Audience: Claude Code, for any task on the application.

Scope of this file. What the application does and what it forbids — and, at §10, how much of it is built right now.

Out of scope. Not the website, which is WEBSITE.md. And not the consultation services: the application is the analytics half of what HappyShip sells (SCOPE.md). Consultation happens outside it, and the application's only connection to it is the CTA at §9.1.

Read SCOPE.md first. Where the two conflict, SCOPE.md governs — raise it, amend the document, then build.

What else this work needs

The shared documents — visual, dictionary, backlog, conventions — are listed in SCOPE.md under Which document to open, and are deliberately not repeated here.

---

1. Product and services

1.1 Analytical services

The four are defined in SCOPE.md. Their boundaries are §9 below; which are built is §10.

1.2 Service legs

The legs are listed in SCOPE.md, which also settles that a carrier is a section inside a leg's rules rather than a leg of its own.

The strategic goal is rate management across every logistics service; last mile is the near-term focus.

1.3 Rate classes

1.4 Two kinds of rate card, two kinds of shipment set

Rates.

• Library cards — stored, owned by an entity. Each carries an internally generated rateID, conditions, and a lifecycle (§4).
• Comparison uploads — a file uploaded to run one comparison. Transient, purged after the run (§6); no rateID, no nickname, no lifecycle.

Shipments follow the same split, but only the transient half is built.

• A comparison shipment set is a file uploaded to run one comparison, purged after the run.
• A stored shipment set owned by an entity would exist to serve invoice audit, which is not built — named here so the symmetry is on record, and not built, stubbed or scaffolded for (§10.2).

1.5 What a phase is

A phase is a decision, not a document. Phases are not folders and not files, and a phase is tied to a leg. Its boundary is described in §10 of this file and nowhere else.

Sections in UX.md and RULES-<leg>.md carry a phase marker in the heading — [phase 1], [not admitted] — so the boundary is visible where it is read. A marker is a label; §10 is the authority. Where the two disagree, §10 governs and the marker is a defect to fix.

Work surfaced during a build is added as a section in the respective document, not as a new file.

Later phases are decided by the product owner, one at a time. Nothing here is a roadmap; the next phase is written into §10.1 when it is chosen.

---

2. Foundations

2.1 Language in the application

SCOPE.md sets the source language for both surfaces and points here for how the application handles it.

Language and time zone are per login, not per entity. Language covers the UI and the PDF report; time zone covers timestamps the interface renders, and a date-only field is a date and does not shift. Two logins in one entity may differ in both.

The browser is the default on first arrival for both; the login's settings govern once one exists. These are not two rules — the first is what a login starts as, the second is what it is thereafter. A user may toggle either at any time, and the toggle writes to the login.

EN and CN in phase 1. EN is the source of truth and the user is told so. Domain terms follow DICTIONARY.md.

No hardcoded user-facing strings. All copy routes through the i18n layer from the first screen. One file per locale, identical keys; adding a locale is adding a file, never touching a screen.

The login code email is always EN. It is sent before a session exists, so there is no login to read a preference from.

Layout consequences of length — button sizing, row wrapping, CJK line height — are brand/STYLE.md.

2.2 Ingest

Template. The HappyShip template, in CSV or XLSX, is the supported path and is the default. Files that resemble the template but do not conform are rejected with a clear reason rather than interpreted. Support for other formats is decided per client, not assumed.

The same template and the same parser serve library uploads and comparison uploads alike. One ingest path, two destinations.

Non-template files are a service, not a code path. HappyShip staff may convert a client's non-standard file into the HS template for that client's approval. This is a value-added service performed offline, and the converted file then enters through the ordinary path of §4.5 — HappyShip enters it, it lands as draft, the client approves by publishing. It adds no ingest code and no second parser, and it is recorded here so nobody builds one.

Column definitions, and the split between what is uploaded and what is entered on the web form, are RULES-<leg>.md.

There is no post-parse edit screen. An entity cannot enter values for lines the file left missing; missing mandatory data is resolved by substitution at comparison time (§9.1).

A card upload reports two distinct things, and they do not behave the same way. Rejections stop the upload. Confirmations do not, and mixing them either blocks what should not or lets through what nobody looked at. The confirmation set and the plausibility bound are RULES-LAST-MILE.md. This is an act of card upload, not of a run; the substitution acknowledgment of §9.1 is a different moment.

One grid serves every service the card declares. Service is a column only in the non-grid charge block, never an axis on the weight-by-zone grid. Which services a card covers is declared after the file parses, not before, and a service the entity does not claim is treated as not offered by that entity. Services within a carrier group usually share by-zone rates, so one grid avoids asking an entity to enter the same 1,050 cells twice, while a Service column on 150 weight rows would be a permanent cost carried for a rare case. Where two services have genuinely different by-zone rates, that is two cards: a card spanning several services is several uploads only when their by-zone rates differ.

2.3 Engineering rules

1. The rate engine is a standalone library with no framework dependencies. Testable without a database or an HTTP server.
2. Explainability is not optional. Every computed charge carries the rule that produced it. A charge that cannot be explained is not returned as computed.
3. Prefer failing loudly over defaulting silently wherever a domain rule is involved.

---

3. Entities and access

3.1 Entities

[OPEN] — current design, revisited once UX work begins.

There is one entity type. Buyer and seller are not stored roles — they describe what an entity is doing at a given moment, and an entity commonly does both.

• Acting as buyer: purchases logistics rates or services, holds L1 rates from its sellers, validates invoices received.
• Acting as seller: sells logistics rates or services, publishes L4 rates, issues invoices to its buyers.

Implementation rules:

• No role field on the entity record, and no role enum anywhere in the schema.
• No separate buyer and seller records, and no separate rate storage per role.
• No role-based branches in the data layer, and no role-based permission checks. Access is determined by ownership and publication (§7).
• An entity holding a card in its own library and an entity uploading a file for one comparison are the same entity doing different things (§1.4).

The entity record holds entityID (§4.1), company name, nickname, country or territory, and the publish authorization flag (§4.4). Company name is free text — it may be anything, including a personal email domain — and HappyShip may correct it later without the entityID changing.

The nickname is a short display form of the entity, capped at 20 characters. It exists because the full company name does not fit every list the entity appears in, and nothing depends on it being unique: it is not the entityID and the system resolves nothing against it. It is not the card nickname of §4.1 — that one is a mask an entity puts on its own card, this one is HappyShip's and sits on the entity, and beyond the word the two are unrelated.

Country or territory, on ISO 3166-1, because separate customs territories are separate rows — Hong Kong, Macao and Taiwan each clear their own shipments and take their own rates, which is why a logistics platform carries them whatever their political status. On a create form the value defaults to the browser's region, which is a starting value the operator corrects rather than a detection, and the screen must not present it as one: a defaulted field that looks authoritative is worse than an empty one.

Then the relationship and commercial fields, all initiated by HappyShip and all optional: contact name, contact phone, contact email, location, HappyShip point of contact, contract expiration date or an explicit "no contract" value, services subscribed, profile status, payment method, currency, internal notes, and a document link.

The record is initiated by HappyShip. Some fields the client may then edit, and some are read-only to the client. The contact fields — contact name, contact phone, contact email and location — are client-editable: a client correcting its own address is the same kind of edit as correcting a phone number. Company name, nickname, and country or territory are read-only to the client and remain HappyShip's to correct, because they identify the entity; location does not. The remaining relationship and commercial fields are read-only to the client as well: HappyShip point of contact, contract expiration date or "no contract", services subscribed, profile status, payment method, currency, internal notes, and the document link.

• "No contract" is an explicit value, not a blank. A blank means nobody filled the field in.
• The value sets for services subscribed and for profile status are not settled. Services subscribed depends on BL-001 in BACKLOG.md. [OPEN]
• The document link is a URL HappyShip pastes, pointing at a document held outside the platform. It is internal-only and never rendered on a client-facing screen. A link may rot and nothing detects it — accepted deliberately, to avoid a second storage path, a MIME allowlist, a size limit, and a retention rule the purge rules of §6 do not cover.
• Nothing acts on the contract expiration date. It is read, not enforced.
• Currency is the currency in which the client pays HappyShip, not the currency a rate card is denominated in. Rate cards are USD in phase 1 and currency never reaches comparison, so no conversion rate and no conversion date exist anywhere in this phase.

The entity record carries no account email. Every address that can sign in is a login record, and that record is the account (§3.2). The contact email among the relationship fields is reference information for reaching someone and grants no access.

An entity with no logins is a normal state, not an incomplete one. It is what every entity looks like between creation and the first address being logged (§3.2).

An entity may be deleted only while it has no logins and no cards. Once either exists, there is history to keep.

3.2 Identity and access

One login, one workspace. A login belongs to one entity. entity_id and login_id are separate columns from the first migration — the entity is the isolation boundary, the login is the identity. Everything in §7 rests on that split.

Access is by invitation only. HappyShip logs an email address against an entity, and that record is the account — nothing is created on first arrival. An address that is not logged cannot log in. A code may be sent for the user's convenience, but it resolves to that address and grants nothing on its own.

Internal access is gated by entity binding. HappyShip is itself an entity. A login registered against HappyShip is internal; a login registered against a client entity is not. The address is never inspected — no domain match, no list of internal addresses, no role field.

Two conditions must both hold: the internal surface was reached (§8.1), and the login is bound to HappyShip. Neither alone is sufficient.

An entity may have several logins, and they all see the same thing. There is no per-login view, no per-login permission, and nothing one login of an entity can do that another cannot. Per-login permissions would be a role system under another name, which §3.1 forbids; if it is ever wanted, that is a scope decision rather than an increment.

What follows from that: any login of an entity can publish its cards, and that act binds the entity (§4.4). A card's nickname is the entity's, not the login's (§4.1). The account balance and coupons are the entity's, shared across its logins (§8.4). Language and time zone are the only things held per login (§2.1).

Recording which login acted is not a permission. Publication and withdrawal record the acting login and a timestamp (§4.4). Every login can still do everything; the record answers who, not who may.

One address, one login, one entity. A person needing both an internal and a client login needs two addresses.

There is no edit on a login's identity. The address is the account, so changing it would move an account to a different person, and rebinding to another entity would move everything that login can see. Correction is delete and recreate.

• Deleting a login ends its session immediately, checked per request rather than at session expiry. Delete is used both for a typo and for someone who has left a company, and only immediate termination serves the second.
• A deleted address is free to be logged again.
• Cards that login published stay published. Publication binds the entity, not the login (§4.4).

Logging an address sends a welcome email to it, and deleting a login sends a notification. Both are sent outside a session — before one exists, or after it has ended — so both are EN, for the reason §2.1 gives for the login code email. A delete-and-recreate correction sends a deletion notice and then a welcome within moments, and the wording of both must be neutral enough to survive that. There is no suppression window.

**The mechanism is ARCHITECTURE.md** — how a session is established, how the entity is bound to it, and what the login flow is. This section states only what must be true of it: the entity comes from the login record, never from a request.

3.3 Serviceability facts

What the requesting entity tells the system about itself for one run — where it ships from and to, what volume, what service level, and whatever else a leg's conditions test. The full set per leg is RULES-<leg>.md.

Three properties matter and are easy to lose:

• Supplied per run, through the web form. Not stored on the entity, not remembered between runs. An entity that ships differently this week says so this week.
• They are the only input the pool is filtered on (§9.1). Nothing else narrows which cards a comparison runs against.
• They are the entity's own claim. Nothing verifies them, and a false claim produces a comparison against cards the entity cannot actually use.

3.4 Ship-from locations

An entity may hold ship-from locations, and the client maintains them rather than HappyShip. Each carries address, city, state and ZIP code. ZIP is required. An entity may have several.

• Not required. "No physical location" is a valid state for an entity.
• The entity's own address is not a ship-from location. The two are separate.
• Each location maps to a region (§4.7), and the ZIP is what resolves it. The seller may declare a region on a location and is not required to; HappyShip audits the declarations and may remap. The declaration is a hint, never the answer — a must-met condition tested against a seller's own unverifiable claim about where it ships from is not much of a test, and resolving the region from the ZIP makes the same condition checkable.
• Phase 1 stores address, city, state and ZIP only. The warehouse service leg will add attributes to this object; they are not built now.

---

4. Rate card properties

RateTable is leg-specific. Templates are defined by RULES-<leg>.md.

A card names the reference standard it is compared against, chosen at entry from master data (§8.2).

4.1 Identifiers

• rateID is unique and generated internally, for a stored card. Users never supply or choose it. It is never reused, with one exception: an ID released by deletion under §4.3 may be reissued, because a deleted card was never used or linked, so it reached no report and nothing can point at its ID, and availability is checked against records that exist. The exception is specific to deletion and does not extend to purge. A comparison upload has none.
• An entity may attach a nickname (mask) to a card — a display alias for its own reference, shared by all of its logins (§3.2). The internal ID remains what the system resolves against. A mask may be duplicated, but among duplicates only one can be active. This is the card's nickname and is the entity's own; the entity record's nickname (§3.1) is a different field, HappyShip's, and the two share nothing but the word.

The ID scheme.

• The safe set is the alphabet: digits 3 4 6 7 9 and letters A C D E F G H J K M N P Q R T U V W X Y, uppercase throughout. It excludes the characters that confuse visually — 0/O, 1/I/L, 2/Z, 5/S, 8/B — and that exclusion is the reason the set is not wider.
• entityID: one free letter A–Z, then 3 from the safe set. Length 4. Randomized and collision-checked at issue, generated by HappyShip at entity creation. It never changes, including when the entity's name is later corrected. It is entityID rather than clientID because HappyShip is itself an entity, and clientID would misname the identifier on HappyShip's own record.
• rateID, shipment set ID and charge file ID: the entityID, a hyphen, a type letter — R, S or C — then 5 from the safe set. Length 11. C is an invoice — a charge file the client uploads for audit. A type letter is fixed and sits outside the random alphabet, so a character excluded from the safe set for visual confusability remains available as a type letter — S is in use for that reason. I is not spent because C already reads as invoice and nothing is gained by using it. Invoice audit is not built (§10.2), so C is reserved rather than in use.
• **HS is reserved as an entityID prefix for HappyShip's own entities**, the last two characters being a country code for a branch office. It collides with nothing, at no cost: positions 2 to 4 are drawn from the safe set, S is excluded from that set for visual confusability, and so no randomly issued entityID can begin HS. This is the same move the type letter makes — a character excluded from the random alphabet stays available for a structured use. Two things it does not change. HappyShip remains a single entity in phase 1. And internal access is unchanged: a login is bound to the entity it is registered against, and the address is never inspected (§3.2). Reserving a prefix allocates identifiers; it grants nothing. The reservation is forward-only — it governs entities allocated from now on, and HappyShip's incumbent US entity predates it, keeps the randomly issued ID it was given, and does not move.
• The type letter is fixed and sits outside the random alphabet, so an ID names what it is without a lookup, and a rateID pasted into a shipment field fails validation rather than a query.
• A suffix is unique within one entity and one type, not globally.
• Stored with the hyphen. Input is uppercased and whitespace-stripped before matching. A stored value not matching the pattern is a defect, not a variant.

4.2 Conditions

A card may carry conditions, and each is marked must-met or prefer-met by whoever sets it. The distinction decides what a non-qualifying entity sees.

• Must-met — a card whose must-met conditions the requesting entity does not meet is excluded from that run. It is not in the pool, and the entity sees only a count and a reason (§7.1).
• Prefer-met — the card enters the pool and is costed, and the result carries an unmet-condition flag. A seller wanting $10k of monthly spend is compared for an $8k buyer, who sees the rate and sees that a condition is unmet.

Prefer-met is lead generation, and is written down so it is not "fixed." A buyer seeing a rate they do not yet qualify for is exactly what drives the consultation CTA. Filtering those cards out would look like a bug fix and would remove the mechanism.

The flag names the condition type and never its value. "Minimum spend not met," never "minimum monthly spend of $10k not met" — the threshold is a term of an anonymized card. Must-met exclusion reasons read identically, so the two cases cannot be told apart by their wording.

RateCondition is evaluated per run against the requesting entity's serviceability facts (§3.3). What a condition can express, and how it is evaluated, is RULES-<leg>.md.

4.3 Lifecycle

Draft, active, expired, archived. An expired card cannot generate a new quotation, but can still compute a comparison or an invoice validation.

A card may be deleted only if it has never been used or linked. Once it has been, it is archived, never deleted. Deletion exists to stop unused drafts accumulating, not to remove history.

4.4 Publication

Public or private. Publication is a flag on an active library card, not a lifecycle state, and the two are orthogonal.

This separation is load-bearing. An entity's own buy rates are active and used for its own comparisons, and must never enter the pool. If activation implied publication, every stored card would be exposed the moment it went live, turning a lifecycle transition into an isolation leak.

• Off — private — by default. A draft cannot be published.
• Two conditions must both hold to publish: the entity is authorized, and the owning entity sets the flag. Authorization is an entity-level setting HappyShip controls, and it exists so that entering the pool can be charged for. The owner's consent is necessary and is no longer sufficient on its own. Separately, a published card must declare at least one region (§4.7). That precondition is different in kind — the two conditions are consent, the region declaration is completeness — so the two-condition rule is not exhaustive of what a card needs before it can be published.
• Clearing the flag withdraws the card from the pool and returns it to plain active, still the owner's to use for their own comparisons.
• The flag clears three ways and they are distinct events. The owner withdraws it. The card expires. Or the entity's authorization is removed, which withdraws every card that entity has published. Only the first is a decision by anyone at the entity.
• Restoring authorization does not republish anything. The owner republishes, card by card. Publication is the consent record, and a card re-entering the pool because an invoice was paid would make the payment the consent rather than the person.
• Setting and clearing the flag record the acting login and a timestamp. Any login of the entity may do either (§3.2), and the act binds the entity either way — the record says which login, not which was allowed. This is the one place a login is recorded, because publication is the consent that makes a card comparable to strangers, and "someone at your company did" is an assertion where "this login, at this time" is a record. It is cheap here and nowhere else: library cards persist (§6), so the event has something to attach to, while a comparison run leaves nothing behind.
• Expiry clears the flag without a login, being automatic. The record distinguishes the two.
• Sharing a card by rateID is not built. Publication is the only way a card becomes comparable to others.
• A UI may derive a single status label — Draft, Active, Published, Expired, Archived — from lifecycle plus flag. Derived for display, never stored.

Card versioning is [OPEN] — how a replacement card supersedes its predecessor, and whether conditions and the publication flag carry forward. Whatever is decided has to hold against the rule above that publication is the consent record.

4.5 Who writes a card

Two paths. The owning entity uploads it, or HappyShip enters it on the entity's behalf — including a file HappyShip converted under §2.2. A card HappyShip enters lands as draft. Only the owning entity publishes, regardless of who entered the data, and that act is the consent record. HappyShip cannot publish on an entity's behalf.

4.6 Output is whole

The system can always export a complete rate card as one file — everything from the upload plus everything from the form. Input is split (§2.2); the artifact is not. This is what preserves the single-file property for audit and dispute. It applies to library cards, which must export complete.

4.7 Regions

Regions are master data maintained by HappyShip (§8.2): one list, each row carrying an active flag, and no region nested inside another — a region holds ZIP prefixes, never other regions. HappyShip may add a region and re-map afterward.

A region holds three-digit ZIP prefixes, single or as a range, and a prefix belongs to one region, so a ZIP resolves to exactly one. Others is where a ZIP matching no prefix lands: it holds no prefixes by definition and cannot be deactivated.

The list is cross-leg, not one per leg — which is what filing regions under platform vocabulary already means in §8.2, a tier defined by not being scoped to a carrier and a leg.

A rate card declares one or more regions, or the value meaning all regions, which is exclusive of any specific region. A published card must declare at least one. The card references a region, not a location (§3.4), and that is deliberate — the declaration is coarse on purpose.

The requesting entity states a set of regions per run, or none (§3.3). A card qualifies where its declared regions intersect the requester's set, or where it declares all regions. Stating more regions widens the pool rather than narrowing it.

The region list as it stands, and the condition's evaluation, are written in RULES-LAST-MILE.md.

---

5. Invoice and shipment properties

[tbd] — filled when audit invoice and track shipments are scoped (§9.3, §9.4).

---

6. Retention

Library cards are stored and persist (§4).

Comparison uploads, computed results and run detail are not. The uploaded file is purged once parsing succeeds; result detail is purged once the report is delivered; there is no run history.

What survives a run is a small set of durable records that hold no rates, no results and no shipment data. Two classes:

• The issued-ID ledger. A shipment set ID and a charge file ID appear on the delivered PDF, so neither is ever reissued, even after the file it named is purged. The ledger holds an ID and the date it was issued. It is not run history and does not make a purged run retrievable.
• The per-entity counters — rates compared, rates published — which survive a run where results do not.

The PDF report is the record. It is emailed to the requesting entity and BCC'd to HappyShip, so a copy persists in email rather than in the platform. It carries the per-run handles of §7.1, since no run record survives to resolve them against.

Purge is configuration, not a hardcoded code path, and defaults to on. The tables carry an owning entity and timestamps from the first migration, so a later phase can enable retention without a rewrite — see §10.1.

The client-facing wording of this is open, tracked as BL-005 in BACKLOG.md. It constrains website copy as well as application copy.

---

7. Isolation and visibility

7.1 Visibility classes

Reference standards are public, and clients are not blinded to them. A client's rates and shipments are always compared against the standard its card names, and that standard is named in output. What qualifies as a reference standard is §8.2.

Everything a client owns is private unless published — rate cards, uploads, comparison results.

Card identities are never revealed in comparison output. Results label each counterparty with an opaque reference code. The standard the card names is identified, being public.

The code is keyed on the run as well as the card, so the same card compared twice produces two unrelated codes. That is what stops two entities discovering, by comparing reports, that they were quoted by the same seller — and it is why the rateID, which is stable and identical for every viewer, is never the label another entity reads.

HappyShip resolves a code by re-deriving it across the pool, not by looking it up. No code is stored, so none needs to be: the codes appear in the PDF, HappyShip holds the BCC'd copy (§6), and a consultation matches the two. The BCC is load-bearing for this and not merely a convenience — without it an entity arrives quoting a code against a run HappyShip has no copy of, and the CTA dead-ends.

What HappyShip cannot do is re-run the comparison. The entity's uploaded rates are gone (§6), so a consultation that means modeling rather than introducing needs the entity to upload again. That is a real limit on what the CTA can promise.

Cards excluded by a must-met condition are not shown at all. A comparison reports how many published cards were ruled out and a brief reason — never a card identity, never an owner, and never a breakdown that isolates one card. A reason names a condition type, never a value (§4.2). A reason specific enough to identify a card is a leak carrying a helpful label.

Publishing a card is a deliberate act by its owner (§4.4), and it is what makes the card comparable to other entities. It does not reveal the card, the owner's identity, or any relationship between the two. Only computed results reach another entity.

7.2 Enforcement

Isolation is enforced at the data layer, not in application code, so a missing filter fails closed rather than leaking. The entity comes from the session, never from a request (§3.2). The mechanisms are ARCHITECTURE.md.

Any path that reads across entities requires an explicit test asserting that entity A cannot read entity B's resources. It requires the positive assertion beside it — that the permitted party can — and a third asserting the bound itself, so widening the reachable column set fails a test rather than passing silently. Both directions or neither counts: a suite asserting only the negative passes when the exemption is broken, missing, or was never built, because the negative is satisfied by the feature not existing, and only the positive tells a correctly bounded exemption from one that has silently failed closed. Those tests extend to the run-time pool (§9.1), where two distinct layers are asserted separately, because they test different mechanisms and merging them hides which one failed:

• Publication state — whether the flag is set at all. A comparison must not surface an unpublished card, a draft, an expired card, or a card whose entity's authorization was removed (§4.4).
• Per-run filtering — of cards legitimately in the pool, excluded for this requester. A card whose must-met condition the requesting entity does not meet must not surface (§4.2).

The content path asserts five things. Positive: an internal session reads another entity's card contents. Negative: a client session cannot, by any route. The bound: the reachable column set is named, so widening it fails a test rather than passing silently. The audit: the action writes its row, a failed audit write fails the action rather than letting it proceed unlogged, the row cannot be altered or deleted through the path, and the application role cannot read the table at all. The boundary: the roster path cannot reach card contents, because two exemptions with no test between them become one mechanism sooner or later.

Neither layer returns card content as opposed to computed output.

A third assertion covers the act rather than a run: removing an entity's authorization clears the publication flag on every card that entity has published, not merely on some (§4.4).

---

8. Internal

8.1 The internal management tool

A separate, HappyShip-only surface. Not a client feature and never exposed to clients. Access is §3.2: the internal surface, plus a login bound to the HappyShip entity.

It is one of two paths that read across entities — the other is the run-time pool (§9.1), which returns computed output only. This one reads card contents and writes on another entity's behalf, which is why it carries its own access control and logs both.

One surface, three exemptions, and they are not interchangeable. The entity roster is every entity's identifying and status fields, the set a list of entities needs: no addresses, no cards, no rates, no internal notes, no document link. The wider seeding set adds the relationship and commercial fields, login addresses, and card metadata — rateID, nickname, derived status, dates — and still reads no contents. The content path reads another entity's card contents, and is the one the paragraph above describes. What separates them is how much of another entity's record a caller ends up holding, which is why one mechanism cannot serve all three (ARCHITECTURE.md, isolation). All three are settled, the content path together with the cross-entity content write, because both are logged and one subsystem records them. The wider seeding set turned out to be two exemptions rather than one, below.

The wider seeding set is two exemptions, not one. The entity record reads one entity at a time: its identifying fields, the relationship and commercial fields, the per-entity counters, its ship-from locations with the region each declares and the region its ZIP resolves to, and its cards' metadata — rateID, nickname, derived status, effective dates. Never card contents. Login addresses read across every entity: the address, the entity it belongs to, and when it was logged, and nothing else. They are separate because one is scoped to an entity and the other spans all of them, and a single bound covering both would be wider than either needs.

What each may write is bounded by its parameter list, as the roster's create is. The entity record writes company name, nickname, country or territory, the relationship and commercial fields, and publish authorization — whose withdrawal clears the publication flag on every card that entity has published (§4.4). It also remaps a ship-from location's region. Login addresses are created and deleted. No card is created here and no card's contents are altered, which is what keeps both out of the content path.

Neither is audited. The audit attaches to reading another entity's card contents, and neither reads them — card metadata is not contents. Of the two writes that reach another entity's records, withdrawing authorization is recorded: a publication event per card, carrying the action, the cause and the timestamp (§4.4). It does not record who withdrew. The event schema attributes an acting login only where the owner acted, and a withdrawal is HappyShip's, so what is on record is that every card left the pool and why — not which internal login decided it. A region remap leaves no record at all. Neither is audited on the rule above, and both are named here so the gap is a decision on the page rather than something inferred from its absence.

What earns an audit row is content, not access. Reading the entity roster is not logged, and neither is card metadata — rateID, nickname, derived status, dates — because neither is another entity's card. Reading another entity's card contents is logged. So is writing on their behalf: entering a card for a client creates something that entity will see and may publish, which changes what they own, and a record of who did that is worth as much as a record of who read.

A row holds who, when, what, on whom, and which card. Who is the acting login's address, snapshotted rather than held as a foreign key — the same choice a publication event makes, for the same reason (ARCHITECTURE.md, schema decisions): login deletion is a hard delete, and a foreign key would either block it or lose the record. What is the action, a content read or a write on another entity's behalf; on whom is the target entity; which card is the rateID. The row is durable and outlives the card it describes, because deleting a card must not erase the record of who read it — it is not run history and §6's purge does not reach it. No client-facing view of these rows exists in phase 1, and whether a client is ever shown them is a later decision rather than an omission.

8.2 Master data and the reference standard

Master data has three tiers, cut by whether a carrier owns it — the cut that decides what adding a second carrier costs.

A reference standard is not master data: it is a card entered through the ordinary card path, kept out of the tiers so nobody builds a second entry route for it.

Which of it earns a maintenance page, and which is code. The test is whether it changes on someone else's schedule — and, where it does, how often. If HappyShip changes it and the change alters engine behavior, it is code. Where FedEx or a government changes it, frequency decides: a weekly fuel table cannot be a deploy, while something amended once a year can be, and is.

Pages: ZIP-to-zone · DAS ZIP lists · the fuel table · region mapping · the metering unit price.

Code: zones 2–8 and weights 1–150, grid shape being a template change · the safe-set alphabet and ID format, since issued IDs would stop validating · the basis vocabulary, each value an engine branch · highest-wins and demand-is-additive, rules rather than values · the three condition types, a fourth silently never firing · the carrier list, a carrier being a complete reference set rather than a row · the accessorial catalog, an open catalog being a door to uncontrolled codes · the charges fuel applies to, a flag on that closed set rather than a list of its own · trigger definitions, each an engine test rather than a value a row could carry · minimum billable weights, which arrive with the trigger that imposes them · the dim divisor default, the fallback the engine applies where a card names none.

A FedEx change to anything on the code list is a deploy, not a data edit — the fuel-bearing list included, which FedEx publishes and may amend. That cost is accepted: for last mile these values were already coded in the template, and keeping them coded is what stops the set drifting.

If adding a row requires writing code before it works, the page is a lie.

Internal staff read the coded rules through a rule report on the internal surface (UX.md) — the accessorial catalog, the charges fuel applies to, the trigger definitions, the minimum billable weights and the dim divisor default, read-only, with nothing on it that edits. It is generated from the constants the engine reads, never transcribed, because a hand-written page describing coded rules is a second master whose failure is silent: the page says 48 inches, the engine says 50, and nothing announces the gap. Staff view these rules; they do not edit them.

Reference standards are defined by HappyShip. There is no limit of one per leg or one per carrier. A rate card names the reference standard that applies to it. FedEx published rates for last mile, or Amazon FBA rates for warehouse, for instance.

To be eligible, a standard must be published by its source. Public is the qualifying test, not a consequence of being chosen: designating a rate as the standard does not make it publishable. A negotiated card or a blended average of what HappyShip has seen cannot be a reference standard, however good a benchmark it would make.

A card in a leg with no public standard has no standard to name, and the missing-data substitution of §9.1 has nothing to substitute for that card. The constraint bites per card, and it is a real one for legs beyond the first, recorded here rather than discovered at build time.

Nothing can be compared until master data exists, so this is not a late feature.

A reference standard is updated by replacing the card: the base grid is annual and accessorials move all year, but the template's per-row dated windows carry within-year history inside the file (RULES-LAST-MILE.md, the charge block), so re-uploading the whole card loses nothing that matters. Published reference-standard cards are therefore mutable where client cards are not — a reference standard is a transcription of a public document, not a negotiated agreement someone stands behind.

A replacement does not reach a report already delivered, and nothing detects it: results are purged and the PDF is the record (§6), so a January report names a standard whose values may have been replaced by March, HappyShip's BCC copy included. This is accepted — the report names the standard as of its run date, HappyShip does not retain what it held, and a run cannot be re-run in any case. It holds because a reference standard is a landmark for rate-for-rate rather than a baseline computed against for money, and it must be revisited if invoice audit is later scoped to compute against one.

8.3 Internal reference views

The rule report (§8.2) is the internal reference view, and its master is a code module rather than a governance file — which is why it serves the application alone rather than both surfaces and SCOPE.md does not carry it, under the anti-drift rule every view here holds to: regenerated from its master, never edited in place, or the page becomes a second one. The handbook was the other one and is no longer on this surface at all — it is generated from the repo and served publicly from a Pages project of its own (SCOPE.md), so it is neither internal nor hosted by the application, and it is looked for there rather than here.

An internal control tower for auditing work performance is intended and is not in phase 1 (§10.2).

8.4 Billing and metering

HappyShip never processes payments between buyers and sellers (SCOPE.md).

Billing covers HappyShip's own clients for HappyShip's services. Stripe is the payment path. ACH and wire are expected later and are managed manually. An entity sees its own account balance; the internal team sees every client's.

Coupon codes are stored value in USD. Single-use, expiring three months from issue. An entity may hold several; they draw down first-expiring-first. Invitation and coupon codes are single-purpose and independently redeemable. Invitation is §3.2.

Metering is per run. The unit price is master data set by HappyShip, defaulting to $0 in phase 1. The deduction path is real and runs on every job regardless of price, so the block-at-exhausted-balance state is exercised rather than stubbed. What is unsettled is the price, not the mechanism — plan structure, pricing and entitlements are BL-001 in BACKLOG.md.

**What HappyShip charges and how it is computed is RULES-HS-CHARGES.md.**

---

9. Product functions

Behavior, outputs, and calculation belong in RULES-<leg>.md. This section states only the boundaries. SCOPE.md names all four functions; §10 says which are built.

9.1 Compare rates

Two comparisons.

• Rate-for-rate — when two cards have exactly the same structure, the numerical differences can be normalized and compared. The result is "who is cheaper for each line item."
• Shipment-cost — when an actual shipment profile is presented, each card produces the cost for that shipment set, whether or not the two cards share a structure. The result is "shipping cost."

One upload, one run. No appends and no accumulation.

The run-time pool. A comparison runs against every published card, filtered by the requesting entity's serviceability facts (§3.3) against must-met conditions (§4.2). The pool is computed fresh for each run and does not persist. No stored relationship governs who compares against whom, and a newly published card is comparable immediately; there is no review step.

Comparing against your own card. An entity using manage rates may run a comparison against one of its own stored cards, by reference, and against the standard that card names. A comparison never promotes a comparison upload into a stored card.

Missing mandatory data. Where an uploaded card lacks mandatory data for a line, the standard the card names is substituted for that line; the line is not excluded. The entity acknowledges this at upload through a required checkbox, shown alongside the count of affected lines. Every substituted line is marked in the report. Results also report the count of the entity's own priced lines that exceed the standard the card names. The alternative considered was excluding the line from both sides. Substitution is the product owner's decision.

**The output surface is UX.md**, constrained by §7.1.

9.2 Manage rates

Lite — upload, conditions, lifecycle, publication (§4). Conditions are evaluated per run, so lite is not "no rules." A client's rates are stored in the HappyShip database once standardized.

Full — derivation of sell rates from buy rates, L1 to L4. Not built. Its rules are unwritten: margin structure, rounding, minimums and accessorial carry-through are all undecided, and until they are written no estimate of the work is meaningful. [OPEN]

9.3 Audit invoice

Not built. To be scoped. [OPEN]

9.4 Track shipments

Not built. To be scoped. [OPEN]

---

10. Phase 1

10.1 Built

A subset of leg 1. FedEx Ground and Home Delivery only, US continental 48, zones 2 through 8. Two functions: compare rates, and manage rates (lite).

This is also the phase that builds the cross-leg and cross-service foundations, which is why the table groups them.

Grouped, not sequenced. Build order is ARCHITECTURE.md's build sequence; this table says what, not when.

Retention shaping is admitted deliberately, because it would otherwise read as the scaffolding §10.2 forbids. Phase 1 purges.

10.2 Not built

Anything not listed in §10.1 is not in scope. Do not build it, stub it, or scaffold for it. Stop and ask — and only start work on it after it has been added to §10.1.

One narrow exception: a screen may carry a placeholder for work that is not admitted, under all of these conditions. It is screen-only: no column, no field in any payload, nothing stored, nothing read. It is greyed, not selectable and not clickable. It carries no value set — a label, never a list of options, because a list is a decision nobody has made. It is visibly marked as not in scope. And the deferred work it names is recorded — as a BACKLOG.md row, or by being named in the not-built list below — so the placeholder is a reminder of something recorded rather than the only record of it. Either satisfies the condition, because the condition exists for the record and not for where it sits, and the not-built list is the stronger record of the two.

The exception is drawn this tightly because an inert label forgets nothing and enables nothing, while a column, a value set or a live control is the scaffolding the rule exists to prevent. Anything failing any of those conditions is not a placeholder, and the rule applies to it unchanged.

Named explicitly, because each is described somewhere and could be mistaken for admitted: derivation of sell rates from buy rates (§9.2) · invoice audit (§9.3) · shipment tracking (§9.4) · stored shipment sets (§1.4) · card sharing by rateID (§4.4) · the internal control tower (§8.3) · any leg but the first and any carrier but FedEx (SCOPE.md).

This boundary is the application's alone. The website has its own at WEBSITE.md; neither admits nor forbids anything on the other.

Audience: Claude Code, when a task touches structure.

Scope of this file. How the parts fit together and where new legs attach. Not a schema mirror — the database is the source of truth for schema, and this file records what is not visible from reading the code: why the boundaries sit where they do.

Read SCOPE.md first, then APPLICATION.md. SCOPE.md governs the shared ground — what HappyShip is, the service legs, the source language, and where a commit goes. APPLICATION.md is the authority for the application: what it does, and what the current phase builds. This file says how that is achieved. Where it conflicts with either, they govern and this file is what changes.

---

0. Status

Written before implementation, and parts of it have been overtaken since. The schema gap was filled from what step 0 built (§4.3); the rest of §13 is still open. Sections marked [OPEN] are unresolved — do not treat one as permission to decide; stop and ask. [UNBUILT] marks something decided but not yet built, and closes when it is.

---

1. Shape

Four layers, one deployable service.

No microservices. No message bus. One service, one database, one object store.

---

2. Stack

Why Python. The engine is numeric and rule-heavy, the XLSX libraries are strongest here, and pricing rules read close to plain sentences — which matters because the product owner reviews logic, not implementation.

Why server-rendered, and why Flask. Every screen is a document — tables, forms that submit, uploads and downloads, a dashboard looked at once and then purged — so a separate front end would be two codebases in two languages for the same screens, with an API contract neither half can change alone: roughly double the build, and more than double the cost of a change, because one new field moves a response shape, a type, a component and everything that read the old shape. Flask rather than FastAPI or Starlette, because both are async, which buys nothing over a synchronous driver in front of a CPU-bound engine and costs a boundary through every handler, and FastAPI's validation and generated OpenAPI describe JSON bodies that no longer exist here. This is the reversible direction: a screen that later needs to behave like an application can be built that way on its own, where React everywhere and then simplifying is a rewrite.

Vendors are named in §7 and are deliberately replaceable. Nothing above the vendor line depends on which vendor is chosen.

---

3. The rate engine

A pure function. Given a shipment and a rate card, it returns computed charges. No database access, no network calls, no framework imports. Reference data is passed in, never fetched.

This is the one hard architectural constraint in the system. It exists so the engine can be tested without infrastructure, and so its correctness can be established independently of everything built on top of it.

The template parser (§9) is under the same constraint, for the same reason, and a test asserts it for both: neither module imports a database driver, a network client or a framework. The rate-for-rate engine built in step 0 is the first of the engine's functions; the parser reads a file and returns rows and findings, and nothing in it writes.

Explainability is not optional (APPLICATION.md, engineering rules). It is what makes the engine's output auditable rather than merely correct.

Selecting which rate card applies happens outside the engine. A single upload or invoice may span multiple rate cards. Resolution rules live in RULES-<leg>.md.

---

4. Data

4.1 Database vs object storage

Files never touch local disk. Uploads go to object storage on receipt. Hosted filesystems are ephemeral, and a file written to disk disappears on redeploy. This is one of two constraints that make the local-to-hosted move trivial (§6).

This is a rule about the code path, not about the machine. The application always writes through the object-storage API; where that API points is configuration (§6). Local development points at the object store's free tier — no cost, no emulator, and the same code path as production. It does not mean "no local development"; it means no ./uploads directory.

Results. A costing run produces one result record per shipment per scenario.

Dashboards sort, filter, and display the full result set, so result detail lives in Postgres, indexed for those queries. Object storage holds the generated file for download, not the queryable copy. Results land in Postgres during a run and the dashboard reads them from there; they do not survive delivery.

Because comparison data does not survive a run, the database is small and steady, and library rate cards are the largest permanent thing in it.

Purge triggers. The comparison upload is purged from object storage once parsing succeeds. Result detail is purged from Postgres once the report is delivered. Whether purge is configurable, and what it defaults to, is APPLICATION.md.

Library cards are exempt from purge — they are stored and persist by design (APPLICATION.md, rate card properties).

4.2 Limits

Dataset ceilings and append behavior no longer apply in phase 1 — there is no dataset model, and each run is one upload (APPLICATION.md, product functions).

A per-upload row limit is still unset. [OPEN]

4.3 Schema decisions from step 0

The database is the source of truth for the schema; the migrations under app/db/migrations/ carry the tables, keys and constraints, and the rule each implements is a comment beside it. This section records only what a reader could not recover from them: why the boundaries sit where they do.

Entity scoping and forced row-level security sit on every table, including the public ones. Regions, the reference-standard designations and the standard's own rows are readable by every entity, and they still carry an owning entity (HappyShip) and forced policies. The alternative, an unscoped table for public data, would be the one table a missing filter could not fail closed on, and the rule that every table carries an owner is worth more than the exception. Forcing binds the migration role too, so the owner cannot be the leak. Two consequences follow, for whoever writes the next migration: a data migration that touches rows must bind its transaction to the entity that owns them, since the migration role sees nothing otherwise; and creating or acting on an entity today is done by a session bound to that entity, until the internal tool's separate logged path exists.

A reference standard is a HappyShip-owned rate card plus a designation naming it, not a table of its own. Its rows have exactly a card's shape, a client's card compares against it cell by cell, and the parser validates a filled template against its structure, so a parallel table would be the same shape twice. The cross-entity read this needs is an explicit, tested policy on the card and row tables, opened only for a designated card, read-only, and beside the two surfaces §5 names. It is not an exception to isolation: an undesignated card of HappyShip's is as private as anyone's, and a test asserts both directions.

A login's key is its email address, and a publication event snapshots that address rather than holding a foreign key to it. The address is the account (APPLICATION.md, identity and access), so nothing else identifies a login. Login deletion is a hard delete and a deleted address may be logged again, while the publication record must keep "this login, at this time." A foreign key would either block the delete or lose the record; the snapshot does neither.

Charge rows carry a sequence; per-zone charge rows do not. Structure is which charges exist, in what order (RULES-LAST-MILE.md), so the order is part of a standard's identity and must be stored, and one charge code recurs across dated rows and brackets, so the row itself does not carry its position. The four per-zone rows are one row per code in an order the doc fixes, so the code alone places them.

The fuel rate is scoped by service family — Ground and Home Delivery share one percentage while express is jet-fuel-based — so the table carries that column before a second carrier arrives rather than after.

Every row of the fuel series carries its effective date from the first migration, since every read of the series is by governing date and a row without one cannot be placed in it.

The 24 charge codes are a check constraint rather than a table, deliberately. The set is code on purpose (APPLICATION.md, master data and the reference standard): an open catalog is a door to uncontrolled codes, and a constraint a deploy is the only way to widen is what stops the set drifting. A second carrier does not weaken this — it arrives as its own coded set rather than as rows someone types into a catalog, so the constraint is not the thing a second carrier forces open.

[UNBUILT] The rule report will read these same constants (UX.md) — generated from them rather than describing them, so the constraint, the engine and the page a staff member reads cannot disagree. It arrives at step 5.

Migrations must apply, in order, to an empty database. The test fixture drops and recreates the schema and applies every migration, then seeds, rather than truncating and re-seeding: a truncate cannot restore rows that a NOT NULL data migration populated, since the seed that re-inserts them predates the column. The first data migration failed on a fresh apply and had been masked on the dev database, where the seed had already run before the migration existed; the shape will recur whenever a migration depends on seeded data, and the fresh apply is the only check that catches it.

---

5. Isolation

APPLICATION.md requires isolation at the data layer so a missing filter fails closed. Four mechanisms, in order of what they buy:

1. Every table carries an owning entity, from the first migration. This is the single most expensive thing to retrofit — it touches every table and every query.
2. Postgres row-level security. Policies live on the table, not in application queries. A query missing its filter returns nothing rather than everything.
3. Entity comes from the session, never from the request. Not a URL parameter, not a body field. Set once at authentication; every query inherits it.
4. Adversarial tests, at the data layer and the view layer. A view cannot skip scoping by being written: the lifecycle that binds an entity runs before every request, so there is no per-view opt-in to forget, and a test asserts every rule in the url_map is served under it. What the tests must assert is APPLICATION.md. Nothing runs them automatically. The repo has one workflow and it runs no tests — it regenerates the handbook (SCOPE.md). So the suite gates whoever runs it and nobody else, and a commit reaches main with no test gate, including the bot's. A workflow that runs the suite on every push is wanted rather than built. [OPEN]

Two surfaces read across entities, and no others. The mechanisms beneath them are listed rather than counted, because the count has been wrong twice — once when the login and session lookups arrived, once when the roster did — and a list gains an entry where a number needs correcting. The list carries no count for the same reason, that being the third time:

• The reference-standard policy. A card designated as a reference standard, and its rows, are readable by any session bound to an existing entity, because reference standards are public (APPLICATION.md, visibility classes) — explicit, read-only and tested in both directions (§4.3).
• The login and session lookups (§10), which no binding could answer, because resolving them is what produces one.
• The roster functions, which return the entity list and create and delete entities (APPLICATION.md, the internal management tool).
• The entity-record functions, which read and write one entity's record at a time — its fields, counters, ship-from locations and card metadata, never contents (APPLICATION.md, the internal management tool).
• The login-address functions, which read every address across every entity, and create and delete them.
• The content path, below, which is the only one that logs. [UNBUILT]

What bounds an exemption is the shape of what it returns, never a predicate. A predicate bounds which rows and says nothing about which columns, so a role-scoped policy with USING (true) on a table yields every column of every row — the internal-only ones included — and nothing stops a caller selecting one nobody intended. That is a convention, not a ceiling. Every cross-entity exemption is therefore bounded by its return shape — a definer function's return type, a view's columns, or column grants — so that widening it takes a migration somebody can see. The two lookups above are an instance of this rule rather than an exception to it: each takes one value and returns one entityID, and the signature is the ceiling.

The internal management tool (APPLICATION.md) goes through a separate, logged path — never a flag on the normal path.

[UNBUILT] The audit write happens inside the function that returns the contents, in one transaction. Reading without logging is not possible because they are one operation, and a failed audit write fails the read. That is structural rather than procedural: nobody has to remember a log line, because the only path to another entity's card contents runs through the thing that records it. It meets the bounding rule in the ordinary way — the function's return type is the ceiling — and the write path is the same shape, the audit row landing in the transaction that creates the card.

[UNBUILT] The application role will hold INSERT and not SELECT on the audit table. It writes and can never read back, which is what makes the table an audit rather than a log the audited surface can read: an internal session can be made to write a row and cannot be made to show one. It inverts the lookup role — that one exists so the application can read what it otherwise could not, this one so it can write what it cannot. Reading the audit is out of band, by whoever holds the migrate credential. Every table carries an owning entity, and here that is the acting entity, HappyShip, because the action is HappyShip's; the target entity is a separate column doing a separate job, and merging the two would file the row under the entity it was written about.

The run-time pool (APPLICATION.md) is the second. It is not an exception to the isolation rules there: it reads only cards whose publication flag is set, and it returns computed results, never card contents. The flag is what the pool tests, never the owner's act. The pool distinguishes none of the ways the flag came to be set or cleared, so a card withdrawn because its entity lost authorization is as invisible as one the owner withdrew. The adversarial isolation tests required by APPLICATION.md extend to it.

Identity is not authentication. Entity scoping exists from step 0 and sessions from step 1; sign-in exists from step 2 (§8). Step 0 runs against a seeded entity with nobody logging into it, and step 1 runs against a real session that nobody has signed in to.

---

6. Portability

Two constraints make the hosting choice reversible. Both cost nothing now and are expensive to undo:

• All configuration through environment variables. No connection strings, paths, or keys in code.
• All files in object storage. Never the local filesystem.

Additionally: run the same Postgres major version locally as in hosted environments, and confirm any extension exists on the target before depending on it.

The move from local to hosted is a few hours' work — provision, dump and restore, repoint environment variables, deploy. The difficulty is never the move; it is data you cannot afford to lose. Move before there is data worth protecting (§8).

---

7. Hosting

Selection rule: every vendor must have a usable free tier and a reasonable paid tier on the same platform. Start free, upgrade in place, never migrate. A vendor that is cheapest at zero but forces a move at scale is disqualified — the migration costs more than the savings.

Each row is one platform from free through production. Upgrading is a plan change, not a move.

Auth is not a vendor and has no row: passwordless sign-in, sessions and entity binding are application code against Postgres (§10), so there is nothing to select, no free tier to outgrow and no user-count threshold to watch, and what auth stores is covered by the Postgres row above.

The application needs no static host of its own, and that is deliberate. It renders its own HTML and serves its own assets from the one service of §1, so nothing of the application's is deployed apart from it and there is no second thing to point a domain at. Two static surfaces do exist beside it and neither is the application's, which is why neither takes a row above: the public website, SCOPE.md's to name and WEBSITE.md's to describe, and the handbook (SCOPE.md). Both sit on Cloudflare, already a named vendor here, so neither adds a platform to select or outgrow.

Prices and tier limits change; verify before committing.

Free-tier compute sleeps when idle. Cold starts are acceptable while testing on internal data and not acceptable once an external user might arrive, so compute is the first upgrade — at the §8 gate.

Point-in-time restore is the one thing not to economize on. Free-tier Postgres generally lacks it. Acceptable for data that can be regenerated; not acceptable once real client rate cards are stored.

Do not introduce Kubernetes, microservices, additional datastores, or a message broker.

Even with upgrade-in-place, §6's portability constraints hold. They are what makes the selection rule a convenience rather than a dependency.

---

8. Build sequence

All steps deliver phase 1 as defined in APPLICATION.md.

The internal portal moved ahead of everything but the schema. Nothing can be seeded without its screens and nothing can be compared without seeded data. Step 0 still runs against a seeded entity with nobody logging into it (§5); step 1 no longer does, for the reason below.

The session moved into step 1 with the screens, because the two were waiting on each other — sign-in authenticates against pre-registered addresses, nothing can be registered until the logins screen exists, and that screen needs a session to know which entity is acting. What identifies the acting entity is what the row-level security policies read (§5), so a stand-in for it is not cosmetic: it reaches every query written in step 1 and every test around them. Building the seeding screens against a real session and real entity binding from the first line costs less than threading a placeholder through them and pulling it back out in step 2.

The dev-only route that mints a session is temporary work toward admitted work, not scaffolding. What APPLICATION.md's not-built rule forbids stubbing and scaffolding for is work phase 1 does not admit, and auth and login are admitted — so the rule does not reach this, and step 2 carries the obligation that makes it temporary rather than permanent: the route is deleted when sign-in lands.

The route sits inside the entity-binding rule rather than being an exception to it, which is what lets it exist inside the security boundary at all: it supplies an address, finds the login record and mints a session the ordinary way, skipping the code and nothing else, so the entity is still read from the login record and never from the request (§10). It cannot run before a login exists, so the first internal login is seeded alongside the HappyShip entity — the same seed, one row wider.

The first cut is the seeding screens only — create an entity · log an email address against an entity · upload a carrier-published card and name it a reference standard · enter a card on an entity's behalf · the values the card fields read (carrier list, entity list, currency, weight unit, ships-from regions) — not one tier and not all master data, so what step 1 owes each is that it is present, not that it has a page (APPLICATION.md, master data and the reference standard) · authorization to publish. Out of it: coupons, payments, activity metadata and the rule report, all of which stay at step 5. The HappyShip entity is a seed rather than something created through the portal, because internal logins bind to it.

The handbook is not in this sequence at all, and did not move within it. It is built, deployed and read with no application running (SCOPE.md): no step waits on it and it waits on none. It was listed at step 5 while it was a screen of the internal tool, and stopped being one.

Auth moved ahead of the library and comparison work. Self-serve card upload is an authenticated act by a card's owner (APPLICATION.md), so auth and entity binding cannot sit after the steps that depend on them. Email delivery arrives with auth, which is where email infrastructure first exists.

Authorization arrives before the billing it exists to serve, and that is deliberate. It is a setting from step 1, while what makes granting it a paid decision waits for Stripe at step 6. Step 1 asks only whether the flag may be set, never why — which is what lets the pool run locally, before there is anything to charge for entering it.

Report generation lands with the comparison steps, at step 3.

The gate

Steps 0–4 run entirely on the product owner's own data, on the local machine, at no hosting cost. "Local" here means no deployed compute and no paid tier — files still go to the object store's free tier per §4.1, never to local disk.

Before step 5 and before any external user, three checks:

1. Is the engine right? Real invoices, line by line, matching. If this fails, nothing downstream matters.
2. Is the template usable by someone else? The owner will fill it correctly because he knows what every column means. That is exactly what an outside user will not do.
3. Does the output say something the reader did not know?

Expect ingest rejection handling to get its first real test after the gate, not before — internally produced files are unrepresentatively clean.

Step 0 is the load-bearing step

Its cost is not code volume; it is writing down the calculation rules precisely and verifying output against known-correct invoices. If those rules are ready when step 0 begins, the step holds its estimate. If they are discovered through wrong invoice totals, it does not.

---

9. Ingest

Single sheet. HappyShip supplies the template. Which formats it comes in, and what happens to a file that does not conform, are APPLICATION.md. An XLSX with more than one populated sheet is rejected, so the two formats stay interchangeable and the parser has one shape to handle.

The template is generated from a reference standard, with structure locked to it (RULES-LAST-MILE.md). The parser knows the expected structure before opening the file, so conformance is a comparison against that structure rather than an inference from what the file contains.

Input is split between the uploaded file and a web form. Which fields go where is decided by the product owner, not derived. The split is recorded in RULES-<leg>.md, and those two are the whole input surface.

The file is a grid for humans; the database is one row per zone, weight, and service. The parser transposes. Nothing downstream sees the grid.

Template column definitions live in RULES-<leg>.md.

---

10. Auth

Passwordless — a verification code emailed to a pre-registered address (APPLICATION.md, identity and access). No stored passwords, no reset flow, nothing to breach.

Entity binding. The entity is bound at session establishment, read from the login record — never from the request (§5).

Session length. Two limits, and the session ends at whichever arrives first. An absolute lifetime of 7 days from establishment, which no amount of activity extends. And an idle timeout of 24 hours, which every request resets, capped by the absolute — an active user is signed out at 7 days, not sooner.

The cookie is persistent, not a session cookie, so closing the browser does not end the session.

Sign-out ends a session, and it is the only way a user ends their own (UX.md, access).

Why the limits are this long. Re-authentication here is an email round trip, so every expiry is one more chance for a delivery failure to sit between a client and their own work — and email is infrastructure rather than a convenience, not a property this design can shorten its way out of (§10.1). What a short session would otherwise protect against is a session outliving the right to it, and that is already handled by a stronger mechanism than a timer: deleting a login ends its session immediately, checked per request rather than at expiry (APPLICATION.md, identity and access). Shortening these limits therefore buys little, and is paid for in email round trips.

The login code email is always EN (APPLICATION.md). The code-sending path has no locale to resolve against (§11).

Consequence: email becomes infrastructure rather than a convenience. Every login depends on delivery, which is stricter than password auth where email only matters at reset. It is stricter still now that email also carries the deliverable (§10.1).

10.1 Email carries the deliverable

Email is no longer only the login path. It is infrastructure, not a convenience, and five things depend on delivery: the login code, the welcome email when an address is logged, the notification when a login is deleted, the PDF report of a completed run, and the notification to an owner when HappyShip has entered a card on that entity's behalf (APPLICATION.md). The report is also downloadable in-session.

With no retention of comparison uploads or results (APPLICATION.md), a failed delivery leaves the entity with nothing to come back to and forces a paid re-run.

---

11. Building for translation

The language policy is APPLICATION.md — which locales, per-login selection, no hardcoded user-facing strings, and the login code email always EN. This section is only what that policy costs architecturally.

CN is in from step 1, not added at the end. Layout breaks appear per screen; retrofitting means re-reviewing every screen.

The step 1 portal follows the login, since a step-1 session carries a login record and a login record carries a language preference; the browser rule governs only before a session exists, which in step 1 means before the dev route runs (APPLICATION.md, language in the application).

Length is the constraint, and buttons are where it bites. Buttons are fixed-position elements in a row, so one long label displaces its neighbors. Paragraphs reflow and tables wrap — neither is a structural problem.

Detailed styling rules belong in brand/STYLE.md.

---

12. Known future work

Recorded so it is not rediscovered as a surprise. None of this is phase 1. This section holds the architectural consequences of work not yet admitted, not deferred decisions — those are BACKLOG.md.

Cross-carrier zone normalization. A FedEx zone 5 is not a UPS zone 5. Rate-to-rate comparison across carriers needs a common basis — a normalization problem one level above the grid. Does not bite while phase 1 is FedEx-only.

Legs beyond last mile. Warehouse, drayage, and global mile attach at the rate table: the charge model is shared, the table shape is leg-specific.

Higher upload volumes. Present limits are set well below what the design supports. Raising them affects worker memory and result handling, not structure.

---

13. Gaps

An open decision lives in BACKLOG.md or as an [OPEN] in the document that owns the thing being decided. This table holds the architectural consequence of each, never the decision itself.

Process lives in tiers, by ownership:

• CLAUDE.md — universal working rules, every project. Part A (behavioral), Part B (code discipline), Part C (shared processes).
• SCOPE.md — describes the project and lists the governance files it requires. Each project declares its own type, required docs, and branch/PR discipline here.
• XYZ.md — project-specific files, in the repo.
• Google Doc SOP — processes done entirely by the human. A reference, not a source of truth.

Precedence. SCOPE.md governs project-specific matters. A rule that names SCOPE.md as its own override is not a conflict. Where the two genuinely conflict, stop and ask.

Part A — Behavioral (applies to all work)

Read the governance files first. Read SCOPE.md at the start of every task — in Code, the version on origin/main; in a Claude chat, the Claude project-folder copy, which is uploaded by hand and lags whatever has landed since. Treat its line-1 stamp as a claim, not a fact: where the task turns on what the file now says, the sync audit resolves it before the work starts. Read CLAUDE.md as well when the task touches the repo, governance, or the backlog: Part A is already in my global settings, so Parts B and C are what opening the file adds. Then read only the docs the task actually touches, from the set SCOPE.md lists — not the whole set. Read once per chat at the first task, and again after a prompt I ran lands.

If a required governance file is missing, stop and ask. If SCOPE.md itself is missing, ask whether it was not uploaded or this is a new project (Part C, start a new project).

Discussion mode by default — wait for the go. Do not write prompts, code, or files until I explicitly say so. Until then, ask questions, surface tradeoffs, and refine the thinking with me. Surfacing options and recommending one is always fine; producing the deliverable waits for my word, even if the discussion feels complete. Do not draft until all your own questions are answered.

Be concise and direct. Keep responses focused. Push back when you disagree. Do not over-explain your reasoning; I will ask if I want more.

Match the mode. Not every chat is about coding. Do not default to coding-oriented output unless the chat is about building or modifying code. If unsure which mode we are in, stop and ask.

Don't guess. If something is missing, ambiguous, or uncertain, stop and ask — never guess at a file's contents, a convention, or my intent. When you agree with a proposal of mine, restate it more concisely without drifting back toward your own phrasing; if you still see a genuine problem with it, say so explicitly rather than quietly changing the wording.

Flag once, then comply. Where something conflicts with a governance file or an earlier decision, say so once in the same chat, then do what was asked; do not re-argue a point that no longer changes the outcome. This is for a conflict you can decide. Where proceeding would be a guess rather than an argument — a copy disagreeing with the repo, a missing governance file, an ambiguous ask — the stop-and-ask rules govern instead. Complying is about the work, not the file: where what you asked for contradicts a governance doc, the amendment lands in the same batch rather than being left behind.

Don't add what wasn't asked for. Do not invent, extrapolate, or draw conclusions on your own, and do not write them into any governance file without my go. Do not invent local folders — ask where temporary files go.

Ask for content first. If I say I am sending content and nothing is attached, assume I hit send early. Stop and ask — do not fill the gap with a speculative response.

State a limitation only where it qualifies the answer, never as a standing disclaimer.

Write US English, unless SCOPE.md sets otherwise. Identifiers, file paths, CSS custom properties and quoted third-party text keep the spelling they have, because changing them changes what they refer to. So does a file authored in another repo and synced in — it must stay byte-identical, so a British form there is corrected at its source, never here.

The repo is the source of truth. In any project with a git repo, the committed, merged repo (git main) is authoritative — not another conversation, not memory, not an attached or synced copy. If attached or synced project files, or claims about what was decided in another chat, conflict with the repo, flag the conflict, stop, and ask.

Prompts are for Claude Code. Where the project uses Code, a prompt I ask for is written for Code to execute — clear, scoped, based on what we discussed. Always in a code block so I can copy-paste it. If you amend a prompt already written, regenerate it in full.

Show a draft in its own format. When you show me a draft or a mock, render it as the thing it will be — a governance doc as a markdown file, a page as HTML, a deck as slides — not as prose describing it or a code block quoting it. The exception is anything whose destination is a paste buffer rather than a file: a prompt for Code stays in a code block. Where the format cannot be rendered, say so and pick the nearest one.

One prompt at a time. Where I have to run steps in sequence, give me the first, wait for the result, discuss if needed, then the next.

Handoffs are for a new chat. Suggest one when a conversation drifts, runs long, or a session closes. Write the handoff in a paste-back code block, never as another document.

Governance files are not permanent. When a discussion produces a claim that conflicts with a governance file, amending is a decision and waits for my go: the rule and its reason go into the doc that owns them, and the alternatives and rejected options go to the decision record where SCOPE.md declares one. Where it does not, state it in the chat. Raise it, agree the change, amend the file — then build. What must not happen is building to the newer decision while a document still says something else, because the next session reads the document.

Part B — Code discipline (projects with a git repo)

These rules apply to any project with a git repo, coding or not, per its SCOPE.md. Clauses referencing origin/main, pushing, or PRs apply only where the repo has a remote; the rest apply to local-only repos too.

**Read governance docs from origin/main.** Always git fetch origin first, then read the committed version (git show origin/main:<file>) — never the working tree, never the synced Claude project folder. This governs a file's contents. Reading a folder copy's line-1 stamp for the sync audit below is not covered by it, and neither is a chat reading the folder copy because it has no other.

Sync audit. At the start of every repo-touching task (pure discussion turns don't need it), line 1 — version, date, line count — is compared between origin/main and the Claude project-folder copy. Line 1 only, unless I ask for more. Audit whatever governance docs SCOPE.md lists, plus CLAUDE.md and SCOPE.md themselves, plus any stamped non-.md governance file the project keeps (e.g. STYLE.css); never assume a fixed list. It takes both of us, because neither side can read both. Code reads origin/main and cannot see the Claude project folder, which is a manual upload outside the repo path; a chat reads the folder copy and cannot read git. Each supplies the half it can read and says which half it is — the prompt carries the chat-side stamps into Code, or Code's output is carried back. A report covering one side is not an audit. Where the two differ, the higher version is current — flag it and sync to that version.

Three pairs of copies, three dispositions — do not read one for another. origin/main ↔ the Claude project folder is the sync audit above: each side reports its half, and the higher version is current. The repo ↔ an attached file, or a claim about what another chat decided, is "the repo is the source of truth": flag, stop, ask. A project repo's copy ↔ the disk master is Part C's CLAUDE.md reconciliation: sync to the later version automatically and report it. Only the middle one stops the work.

Verify the git identity before pushing. Where the repo has a remote, run gh auth status at the start of any task that will push, and confirm the active account matches the GitHub account declared in SCOPE.md. gh auth switch and gh auth login change credential state for every project on the machine, so Claude never runs either — on a mismatch, stop and give me the exact command.

Governance docs go direct to main. Every .md governance doc listed in SCOPE.md is committed straight to main and pushed immediately. No branch, no PR: they carry no styling or page logic. Where an ungated handbook renders them, a bad edit does reach a public page — accepted deliberately, because the risk is content only and the fix is another direct commit. Push is the finish line.

Publicly-served governance files are the exception. Where SCOPE.md declares a governance file publicly served, an authored change to it keeps branch and PR discipline. A byte-identical copy of content already reviewed in the repo where it was authored is not an authored change and goes direct to main — unless the receiving repo deploys from main, where it keeps branch and PR on the receiving side.

The discipline covers an authored publicly-served file, never a generated one. A generated file is authored nowhere; what earns branch and PR is the generator and the sources it reads, which already have it. Two commits, both direct to main: the sources first, then the file regenerated against them and committed on top. Never one commit, never an amend.

Governance docs carry a version stamp. Line 1 of every .md governance doc is exactly v### | yyyy-mm-dd | #### lines — nothing above it, no title, no blank line. A file whose format forbids bare text at the top (e.g. STYLE.css, which must open with a comment) carries the identical stamp on the first line of its opening comment block. Bump v### on every substantive change — once per commit, not per revision. An uncommitted draft keeps the number it will carry when it lands, however many times it is revised beforehand. The date and line count are read from the machine at the moment of writing (date +%F, wc -l) — never hand-typed, never copied forward. The date is the machine's LOCAL timezone. If machine time returns something implausible, stop and ask. Version counters are per-file and independent; a constant offset between two files is expected and is not a defect.

Correcting a claim means correcting what justified it. Amending is three passes, not one: the claim, the sentences saying why the doc says it, and what the doc concluded from it — which can sit paragraphs away and be further from true than the premise. A rewritten paragraph is not evidence that the sentences inside it were re-read. After the edit, search the section for because, since, which is why, so that, the reason, and for anything beginning this means or so there is no. Each hit either still follows or does not.

Protect main when it deploys from main. Where the project deploys from main, anything on the branch-and-PR side takes one feature branch per task, branched from an up-to-date main → commit locally as you work → push the branch → open a PR only when I ask → merge → clean up. Where the project does not deploy from main, commit directly to main and branch only for isolation on risky work.

Direct to main: anything the build validates before it publishes, plus governance docs.

Branch and PR unless I say otherwise: anything on a deploying surface that nothing validates — the viewer, the build script, stylesheets. The PR is for the preview deploy and the single revert unit, not for the review.

Public or private makes no difference. If it isn't obvious which side a file sits on, the test is whether a bad commit reaches readers with nothing catching it; if that's still unclear, ask.

When I ask for a PR, name it type/short-description, where type is one of: feat, fix, docs, refactor, chore, style, test, perf, build, ci, uat.

Post-merge cleanup — Claude reminds, so I don't have to. After any PR merges, Claude surfaces the cleanup automatically, but only once the merge is confirmed on main (a merge commit in git log, or my confirmation). The sequence is push → PR → merge → cleanup. Then provide: git checkout main, git pull origin main, git branch -d <branch>, git remote prune origin.

Style changes get their own commit. When a UI/UX decision is finalized and applies project-wide, ask whether STYLE.md and/or STYLE.css should be created or updated. Any change to either gets its own commit, never mixed into others.

An action a person can take is tested by taking it — submit the form or follow the link, follow the redirects, and assert the page that comes back. An assertion about the effect goes after that, never instead of it.

Show client-facing changes on localhost. When edits are client-facing UI or UX (style, content, layout, flow), launch localhost first so I can see them before they are committed. Start the server with caching disabled, or hand over the URL cache-busted (?v=<short-sha> or equivalent) — always a link I can copy-paste, never a bare localhost:####. Beating the cache is Claude's job.

Part C — Global Human/Claude Processes

Processes here are either universal — every project, always — or opt-in, applying only where SCOPE.md declares them.

how-to: keep CLAUDE.md in sync (universal)

The master copy lives on local disk at /Users/swai/sw805206/CLAUDE.md. Every project repo holds a copy, and the disk master is what they reconcile against, regardless of tree or GitHub account. A new repo joins by taking a copy at creation.

Publishing a change (project A). Edit the copy in project A's repo, commit to main, then copy the file back to the disk master. Not finished until both have happened.

Reconciling a copy (any project). At the start of a task, compare the project repo's copy against the disk master by line 1, and where they differ, sync to the later version automatically — perform the sync and report it, rather than flagging and waiting. Disk master later: copy it into the working tree, commit, push. Repo copy later: copy it out to the disk master. Either way both copies end the task on the same version.

Human steps after any change. Re-paste Part A into Claude's global settings, and upload the current file to each Claude project folder.

how-to: start a new project (universal)

A new project starts in a Claude chat, before any repo exists.

1. Bootstrap. I create a Claude project folder, upload CLAUDE.md, and describe the project. Reading CLAUDE.md and finding no SCOPE.md, the chat asks whether one is coming or whether this is the chat that authors it.
2. Author SCOPE.md. Discuss, then write v001 and save it to the local tree beside CLAUDE.md. SCOPE.md declares the project type, the governance docs it requires, whether it deploys from main, and its branch/PR discipline. Little else can be decided until it exists.
3. The repo, where the project is git-related. Created either by a prompt the chat writes for Code, or by me. Its path is recorded in SCOPE.md. Before the first commit, run git config user.email in the fresh clone and check it against the account the project owns — no commit is made until it passes. This is the only check that catches a wrong-tree clone, whose failure is otherwise silent. The account decides the tree, and the clone URL form selects the credential path; use the form belonging to that account, not a bare github.com URL.
4. Scaffold every XYZ.md SCOPE.md names, at v001, so a declared file is never a missing one. Commit them direct to main with SCOPE.md — except a scaffold SCOPE.md declares publicly served, which takes branch and PR from creation. Copy CLAUDE.md from the disk master, byte-identical, never re-stamped. Ignore local tooling directories at creation rather than after they first dirty the tree.

SCOPE.md v001 is hand-stamped, since no machine has counted it yet; the first Code commit corrects the stamp.

how-to: run the tally (universal)

The tally is a live list in chat of everything a discussion produced that is not already done. Temporary and uncommitted; the repo files are the source of truth. Which destinations exist depends on which files SCOPE.md declares.

Capture is proposed, never assumed. When a discussion produces an open question, a fix, a finding against a governing doc, or a decision, ask whether to log it. The ask rides along with the answer it came out of, never as its own turn. On yes, log it and reprint. On no, it is gone — no shadow list.

The tally reprints in full whenever it changes, never the new row alone, so the latest printing is always the complete list. Reprint a row's FULL text only when that row's wording changed; otherwise give it as P##, destination and a one-line summary. Every row is printed in full at the flush, which is where the wording has to be exact.

Format. | P## | Item | Destination | — Destination stays blank until the checkpoint.

P## are scoped to the current unflushed batch and are never reassigned within a session: when an item leaves, the others keep their IDs and the next item takes the next number. They recycle from P01 only once the tally is empty, which a flush does not necessarily leave it. An item that leaves by being fixed drops out at the next reprint and is named in a one-line note beneath it with its evidence (SHA or PR); those notes are chat-only and die with the session, since the durable record is git.

The checkpoint is mine to call. Claude may suggest one; it never decides one, and nothing flushes automatically. At the checkpoint every row takes a destination:

An undecided decision is a Park, not a Settle. DECISIONS.md holds decisions that have been made.

The search runs at every checkpoint, without being asked. Before the flush, search each row against BACKLOG.md and DECISIONS.md and report it as new, a duplicate of BL-###, or in conflict with DEC-###. The search is unconditional; what to do about a hit is mine.

The flush is one operation and one commit. It is a word-for-word copy verified by count — N rows named = N rows out — which guards against dropped or duplicated rows. IDs are assigned here, and so is the cross-reference: a Settle writes its DEC-### entry and the rule it changed in the same operation, so the link cannot be half-made. All three files are governance docs, so the commit goes direct to main and is pushed per Part B.

Claude does not log as a way of deferring. Where an item could reasonably be done now, Claude says so and offers to do it rather than proposing a row.

Where the project publishes a rendered view, verify the flush there rather than in the raw file: push, wait for the rendered view's own commit to deploy, then confirm the new rows render as correctly-columned rows. This catches an unescaped pipe, and a bare <angle-bracketed> token which renders as a tag and vanishes — both silent in the source and visible only once rendered. Verify against the deployed page, not a local copy, and not before the deploy confirms.

how-to: keep the backlog (opt-in — when SCOPE.md declares it)

BACKLOG.md tracks deferred work. Its definitions — categories, status semantics — live in its own header. The process is global; the artifact is per-project, and backlogs never merge across projects.

BL-### are assigned at flush in cumulative sequence from the last BL number in the file, and are never reused. Category and status are assigned at flush.

Once an item is a row, the Status rules govern it for the rest of its life. Work on an existing row moves it to review; nothing lifts a row back out of the file.

Status rules. Claude never self-closes: done items move to review, not close. Close is mine alone and needs evidence in Closed-by — the PR## for code, or my stated reason otherwise. A discard row carries its reason there too. Closed-by stays empty on every other status.

Schema. | ID | Status | Category | Item | Raised | Closed-by |

how-to: keep the decision record (opt-in — when SCOPE.md declares it)

DECISIONS.md holds the layer beneath the governing docs: alternatives considered, options rejected, the research a decision rests on. The governing doc wins on conflict — the record is history, never authority.

The rule and the "because" beside it stay in the governing doc. Only the layer beneath comes here. Part B's three-pass check depends on the justification sitting next to the claim it justifies.

DEC-### are assigned at flush in cumulative sequence, and are never reused. The decision's date is the flush date, read from the machine.

An entry names the governing doc it changed. The link runs one way: the governing doc does not cite back.

The entry's own fields are the project's to define, in DECISIONS.md's header.

how-to: publish the handbook (opt-in — when SCOPE.md declares it)

SCOPE.md declares whether a handbook exists, which documents it renders, whether it is gated, where it is hosted, and what generates it.

It is a view, not a source. The master is always the file. A page is regenerated from it and never edited in place, or the rendering becomes a second master.

Regeneration follows the commit that changed a source; it never rides inside it. A generated page names the commit it renders, so it cannot sit in that commit. Two commits, both direct to main: the sources first, then the page regenerated against the now-clean tree and committed on top (Part B, generated files). Not an amend. Regeneration is not a judgment about whether the change was significant enough — every commit bumping a version stamp on an in-scope document earns one.

Where a workflow does the regenerating, the second commit arrives on its own. SCOPE.md says whether one exists. Do not also regenerate by hand.

The handbook is not stamped and is not in the sync audit. It is generated, so a stamp on it would be authored nowhere; it carries the stamps of the documents it renders, and the audit covers those.

Verify on the deployed page where the change touched a table. What you wait for is the deploy of the page's own commit, not of the source commit. Push, wait for the page commit to land and deploy, then confirm the rows render as correctly-columned rows. This catches an unescaped pipe, and a bare <angle-bracketed> token which renders as a tag and vanishes — both silent in the source and visible only once rendered. A change touching no table needs no post-deploy check.

Audience: anyone implementing or quoting what HappyShip bills.

What HappyShip charges its own clients, and how it is computed. It spans every phase and every leg, and it covers HappyShip's own fees only — never charges between a buyer and a seller.

Contents are [OPEN].

Audience: Claude Code, for any task touching leg 1 rating, the rate card template, or comparison.

Scope of this file. One leg, all of its carriers. Leg 1 is last mile (SCOPE.md, service legs).

Read SCOPE.md first. Where the two conflict, SCOPE.md governs.

What else this work needs.

---

1. Status

Settled: the rate card template (§2), rate conditions (§3), and rate-for-rate comparison (§5).

Not settled: shipment-cost calculation order (§6) [OPEN] · the shipment template (§7) [OPEN] · the aggregate presentation of comparison output [OPEN].

---

2. The rate card template [phase 1]

2.1 The template is generated, not blank [phase 1]

• A template is generated for one reference standard, chosen before download. The standard is named in the file's header block.
• Structure is locked to that standard: which charges exist, in what order, with what unit and what brackets. The client supplies amounts, and dates where theirs differ.
• Two cards naming the same standard cannot differ in shape. The structural-equality requirement of §5.5 is therefore a backstop against edited files rather than a routine outcome.
• Language follows the login (APPLICATION.md, language in the application). It is not a download option, and the file is never bilingual.

2.2 File shape [phase 1]

• One populated sheet. CSV and XLSX are interchangeable (APPLICATION.md, ingest), and a CSV has no sheets — that is the reason.
• Two blocks in one rectangle. The weight-by-zone grid on the left; the charge block to the right of the last zone column, separated from it by one empty column. Placed right, every column means one thing from top to bottom. Stacked below, a value column would mean "zone 2 rate" for the grid rows and "amount" for the rest, and a column that changes meaning mid-file is a silent wrong answer.
• A header block travels with the file, carrying the reference standard, carrier, service group, leg, template version, and the card's effective from and to. It is what lets the parser read a filled file standalone and what satisfies the export-complete rule (APPLICATION.md, output is whole).

2.3 The charge code [phase 1]

• Every charge row carries a code in a hidden, locked column. HappyShip assigns it; a client never types it.
• Why it exists: the label is translated, so the label cannot be the key. Position alone would work while the structure is locked, but fails silently if a row moves, and it leaves an exported file uninterpretable without HappyShip's mapping — which the export-complete rule exists to prevent.
• The code is hidden rather than removed so it survives a CSV round trip and the file stays self-describing.
• The set for this leg, closed: AHS-D, AHS-W, AHS-P, OS, RESI, DAS-C, EDAS-C, RDAS-C, DAS-R, EDAS-R, RDAS-R, ADDR, SIG-A, SIG-D, SIG-I, DATEC, UNAUTH, HAZMAT, INS, DMD-RESI, DMD-AHS, DMD-OS, DMD-UNAUTH, DMD-RESIPK. The marker row's code BASE (§2.4) is a structural code, not a charge: it is not in this set and never appears in the charge block.
• Naming convention, so a second carrier follows it: the modifier precedes the base (EDAS-C, RDAS-C), and DMD- prefixes the code of whatever it modifies.
• One code, many rows. A row is identified by its code plus its effective-from date, plus its bracket where one exists. UNAUTH appears twice because FedEx renamed the charge mid-year; INS twice for two brackets; each DMD- code three times for three windows.
• **Grid rows below the BASE marker row carry no code.** A row is identified by its code, or by its numeric Item where the code is blank — a weight is already language-independent.

2.4 The grid [phase 1]

• Rows are weight in whole pounds, 1 through 150, contiguous — no gaps and no bands. A file with gaps or bands is rejected.
• 150 lb is FedEx Ground's per-package ceiling, not an arbitrary limit.
• Columns are zones 2 through 8.
• AHS Dimension, AHS Weight, AHS Packaging and Oversize are per-zone but not weight-indexed. They sit in the same grid under the same zone headers, above the weight rows, separated from them by a required marker row.
• **The marker row carries the code BASE in the hidden code column**, like every other structural row. Its visible cell is display text and is translated; the parser reads the code, never the label. The label is translated, so the label cannot be the key — the same reason the charge code exists (§2.3). A file missing the code is rejected rather than read as weight rows. Formatting does not survive CSV, so the marker cannot be a fill color either.
• The grid takes its effective dates from the header block, not per row. A base grid changes once a rate year; 150 identical date pairs would be 300 cells that always agree.

2.5 The charge block [phase 1]

Columns: Code (hidden), Charge, Charged as, Value from (hidden), Value to (hidden), Effective from, Effective to, GD, HD.

• **Charged as carries the unit and, where one exists, the bracket, as display text** — "flat", "flat, $100.01~$300", "per $100, when $300+", "105~125%". This is not a parsing hazard: the column is locked and generated from the reference standard, so the client cannot type into it, and the machine reads the bracket from Value from and Value to. The cell only has to be legible to a person.
• **Value from and Value to hold a bracket's boundaries as numbers.** Both are hidden and locked, like the code column. Both exist because the prose is legible and the numbers are parseable, and neither can be typed into — the same arrangement as the code column, machine-readable underneath and legible on top. Both are blank on a charge that carries no bracket. Insurance is the only bracketed charge in this leg; the columns exist for the shape rather than for the count.
• **Effective from and Effective to are per row**, so a dated surcharge window is rows and a new one is new rows rather than a new file format. A blank Effective to means open-ended.
• A renamed charge is two dated rows under one code, not an edit. Recorded so an invoice from either side of a rename stays explainable.
• **GD and HD are per-service columns.** Service is a column only in this block, never an axis on the grid (APPLICATION.md, ingest).
• **A blank Charge name means the row continues the charge with the same code above it.**
• Blank rows separate charge groups. The parser skips them; a blank row does not terminate the block.
• Demand — Residential Delivery Charge is excluded, and the exclusion is stated in output. FedEx computes it weekly from the client's own shipping volume against a peaking factor with a two-week lag, and no contracted discount applies to it, so it cannot be expressed as a priced row. The peaking-factor tier table is carried as reference only under DMD-RESIPK and is not costed.

2.6 The form [phase 1]

Fields entered on the web form, not in the file:

• Nickname.
• Rate owner — the owning entityID. Not shown when a client uploads its own card, since the entity comes from the session (APPLICATION.md, identity and access). Selectable from the entity list only when HappyShip enters a card on an entity's behalf.
• Dim factor.
• FSC discount.
• Currency and weight unit, displayed but locked — they come from master data.
• Notes, free text, never parsed.
• Conditions, per §3.

The effective dates are not on the form. They are in the file's header block (§2.2).

The governing test: the file holds anything with one uniform row shape, however many rows. Anything carrying parameters of its own goes on the form.

2.7 Dates [phase 1]

• **Every date is a real date, rendered YYYY-MM-DD.**
• A CSV must carry ISO dates. Any other format is a rejection, not a guess — Excel exports a date in the system locale's format, so the same file saved on two machines produces two different CSVs, and one of them reads May as January.

2.8 Prefilling [phase 1]

• A template ships prefilled with the reference standard's published values. It is not offered blank.
• A blank file gives the filler no reference for what a valid entry looks like. Clearing is one action for the rare client who wants to start empty.
• The hazard this creates is handled at upload, not download. A client who overwrites the grid and forgets the accessorials ships a file whose accessorial rows still hold published values, which parses clean and reports a 0% difference. §2.10 covers it.

2.9 Reading the file [phase 1]

The parser cannot trust the file's formatting. Paste replaces format, so a pasted cell may hold a number as text, a date as a serial, or a currency-formatted string.

• Normalize what has one reading: strip currency symbols, thousands separators and whitespace including non-breaking space, normalize full-width digits, then coerce.
• Reject what has two. A value whose decimal separator is ambiguous is a rejection naming the cell, not a guess.
• Check type before coercing. A numeric cell holding a string is recorded as coerced even where coercion succeeds, so it reaches §2.10.
• A date cell holding a number is a serial only within a plausible range; otherwise it is a rejection.
• The hidden code column cannot be pasted over, being locked, so it is the anchor the parser reads structure from, whatever happened to the amounts beside it.

2.10 Conformance, rejection and confirmation [phase 1]

• A file that does not conform is rejected with its reasons before anything is stored. There is no post-parse edit screen (APPLICATION.md, ingest).
• The reason list is exhaustive on the first pass. The parser does not stop at the first error. A fail-fast parser turns a twenty-error file into twenty round trips.
• A header block that contradicts the form is a rejection, not an override.
• Separate from rejections, the upload reports what it read and does not block. Rejections stop the upload; confirmations do not, and mixing them either blocks what should not or lets through what nobody looked at. The report:
• rows still matching the reference standard exactly, as a count
• cells at or above the published value, listed
• cells below the plausibility bound, listed
• cells coerced from text, as a count
• empty amounts, as a count
• The plausibility bound is master data set by HappyShip, one bound for every block. It flags where the client value divided by the published value is below 0.10. It is recorded as a ratio, not a percentage, because "10% of published" reads two ways.
• Zero and blank are different findings and are not counted together. A typed 0.00 means waived; an empty cell means no rate and renders n/a.

---

3. Rate conditions [phase 1]

Each condition is marked must-met or prefer-met by whoever sets it (APPLICATION.md, rate card properties). The seller marks each condition explicitly, per card. There is no default.

The set is closed at three:

1. Minimum spend per month.
2. Ships from — one or more regions, or the value meaning all regions, which is exclusive of any specific region. Regions are cross-leg master data (APPLICATION.md, regions); the list as it stands is §3.1.
3. Fulfillment combo — the rate must be used together with the seller's fulfillment service.

Each is evaluated against a serviceability fact the requesting entity supplies per run (APPLICATION.md, serviceability facts). The three facts are: stated monthly spend, a stated set of regions or none, and stated fulfillment stance — willing to use the seller's fulfillment, or keeping their own.

• An unstated fulfillment stance means open to it. The alternative silently shrinks the pool.
• Fulfillment cost is never modeled. The condition includes or excludes a card and nothing more. This is a boundary: the warehouse leg is not built (APPLICATION.md, phase 1).

3.1 Ships from [phase 1]

The region list as it stands — one list across every leg (APPLICATION.md, regions), written here because last mile is the only leg built: Southern California; New York / New Jersey; Houston / Dallas; Chicago; Savannah / Atlanta; Others; and the all-regions value.

• A seller never selects Others. Where a seller's ship-from location falls outside the list, HappyShip adds a region to master data (APPLICATION.md, regions). A seller's declaration is always a reference, never free text.
• A requesting entity may select Others and supply free text. That text matches nothing, so a card cannot satisfy a must-met test against it; it flags and reaches the consultation.
• The requesting entity states a set of regions per run, or none. A card qualifies where the two sets intersect, or where the card declares all regions. Stating more regions widens the pool rather than narrowing it.

---

4. Reference data this leg needs [phase 1]

Not on a card. Some of it is master data HappyShip maintains; the rest is code, and which is which is APPLICATION.md, master data and the reference standard. [OPEN] marks a shape not yet designed.

• ZIP to zone lookup — audit-era, not phase 1.
• The trigger definitions for AHS Dimension, AHS Weight, AHS Packaging, Oversize and Ground Unauthorized — code, not master data. Each is an engine test rather than a value a row could carry, and the values are §4.1. A FedEx amendment to one is a deploy.
• Minimum billable weight rules — code, not master data. They arrive with the trigger that imposes them, so they are coded where the trigger is; the values are §4.1.
• Weekly published fuel surcharge rates, dated. HappyShip consumes FedEx's published weekly percentage and not the diesel bands it derives from: loading the bands would mean ingesting the diesel index weekly and reproducing FedEx's lag for the same answer, with drift producing a wrong number silently, and they earn their place only for invoice audit, which is deferred. The shape is an append-only weekly series — effective from, effective to, the percentage, and the index date it derives from — so history is the table and it needs no versioning.
• The set of charges the fuel surcharge applies to — code, not a boolean on a maintained catalog. The accessorial catalog is itself code, so the flag is a property of the coded set rather than a column someone edits; declared value is not on FedEx's list. FedEx publishes this list and may amend it, and an amendment is a deploy.
• DAS ZIP lists — audit-era, not phase 1.
• Insurance bracket structure. [OPEN]

Neither zone list is phase 1 work: a shipment profile carries the zone, so shipment-cost never resolves ZIP-to-zone and rate-for-rate compares zone 5 against zone 5, which leaves both to invoice audit.

The accessorial catalog is not a page. The question this file used to hold open — whether a fuel-bearing charge needs engine behavior attached, or is only a priced line that gets summed — was asked because it decided whether the catalog could be a maintenance page at all. It cannot, and the reason is the one that made the question urgent: the engine has to know what each charge does, and a name it has never seen can be parsed but not applied. The catalog is code (APPLICATION.md, master data and the reference standard), so a charge and the behavior attached to it are added together or not at all, and the question no longer has a decision resting on it.

The asymmetry, which runs through this whole file: a card supplies the PRICE of a charge; the TEST that decides whether the charge applies is never on the card. A card says what an oversize package costs and never what makes a package oversize. The test lives in code, not in master data — which changes who amends it and how, and not the asymmetry itself.

A card may override a default where a client has negotiated one, whether that default is master data or code. The dim factor is the known case: the divisor default is coded, and the card carries a form field (§2.6) where a client enters its own — so a negotiated dim factor is still data, and coding the default did not make it a deploy. A negotiated insurance bracket boundary is not supported in phase 1: Value from and Value to are locked and generated from the reference standard (§2.5), and no form field carries them, so a client cannot overwrite the threshold. Admitting it later is unhiding those two columns, not a format change.

4.1 FedEx published values [OPEN — verify before implementation]

Sourced from FedEx's published 2026 rules. Every value below requires verification against the FedEx service guide before any code depends on it.

• Dimensional weight is volume with each dimension rounded up to the whole inch, divided by 139 for US domestic. Billable weight is the greater of dimensional and actual, rounded up to the whole pound.
• AHS Dimension: longest side over 48 in, second-longest over 30 in, cubic volume over 10,368 in³, or length and girth over 105 in. Minimum billable weight 40 lb.
• AHS Weight: actual weight over 50 lb domestic.
• AHS Packaging: not fully enclosed in a corrugated container. Tests a description, not a measurement, so it must be declared on a shipment row.
• Oversize: length over 96 in, length and girth over 130 in, cubic volume over 17,280 in³, or actual weight over 110 lb. Minimum billable weight 90 lb.
• Ground Unauthorized: over 150 lb, over 108 in length, or over 165 in length and girth. Applies to Ground, Home Delivery and International Ground at one amount.
• Highest wins. Where a package qualifies for more than one of the above, only the highest applies, assessed after discount. The engine evaluates all of them and returns one line.
• The AHS Dimension minimum billable weight applies even where the AHS Dimension charge itself is suppressed by the highest-wins rule.
• Demand surcharges are additive, not highest-wins. The two families behave oppositely.
• Fuel is assessed on the net package rate plus a named subset of surcharges, not on the base rate alone. Insurance is not in that subset.

---

5. Rate-for-rate comparison [phase 1]

5.1 What it is and is not [phase 1]

• It compares two cards cell by cell and returns a percentage delta matrix plus an aggregate. It is a price-list comparison, not a computation.
• No triggers are evaluated, because there is no package to test.
• It cannot produce a total. Which card is cheaper overall depends on the package mix, which rate-for-rate does not have. Summing a price list looks like an obvious improvement to whoever finds it later; it is not one.
• Highest-wins is unavailable here. AHS Dimension, AHS Weight, AHS Packaging and Oversize compare as four separate rows.

5.2 The pairings [phase 1]

Three, fixed:

The pairings are fixed because the anchors are what make the output interpretable. A user-supplied pairing has no anchor.

The anchor follows the pairing and never moves with the arithmetic. An anchor that moved would mean C-to-A read one direction this month and another the next.

5.3 B1 and B2 [phase 1]

• B1 is drawn from the serviceable pool. B2 is drawn from the whole published pool and ignores must-met conditions. B1 is never cheaper than B2.
• Where they are equal, show B1 alone. Where they differ, show B2 as a headline figure and the condition type that blocked it — never a matrix, never line detail, never an owner.
• APPLICATION.md (isolation and visibility) forbids a breakdown that isolates an excluded card, and must-met exists so a seller can decide their card is not shown to entities that do not qualify. A headline figure satisfies the count-and-reason rule and still drives the consultation CTA.

5.4 Determining cheapest [phase 1]

• Evaluated after divisor mapping (§5.6), anchored on C. Ranking on raw card rates first produces the wrong card, because the divisor reorders the ranking.
• The requesting entity may nominate its most important 10 lb weight band; if it does, cheapest is cheapest in that band.
• If it does not, cheapest is the unweighted mean of the base grid, excluding AHS and all other accessorials.
• Where a divisor mapping truncates (§5.6), cheapest is computed over the anchor rows that resolve. Two candidates with different divisors may therefore be ranked over different row sets, and a candidate whose heaviest rows fall off the grid is measured without them. This is a limit of the measure, not a correction to it, and the truncation is reported alongside the ranking rather than left implicit.

5.5 Structural equality [phase 1]

Both cards must share a structure or the comparison is rejected: same zone set, same weight ceiling, per-pound rows. Non-standard weight banding is rejected — the HappyShip template is the supported path.

5.6 The row axis is volume [phase 1]

• The invariant is the box, not the weight row. Two cards with different dim factors put the same package in different rows.
• For each anchor row w, volume is w multiplied by the anchor's divisor; the comparison card's row is that volume divided by its own divisor, rounded up.
• Where divisors are equal this degenerates to row-for-row. One rule, not two.
• The mapping is not one-to-one, so the matrix reads in one direction.
• Where the mapped row exceeds the comparison card's grid, those rows have no counterpart and are reported as such rather than omitted silently.
• The matrix compares dimensional weight on both sides, so it holds for dim-dominant packages. A dense package bills at actual weight on both cards and the divisor advantage does not apply. This is stated on the output, not footnoted.

5.7 Output [phase 1]

• A heat map. 15 weight bands of 10 lb each, zones 2 through 8.
• A band's figure is the unweighted mean of that band's computed cells, the same rule the aggregate uses. A cell that is n/a or not computed is not in the mean. This is a second averaging layer above the aggregate's, and a band mean can hide a spike inside it.
• The aggregate is the straight unweighted mean across all computed cells — grid, per-zone charge and flat alike. It is unweighted and therefore structural — not what any shipper pays. Rate-for-rate has no volume profile by definition, and naming this stops someone later adding a weighting nobody supplied. This is not the measure cheapest is ranked by (§5.4): that one is the unweighted mean of the base grid alone, accessorials excluded. Two populations, two purposes — the aggregate describes the whole matrix, cheapest ranks cards on the grid.
• Computation is exact rational arithmetic throughout, rounded once at the boundary. Summing a thousand already-rounded cells drifts, and the mean of a thousand identical deltas then differs from the delta itself. This was observed, not anticipated.
• AHS Dimension, AHS Weight, AHS Packaging and Oversize appear as rows inside the zoned matrix, because that is how the file supplies them.
• Flat charges appear as a single cell.
• **Where the reference card carries a value and the entity's card does not, the cell renders n/a.** The engine cannot distinguish an omission from a deliberate absence, and n/a claims only that there is nothing to compare, where "data missing" makes a claim about the file. No substitution, and no conclusion drawn either way — an omission and a deliberate absence cannot be told apart from the file.
• Where the anchor's value is zero, no percentage is returned. The cell reports not computed and shows the anchor value. A percentage of zero is not a figure, and returning one would be a number nobody could explain (APPLICATION.md, engineering rules). This is a different finding from n/a: n/a is nothing to compare, not computed is nothing to divide by.
• A cell still holding the reference standard's published value is not distinguishable from a negotiated rate that matches it. That is why the count of such cells is reported at upload (§2.10) rather than inferred at comparison.
• Substitution of the reference standard for missing mandatory data (APPLICATION.md, compare rates) applies to a costing run. Rate-for-rate computes no cost, so nothing is substituted and a missing value renders n/a.
• The dim factor advantage and the FSC discount are stated in the report, not folded into the map.
• Colors, banding and layout are brand/STYLE.md. They are not restated here.

---

6. Shipment-cost comparison [OPEN]

Not yet written. It needs: calculation order, the interaction between minimum billable weight and the base rate, and the shipment template (§7).

---

7. The shipment template [OPEN]

Not yet written. What is settled: a shipment row carries length, width, height, weight, origin, destination, service and ship date, plus declared flags for residential or commercial, AHS Packaging, hazardous materials, signature option and declared value. DAS is derived from master data, not declared.

---

8. Carriers [phase 1]

8.1 FedEx — Ground and Home Delivery [phase 1]

§2 through §7 describe it. No carrier-specific variation beyond what is already stated.

8.2 Other carriers [not admitted]

UPS, USPS, Amazon and OnTrac are names in the coded carrier list and are not built — the name is there, the reference set behind it is not (APPLICATION.md, master data and the reference standard).

---

9. Open items [OPEN]

Audience: Claude Code and Claude chats, at the start of every task.

What this file holds. The shared ground: what HappyShip is, the two surfaces, the service legs, the source and target languages, which document to open next, where a commit goes, and what the handbook renders. Short by design.

What it does not hold. How either surface works, or what is built on either. APPLICATION.md and WEBSITE.md own those, each for its own surface.

---

0. Rules for using this document

1. Open the one document for the surface you are working on (§5.1) and follow it onward.
2. In all markdown documents, an [OPEN] tag means the decision is not finalized.
3. A rule written for the website or the application does not carry to the other unless it says so. Each owns its own scope boundary.
4. A reference that crosses a file names the file, never a section number inside it. Section numbers are for use within the document that owns them. A number quoted across a boundary is a promise the other file never made, and it breaks silently the next time that file is restructured — which has already happened here more than once.

---

1. What HappyShip is

HappyShip provides logistics rate analytics and advisory. The analytical services are rate comparison, rate management, invoice audit and shipment tracking; the advisory services include rate negotiation and rate sourcing. It is a control tower: it holds the analytical picture, it does not hold the commercial relationship, and it does not profit from rate arbitrage.

1.1 What HappyShip sells

• Rate and invoice analytics, charged to clients.
• Consultation on rate optimization and carrier negotiation, charged to clients.

1.2 What HappyShip does not do

Direct contract negotiation · rate legitimization · dispute execution · payment processing between entities · adding margin to any rate.

---

2. Project scope

Two surfaces:

1. The HappyShip website.
2. The HappyShip application (SaaS).

Most of this document is about the application.

The product definition will keep evolving. The website carries the public-facing statement as it stands at any moment. These documents carry both the internal and the external view, and both the short-term and the long-term design. The two are not expected to match, and the website is not where the plan is published.

---

3. Product description

3.1 Services

The For column says what an entity is doing, never what it is. There is no stored role, so "acting as buyer" describes the moment, not a type — and one entity commonly appears in both rows.

This table is the full set of functions, not the built set.

3.2 Service legs

Rates are organized by leg. Each leg has its own rate table shape and its own RULES-<leg>.md. Carriers vary within a leg; they are not legs of their own, and a new carrier is a section inside that leg's rules rather than a new file.

---

4. Language

Source language is American English, on both surfaces — everything is authored in it, and the rule and its exceptions are CLAUDE.md Part A. This governs the English that is written, not whether a translation may exist.

Simplified Chinese is the first target language. Spanish and Vietnamese are candidates, not committed — [OPEN]. A target language is rendered from the source through DICTIONARY.md, never authored directly.

**Domain terms are translated against DICTIONARY.md**, which is shared for the reason that matters: one glossary means a term cannot render one way on a website page and another way on an application screen. Generic machine translation is not sufficient — it renders domain terms literally and inconsistently.

Locale mechanics differ by surface and are named in each.

---

5. Documents

5.1 Which document to open

Start with the one document for your surface, and not the other. It names what its own surface needs beyond this list.

Shared by both surfaces. Listed here and in neither surface document, so the two cannot drift into naming different files for the same job.

The website.

The application. APPLICATION.md and ARCHITECTURE.md and UX.md describe the application whole — every phase, every leg. They are not rewritten when a phase advances; APPLICATION.md is, and it is the only place that says how much is built. RULES-<leg>.md is narrower: one file per leg, holding every carrier in that leg as a section of its own.

---

6. Repository

6.1 Where it lives

6.2 Where a commit goes

Discipline is per path, not per repo. CLAUDE.md Part B asks one question — does a bad commit reach readers with nothing catching it — and that question has different answers in different directories. There is no answer for "this repo" as a whole.

**brand/ ships on merge, which is why all of it takes branch and PR.** build.sh carries brand/assets/ and brand/*.css to the live site at deploy with no review downstream. brand/ is the only gate.

**brand/STYLE.md is the exception that proves the rule.** It is not copied and reaches no reader, so Part B would send it direct to main as a governance doc. It does not go: Part B's exemption exists because governance docs carry no styling or page logic, and STYLE.md is styling. The justification does not reach it, so neither does the rule.

The generator and its workflow take branch and PR, though neither deploys. Part B says what earns branch and PR is the generator and the sources it reads. A bad commit under app/handbook/ or .github/ publishes a bad page to handbook.happyship.us with nothing between it and a reader — the generated file itself is exempt precisely because these two are not. That the workflow has run clean does not narrow the blast radius.

**app/ does not deploy from main, and a commit there reaches no reader. This holds only while it is true** — the day the application acquires a deploy that builds from main, this row must be rewritten before the first commit under the new arrangement. app/handbook/ is already carved out above.

**brand/tokens.css is a publicly-served governance file, and this is where that is declared.** It is the trigger for Part B's exception, which the brand/ row already satisfies. It reaches the public twice — copied into web/site/ by build.sh, and embedded in the generated handbook, where the whole file is inlined as a <style> block and its values are rendered again into the stylebook — and the second route adds nothing to review, since branch and PR attach to the authored file and the generated copy carries that same reviewed change downstream, which is what Part B's narrowing turns on.

**What this repo publishes is web/site/, the brand/ files build.sh copies into it, and handbook.html.** Everything else is unserved — but unserved is not the test, which is why app/handbook/ and .github/ take branch and PR anyway.

---

7. The handbook

Every governance document is rendered into one handbook, all of them in one reader, because separately they go unread: they are long, and following a cross-reference means opening another file and searching it. It is public and ungated, served at handbook.happyship.us. It is a view, never a source, and the process governing it is CLAUDE.md Part C.

What the handbook holds:

Audience: Claude Code, when a task touches a screen, a flow, or what a user sees.

Scope of this file. Screen inventory and flow for the application: what a user does at each step, and what each screen contains.

This file holds no rules of its own. Every rule lives in APPLICATION.md, ARCHITECTURE.md or RULES-<leg>.md, and the default here is to name the owning file rather than repeat what it says. Visual language is brand/STYLE.md; values are brand/tokens.css. Domain terms are DICTIONARY.md.

A premise is the exception. Where a screen requirement cannot be read without the rule it rests on, that rule is stated here and its owning file named alongside it — a requirement whose premise lives only in another document is one nobody can act on from this one. The test is whether the rule is doing work for something on the screen. A rule sitting on its own, for its own sake, is a restatement and comes out.

Not the website. That surface is WEBSITE.md and has no UX document.

A section here is not permission to build it. APPLICATION.md is the authority on what the current phase admits. Every heading carries a phase marker; where a marker and APPLICATION.md disagree, APPLICATION.md governs and the marker is a defect to fix.

What is written and what is not. A section with content is settled. [OPEN] marks a decision that has not been made — not a section someone forgot to write. Where a screen's contents are settled but its arrangement is not, the contents are listed and the layout is marked open; listing what must appear is not a layout decision.

---

1. Patterns [phase 1] [OPEN — §1.5]

Written once, instantiated everywhere. A new leg reuses this section rather than copying it.

These are shapes generalized from the sections below, not a fourth surface. Where one of those sections still states a shape stated here, it does so because the screen there cannot be read without it — the premise rule in this file's header. §1.5 is the one subsection still open, and what it waits on is named there.

1.1 The shell

**The band is brand/STYLE.md's.** It carries the logo, navigation and environment, and what it looks like on each surface is that file's business rather than this one's.

Navigation has one root per surface, and neither leads to the other. A client arrives at the service menu (§3); the internal tool is a separate surface reached only by a login bound to the HappyShip entity (§9).

Entity context and entity identification are different controls, and the shell must not collapse them. The internal tool reads across entities by design (APPLICATION.md, internal), so it shows which entity is in view — a context that changes while the login does not. A client login binds to one entity (APPLICATION.md, identity and access) and has nothing to switch to, so what its shell shows is identification. Rendering the client's as a picker holding one option offers a choice that does not exist.

Sign-out sits here, and it is the only control that ends a session (§2.4). A session also ends on its own, but those limits and the reasoning behind them are ARCHITECTURE.md, auth, and no screen states them. It sits at the right of the band, after the entity context — an arrangement carried over from the client band, which draws it, rather than one the internal design has been reviewed with.

Language and time zone are set from the shell, per login, taking effect immediately — §7.3 holds that rule, and §2.2 governs instead before a session exists. Their placement and form are [OPEN]: neither band has been drawn with them, so whether the control is a pair of selects, a menu, or a link to a settings screen is undecided.

1.2 The run pattern

upload → validate → acknowledge → run → dashboard → report

The whole arc belongs to a run. A card upload uses the first two stages and stops at stored (§4.2): nothing about it runs, and it produces no report.

• Upload — a file on the generated template, or a selection from what the entity already holds (§5.3). Whether the file survives is the stage's own business, and the two answers are opposite: a library card persists, a comparison file is discarded.
• Validate — parse, then report in the two columns of §1.3. Nothing is stored and nothing runs until the blocking column is empty.
• Acknowledge — the acknowledgment carries a count, not a policy. A required checkbox stating a consequence in the abstract is agreed blind; the same checkbox beside the number of lines it applies to is a decision (§5.4).
• Run — the point the entity commits. A run cannot start on an exhausted balance (§7.4), and metering deducts per run whatever the price (APPLICATION.md, billing and metering).
• Dashboard — what it must carry is §6.2, and that same list governs the report.
• Report — the report is the record, because the run leaves nothing behind. The upload is gone once it parsed, the detail goes once the report is delivered, and there is no history to return to (§6.3; APPLICATION.md, retention). A screen implying a result can be reopened is describing something that does not exist.

1.3 Rejection and error display

Two columns, always: what stopped the work, and what was found and did not stop it. Card upload, comparison upload and every master-data upload show both, visually distinct on each.

• The blocking column is exhaustive on the first pass. The parser does not stop at the first error, because a fail-fast one turns a twenty-error file into twenty round trips.
• A non-blocking finding must say plainly that it did not block. Left ambiguous it reads as a failure, and the work it did not stop is assumed undone.
• Nothing is stored while the blocking column has anything in it, so a rejection screen never has a half-saved thing behind it.

What is reported, and which findings fall in which column, is RULES-<leg>.md.

1.4 Empty states

An empty state that is normal must not be dressed as incomplete. The cost of getting this wrong is not a misreading but a search: someone goes looking for a defect that was never there.

Normal, each already instanced — an entity with no logins, which is what every entity looks like before an address is registered (§9.1) · an entity with no ship-from locations, "no physical location" being a valid state (APPLICATION.md, ship-from locations) · a library holding no cards, since an entity may compare without ever holding one (§5.3) · Others holding no ZIP prefixes, which is what Others is (§8.2).

The rule is the difference, not the emptiness. A region added but not yet mapped is empty in a way that does mean something is unfinished, and a screen saying so is right. The test is whether the empty state is where the thing is meant to rest or a stop on the way somewhere else.

1.5 Loading and long-running work [OPEN]

Nothing to generalize from yet. No document says how long a run takes, what the screen shows while it runs, or whether a user may navigate away from one.

It waits on two things already recorded: the job execution model, which ARCHITECTURE.md marks a gap and forbids deciding without asking, and what session expiry looks like part-way through a run (§2.4). The one adjacent fact that does exist is §6.1's — the report is emailed as well as offered in-session, so a closed tab costs the entity nothing. That is a property of the report, not a loading pattern, and it settles none of this.

---

2. Access [phase 1]

2.1 Arrival and sign-in

There is no sign-up. Access is by invitation (APPLICATION.md), so nothing is created on first arrival that did not already exist, and the first visit and every later one are the same two screens — enter an email address, then enter the code sent to it.

The code is six digits and arrives by email. That email is always English, because it is sent before a session exists and there is no login to read a preference from.

2.2 Language and time zone before a session exists

Both follow the browser on the unauthenticated screens: its language, and its clock for the time zone. No login exists yet to read a preference from. Once one does, §7.3 is where they are set.

2.3 Settled by convention, not by design

• Code expiry, resend cooldown, and wrong-attempt limits follow industry standards. Nothing here is unusual and nothing needs inventing.
• An unregistered address gets a page, with a link out to the contact form on the website.
• A delivery failure has one recovery path: contact us. No self-serve alternative in phase 1.

2.4 The session

A session ends on its own — after a stretch of inactivity, or at an absolute maximum measured from sign-in, whichever comes first. Activity extends the first; nothing extends the second. The two limits, and the reasoning that set them, are ARCHITECTURE.md, auth.

It survives a browser close. Closing the tab, or quitting the browser entirely, and returning inside those limits finds the session still there and asks for nothing again.

Signing out is the only way a user ends their own session, from the control in the shell (§1.1). There is nothing else on any screen that ends one.

What expiry looks like part-way through a run is [OPEN].

Rules: APPLICATION.md for identity and access, ARCHITECTURE.md for the auth mechanism.

---

3. Service menu [phase 1]

Four tiles, one per function, labeled as SCOPE.md names them.

A disabled tile is inert — a label and nothing behind it. It is not a route, a stub, or a screen that explains itself.

**Tile labels match the function names in SCOPE.md exactly.** One vocabulary across the documents and the interface; a tile does not get a friendlier name than the function it opens.

Choosing Compare rates leads to §5, which begins by choosing between the two comparisons. Choosing Manage rates leads to §4.

---

4. Manage rates [phase 1 — lite]

4.1 The library list

Every rate card the entity owns, in one list. Each row shows the nickname the entity gave it, its rateID, its status, and whether it carries conditions.

Lifecycle is set by the user, not computed. A card is created as draft and the user promotes it to active. The user archives a card when it is finished with. Delete is offered only on a card that has never been used or linked (APPLICATION.md). Expiry is the one exception — a card past its expiration date expires on its own.

Publication is a separate flag, not a lifecycle state (§4.4). The list shows one word per card because a column holds one, so an active card with the flag on reads Published — but the user is setting two independent things, and the screen must not offer a status control that turns publication on. An entity's own buy rates are active and must never enter the pool; if going active sat one slot away from publishing on the same control, that separation would be one misclick deep.

4.2 Uploading a card

The HappyShip template, downloadable from this screen once a reference standard is chosen — the file is generated for that standard. The standard is not a post-upload form field. The template's language follows the login (APPLICATION.md); there is no language choice at download. The formats it comes in are APPLICATION.md. A file that does not conform is rejected with the reason, on the upload screen, before anything is stored.

The upload screen reports rejections and, separately, confirmations that do not block. What is reported is RULES-LAST-MILE.md; that there is no post-parse edit screen is APPLICATION.md. The screen shows both, keeps them visually distinct, and makes clear that a confirmation does not prevent the card being stored.

A card the entity uploads for its library is stored and persists. This is a different act from uploading a file to run one comparison (§5.3), which is discarded — and the two are reached from different places so they cannot be confused.

The card-entry screens carry a how-to at the foot, with a link to it at the top — on this path and on the internal one (§4.6), since both fill the same template. It must carry how to fill the template and what is rejected (RULES-LAST-MILE.md, conformance, rejection and confirmation). Its contents are [OPEN].

4.3 Conditions

A card may carry conditions, and each is marked must-met or prefer-met when it is set. The screen has to make that choice explicit rather than defaulting it silently, because the two do different things:

• Must-met — an entity that does not meet it never sees the card at all.
• Prefer-met — an entity that does not meet it sees the rate, flagged.

The setter is choosing between "hide this from people who don't qualify" and "show it to them anyway." Wording that does not convey the difference is a defect.

What a condition can express is RULES-<leg>.md.

4.4 Publishing and withdrawing

One control on an active card, labeled Private and Public. Private by default. Publishing puts the card into the comparison pool; clearing it takes the card back out while leaving the card usable for the entity's own comparisons.

The screen has to say what publishing does, because the word suggests display and that is not what happens: a published card is comparable to other entities, never visible to them. What they see is computed results behind a reference code that changes every run — never the card, its rateID, the terms, or the owner.

The screen has to distinguish "you have not published this" from "your entity cannot publish." The owner's consent is not the only condition (APPLICATION.md), and an unauthorized entity that uploads cards and finds a dead control with no explanation will conclude the product is broken. What that state offers is [OPEN].

A card leaves the pool three ways, and the interface must not present them as one event. Only one of the three is anyone at the entity deciding something; the other two happen to them. Which is which is APPLICATION.md.

A draft cannot be published.

Publishing requires declaring at least one region (APPLICATION.md). The screen must make the all-regions value exclusive of specific regions, and must not allow publishing without a declaration.

Where the acting-login record surfaces in the UI is [OPEN]; that it is kept is APPLICATION.md.

4.5 Drafts HappyShip entered

A card HappyShip entered on the entity's behalf appears in the same list as a draft, and the owner is emailed when it lands.

The screen exists so the owner can check a transcription before standing behind it. Only the owner can publish, whoever typed the card in — so the draft's screen leads to the same publish control as any other card, and to nothing else.

This is also where a card HappyShip converted from a non-template file arrives. Nothing about the screen differs; the conversion happened offline.

4.6 The internal path, and where it diverges [phase 1]

§4.1 to §4.5 are the client's path and are correct as written. An internal path exists alongside it and diverges at the start, in the middle, and at the end.

At the start, internal only: a first step choosing what kind of card — client, or carrier published — and a rate owner naming the entity the card belongs to. A client has neither, because designating a reference standard is a HappyShip act and the entity comes from the session rather than a field (RULES-LAST-MILE.md, the form).

In the middle: the internal path is two pages and the client's is one; the order of what they ask is the same on both (DECISIONS.md).

At the end: a client's card lands as a draft in that client's library (§4.5); a carrier-published card becomes a HappyShip-owned card plus a designation, which the schema already does (ARCHITECTURE.md) and no screen describes.

The internal tool's own screens are §9; its entity, entity-detail and logins screens carry the internal side of this.

Rules: APPLICATION.md, master data and the reference standard.

4.7 Ship-from locations [phase 1]

The client maintains its own ship-from locations. The screen carries the list, and for each location the fields APPLICATION.md names: address, city, state and ZIP code, and the region the location maps to. ZIP is required. Several are allowed, and none is a valid state.

Declaring a region is optional, and the region shown against a location is resolved from its ZIP (APPLICATION.md, ship-from locations). The screen must not present a declared region as the answer, since HappyShip audits declarations and may remap.

**Under the placeholder exception in APPLICATION.md**, the screen shows warehouse type and square footage as greyed, non-selectable, non-clickable labels marked as not in scope. They carry no value set and store nothing. The deferred work is BL-008 in BACKLOG.md.

Rules: APPLICATION.md, ship-from locations.

4.8 Derivation, L1 to L4 [not admitted]

No screen. Its rules are unwritten.

Rules: APPLICATION.md, rate card properties.

---

5. Compare rates [phase 1]

5.1 Choosing the comparison

Two paths, chosen first because they take different inputs:

• Rate-for-rate — compares rate cards line by line. Answers who is cheaper per line item.
• Shipment cost — prices an actual shipment profile against each card. Answers what shipping would cost.

5.2 The web form

Serviceability facts: where the entity ships from and to, what volume, what service level, and whatever else the leg's conditions test. The full field set is RULES-<leg>.md; what they are and what they narrow is APPLICATION.md.

Supplied every run, never remembered. The form is not a profile and must not present itself as one — an entity that ships differently this week says so this week.

5.3 Providing the rates or shipments

Either upload a file on the HS template, or — for rate-for-rate — select a card from the entity's own library.

An uploaded file here is transient. It runs one comparison and is discarded; it never becomes a library card, and the screen must not offer to keep it.

5.4 Validation and the acknowledgment

On upload, the file is parsed and checked. Then, before the run:

• Rows that cannot be read are reported with their reason.
• The count of lines missing mandatory data is shown.
• A required checkbox states that those lines will be priced at the reference standard.

Checking the box starts the run. The count is shown next to it so the acknowledgment is specific rather than a policy agreed blind.

5.5 Running against your own card

An entity may compare one of its own library cards instead of uploading, and against the reference standard. Reached from §4.1 as well as from here.

Rules: APPLICATION.md for the boundaries, RULES-<leg>.md for the form-and-file split.

---

6. Results [phase 1]

Layout is [OPEN]. What the screen must show is settled and is listed below; how it is arranged, what leads, and what a chart does is not.

6.1 The report

The report is delivered by email and is downloadable in-session, so a closed tab or a dropped connection costs the entity nothing.

6.2 What the dashboard and the report must both carry

• An executive summary — where the entity's card stands in the pool, against the reference standard and against the cheapest serviceable rate. Where a shipment profile was supplied, the total cost difference against both.
• Counterparties labeled by a reference code. Each card in the pool carries one opaque code, and it is different in every run. The reference standard is named outright, being public.
• The same codes in the PDF. No run record survives, so the codes in the report are what a consultation resolves against weeks later. Why a code identifies nothing on its own is APPLICATION.md.
• Marked substitutions. Every line priced at the reference standard because the entity's card lacked mandatory data is marked as such.
• The count of the entity's own priced lines above the reference standard.
• Excluded cards as a count and a reason. How many published cards a must-met condition ruled out, and why — naming the condition type, never its value, never an owner, and never a breakdown that isolates one card.
• Prefer-met flags. A card whose prefer-met condition the entity does not meet appears with its rate and a flag naming the condition type. This is deliberate: an entity seeing a rate it does not yet qualify for is what the consultation exists to resolve. Filtering these out would look like a fix and would remove the mechanism.
• The consultation CTA.

6.3 After the run

The uploaded file is gone once parsing succeeded, the result detail goes once the report is delivered, and there is no run history to return to.

The screen has to be honest about that rather than implying a result can be reopened later. What it offers instead is the download, and the knowledge that the report is already in the entity's inbox.

Rules: APPLICATION.md for isolation and visibility, which constrains all of §6.2.

---

7. Account [phase 1]

7.1 Balance and coupons

The balance is the entity's, shared across its logins. A coupon is entered here, and an entity may hold several — so the screen shows what is held and when each expires, not one merged number alone. The coupon terms are APPLICATION.md.

7.2 Payment

Stripe is the path. ACH and wire are recorded manually by HappyShip, so what the screen offers for them is instructions and not a form that submits.

7.3 Language and time zone

Two toggles, both writing to the login and taking effect immediately. Per login, not per entity — a second person on the same entity is unaffected by either.

7.4 An exhausted balance [OPEN]

Metering runs per job at a price HappyShip sets, defaulting to zero in phase 1, so this state is reachable but rarely reached. What is settled: a run cannot start once the balance is exhausted, and the account screen stays reachable so the entity can pay.

What is not settled: what the blocked state looks like at the point the entity tries to run, and whether anything is offered beyond "add funds."

7.5 Entity record [phase 1]

The client sees its entity record. Some fields are editable by the client and some are read-only to it, and the screen must distinguish the two. Which fields fall on each side is APPLICATION.md.

Rules: APPLICATION.md for billing and metering, RULES-HS-CHARGES.md for what is charged and how it is computed.

---

8. Internal — master data [phase 1] [OPEN]

Entry and management of the reference standard, zones, fuel and regions. Nothing can be compared until this exists, which makes it the earliest internal screen rather than a late one.

Rate cards arrive through the generated template and its parser — a template is generated for one reference standard and its structure locked to it, which is what lets the parser compare rather than infer. Master-data uploads do not come that way, and their format is [OPEN].

The accessorial catalog is not entered here. It is code, along with the charges fuel applies to, the trigger definitions, the minimum billable weights and the dim divisor default (APPLICATION.md, master data and the reference standard) — staff read them at §8.1 rather than maintaining them.

Contents not yet designed, beyond §8.1 and §8.2.

Rules: APPLICATION.md, master data and the reference standard.

8.1 Rule report [phase 1]

The coded rules, read-only: the accessorial catalog, the charges fuel applies to, the trigger definitions, the minimum billable weights and the dim divisor default, grouped by rule rather than run together as one list. The screen carries no control that edits anything — there is nothing on it to edit, and an inert-looking control on a page of coded values invites someone to try.

It is generated from the constants the engine reads, so it cannot drift from them. A page transcribing the same values by hand fails silently: the page says 48 inches, the engine says 50, and nothing announces the gap.

Layout is [OPEN].

8.2 Region mapping [phase 1]

The region list, each row with its active flag, and for a selected region the ZIP prefixes mapped to it — three-digit, added singly or as a range, and by bulk upload for a set too large to type.

The screen has to say that adding a prefix another region holds moves it, because a prefix belongs to one region (APPLICATION.md, regions): the control that reads as an addition is also a removal somewhere else, and nothing else on the screen would show that.

Others carries no prefixes and cannot be deactivated. It is where a ZIP matching no prefix lands, so the screen offers neither control on it rather than offering them disabled.

A review surface lists the disagreements — ship-from locations where the client's declared region and the region resolved from the ZIP are not the same. This is what HappyShip audits (APPLICATION.md, ship-from locations), and a screen showing only the mapping would never surface it.

Layout is [OPEN].

---

9. Internal — management tool [phase 1]

A separate surface, reached only by a login bound to the HappyShip entity.

The shell is §1.1's — band, navigation, entity context and sign-out are the same here as on any screen, and are not restated below.

Three screens are settled, contents and arrangement both — §9.1 to §9.3. They are the seeding screens ARCHITECTURE.md's build sequence puts first; §9.4 is the rest, and stays a list until a screen is drawn for it.

Inter-screen navigation is [OPEN]: whether the tool carries a persistent navigation across the three screens, and whether a row in the entities list leads to entity detail or expands in place.

9.1 Entities

A list, with a create form above it. Create takes company name, nickname and country or territory, and nothing else — the line is drawn against the relationship and commercial fields, never against identifying ones, and the nickname is optional here because it can be set later on entity detail. The entityID is generated on save and never changes, including when the name is later corrected (APPLICATION.md, identifiers). The screen has to say so, because someone who does not know it will avoid correcting a name.

The list carries entityID, nickname, name, country or territory, whether the entity is authorized to publish, and the created date. Columns sort; search matches name or entityID. The HappyShip entity appears as a row like any other, marked internal.

The screen must not present an entity with no logins as incomplete. That is what every entity looks like before an address is logged against it (APPLICATION.md, entities), and a list that flags it sends someone looking for a defect.

Authorization is changed on the entity and never from the list. Delete is offered only while the entity has no logins and no cards (APPLICATION.md, entities).

Arrangement: the create form above the list, search above the table, and the explanatory notes at the foot below it. A note set between the form and the list would sit across the two things the screen is for.

9.2 Entity detail

Everything HappyShip holds about one entity. Six blocks:

• Profile — company name, nickname and country or territory, editable here; entityID and created date, read-only.
• Relationship and commercial fields — contact name, phone, email and location, HappyShip point of contact, contract expiration date or "no contract", services subscribed, profile status, payment method, currency, internal notes, and the document link. All are HappyShip's on this screen; which of them the client may edit is APPLICATION.md, entities. Services subscribed and profile status carry value sets that file marks [OPEN].
• Publish authorization — its state, and the control that grants or withdraws it. Withdrawing must say how many cards leave the pool, and that restoring authorization republishes nothing — the owner republishes card by card (APPLICATION.md, publication). Neither is a consequence anyone will expect from a single control.
• Logins — the entity's addresses and when each was logged, a delete on each, and a way to log another. Deleting says the session ends immediately and that cards that login published stay published (APPLICATION.md, identity and access).
• Rates managed — the entity's cards with rateID, nickname, derived status and effective dates, and the control that enters a card on the entity's behalf (§4.6).
• Ship-from locations — each of the entity's locations with its declared region, the region resolved from its ZIP, and a control to remap where the two disagree. Why HappyShip remaps at all is APPLICATION.md, ship-from locations; the locations themselves stay the client's to maintain (§4.7).

The per-entity counters — rates compared, rates published — belong here, being the only counts that survive a run (APPLICATION.md, retention). Revenue is not one of them and never becomes one here — it appears as an inert placeholder rather than a figure, under the placeholder exception in APPLICATION.md: greyed, non-selectable, non-clickable, carrying no value set, marked not in scope, and naming deferred work that is recorded as BL-001 in BACKLOG.md. Invoices audited carries a placeholder on the same terms, its deferred work named on that file's not-built list rather than in the backlog.

Arrangement: the entity's name is the page heading, its entityID beneath. Below that the blocks sit in two columns — profile, then relationship and commercial, on the left; publish authorization, the counters and logins on the right — and rates managed, then ship-from locations, run full width under both, each being a per-row table with a control where every two-column block is a single-record panel.

9.3 Logins

Every address across every entity: email, entity, entityID, and when it was logged. Search matches email or entity.

Logging an address is what creates the account. An address not logged here cannot sign in, and choosing HappyShip as the entity is what makes a login internal (APPLICATION.md, identity and access) — so the form takes the address and the entity and nothing else, and the screen has to make both facts plain. One address, one login, one entity.

A login is deleted rather than edited. Deletion ends its session immediately, and the address may be logged again afterward (APPLICATION.md, identity and access).

Arrangement: the same shape as §9.1 — form above, search above the table, notes at the foot.

9.4 Screens not yet drawn [OPEN]

Named because §9.1 to §9.3 are not the whole tool. Each waits on a screen, not on a decision:

• Uploading and naming reference-standard cards — a seeding screen like the three above.
• Reading and downloading any published card.
• Running a comparison across published cards against the same reference standard.
• Coupons — generate, set a value, assign to an entity.
• Payments — Stripe and coupon activity, and recording an ACH or wire receipt.
• Client activity — metadata only: who, when, which comparison, row count, exclusion count. Never rate values.

The last three are where ARCHITECTURE.md puts the remainder of the internal tool, after the gate.

Rules: APPLICATION.md, internal.

---

10. Leg and carrier differences

Sections 1 through 9 are shared. A leg or a carrier gets a section here only where a screen actually differs — an empty section is an invitation to fill it.

Most variation is not screen variation. The web form's fields and the template's shape belong to RULES-<leg>.md, and a new carrier usually changes neither the upload flow nor the dashboard. What can differ is a dashboard column set, or a form with enough fields to need a different layout.

• 10.1 Last mile — FedEx Ground and Home Delivery [phase 1] — no differences; the sections above describe it
• 10.2 Last mile, later carriers [not admitted]
• 10.3 Later legs [not admitted]

Nothing has content here until a second carrier or leg is admitted.

Audience: Claude Code, when a task touches the public website.

Scope of this file. The public site at happyship.us, end to end: what it is for, what it may and may not contain, and how it is built and published. A task touching the website reads this file and needs no other, with two exceptions below.

Read SCOPE.md first; where the two conflict, SCOPE.md governs. Two things stay there because neither is the website's alone: deploy discipline for web/ and brand/ — every change under either takes a branch and a PR — and the product the site markets.

The website has no further documents of its own. The shared ones — visual, dictionary, backlog, conventions — are listed in SCOPE.md under Which document to open, and are deliberately not repeated here.

Not the application. That is APPLICATION.md, and nothing here reaches it.

---

1. Purpose

A public landing page introducing HappyShip: what it is, who it is for, and how to make contact. It is marketing for the product of SCOPE.md, not part of that product.

Published in two languages, English and Simplified Chinese, which are the same page in translation rather than different content.

The site performs no authentication, carries no application functionality, and holds no client data. The "Sign in" link of §2 is a signpost toward the application, not a login.

The website is not where the plan is published. It carries the public-facing statement as it stands at any moment. SCOPE.md carries both the internal and the external view, and both the short-term and the long-term design. The two are not expected to match.

1.1 Sharing a repo is not sharing a surface

The site links to the application and describes it; it does not share code with it. **Nothing under web/site/ may import from, or depend on the contents of, app/.**

That is a prohibition rather than an impossibility. A build step exists (§5) and could be pointed at app/ as easily as at brand/. It is not, and must not be — build.sh copies from brand/ and from nowhere else.

What the two surfaces do share is the brand, deliberately and in one direction: both read brand/, and neither reads the other. One repository, two deployments, two boundaries.

---

2. In scope

1. The landing page, in two language versions: English at / and Simplified Chinese at /zh/, sharing one stylesheet and one set of assets
2. Contact route — a published address, no form handling in v1
3. A "Sign in" link in the site navigation. It goes to the application, but has no destination for now — the application has no deploy
4. Cloudflare Pages deployment from main, running ./build.sh and serving web/site/
5. Apex and www DNS, www redirecting to apex

Content is [OPEN]. The client-facing wording of the retention rule (APPLICATION.md, tracked as BL-005) constrains it.

---

3. Out of scope

Anything not in §2 may not be in scope for the website. Do not build it, stub it, or scaffold for it. Stop and ask — and only start work on it after it has been added to this document.

Specifically not in v1: forms that submit anywhere, analytics, blog, pricing pages, any link into the application other than the "Sign in" link of §2.

This boundary is the website's alone. Work admitted to the application at APPLICATION.md is not admitted here, and the reverse.

---

4. What the site is

A static site, hand-authored. No generator, no framework, no package.json, no dependency install. No server and no database.

The rule is not "no automation" — it is that nothing has to be installed before the site can be seen. A cp clears that bar. A build system does not: it brings a dependency tree, a lockfile, a toolchain version, and a site nobody can render without installing something first.

---

5. The build step

There is one, and it is a file copy. build.sh at the repo root copies brand/assets/ and any brand/*.css into web/site/brand/. It transforms nothing: no file's contents are read, rewritten, minified, bundled or compiled, and the bytes that land under web/site/brand/ are the bytes in brand/. Plain POSIX shell, no dependencies, safe to run repeatedly.

build.sh exits non-zero when:

• the repo root looks wrong;
• brand/ or brand/assets/ is missing;
• brand/tokens.css is missing from the source, or has not reached web/site/brand/ after the copy;
• any brand/*.css fails to copy;
• the number of files copied does not match the number found, counted separately for the assets and for the stylesheets.

A broken copy therefore fails the deploy rather than publishing a partial one.

5.1 The tokens.css guard

**brand/tokens.css is checked by name on both sides — in brand/ before the copy, in web/site/brand/ after it — never by asking whether the *.css glob matched anything.**

web/site/styles.css carries no hex value at all: every color, space, radius, weight and font stack resolves against tokens.css. A tokens.css that does not arrive therefore does not degrade the site, it unstyles it — and a copy step that reported success while doing that would be the worst form of the failure.

A glob test starts passing the moment any other stylesheet exists, which is a guarantee about the wrong file. A count proves how many stylesheets arrived and never which.

**The same reasoning is carried as a comment block in build.sh, beside the check.** It is written twice on purpose: here for whoever is deciding what the build does, and there for whoever is about to delete a line that looks redundant.

5.2 Why a copy rather than duplication

This project publishes only web/site/, so a file above it has no URL on the website and the site cannot reference it. That is a fact about this project rather than about the repo: a second Pages project publishes handbook.html from the repo root (SCOPE.md), so a file above web/site/ can have a URL — just never one the website serves. The application has no such constraint either — it builds, and can read anything in the repo.

That left three ways to share the brand: duplicate the assets in git, move the published root up and expose the governance docs along with it, or copy. Duplication is two masters for one thing, which is a whole class of drift — the class that ends in a logo, or a token value, differing between the site and the app with nothing to say which is right. One shell command removes that class.

The copy now carries the entire visual system rather than a folder of images, which does not change the reasoning above but does change how much rides on the copy succeeding. That is why it is verified file by file rather than trusted to have run.

---

6. What the build carries

brand/assets/ and brand/*.css reach the live site, at /brand/….

Nothing else above web/site/ does. app/, brand/STYLE.md and the governance docs at the repo root are not copied and have no URL on this site — handbook.html has one from a project of its own, which this build neither produces nor knows about. That holds for anything added at those paths later, without a rule per file — and it does not hold for anything added to brand/assets/ or a new brand/*.css, which the build step picks up and publishes by design.

The copy is mechanical and runs at deploy with nobody reviewing it, which is what makes the branch-and-PR rule on brand/ load-bearing rather than cautious.

**web/site/brand/ is generated output, not a source.** It is gitignored, never edited by hand, and never committed. brand/ is its only master: an edit made to the copy is overwritten by the next build without warning, and a copy committed to git is the second master this arrangement exists to remove.

---

7. The published tree

web/site/ holds index.html, styles.css, robots.txt, site.webmanifest, assets/, zh/, and the generated brand/.

A root-relative path resolves against the output directory, not against the repo root. Pages publishes web/site/ as the URL root, so the web/ prefix never appears in a URL: /styles.css is web/site/styles.css on disk, and the same path works from /zh/ without a second copy of the file. How deep the output directory sits in the repo is invisible to the URL space.

---

8. Pages

Adding a page is adding a file. The build step copies assets; it does not generate pages, so no page passes through it and nothing has to be rebuilt to add one. Pages serves the file tree under web/site/ directly, so a subdirectory does not change that either.

The Chinese page is that property in use: one more HTML file, sharing the one served stylesheet and the one copy of assets/.

**styles.css is never forked per language.** Language-specific rules are scoped within it by :lang(). Two copies of the same rules drift. brand/tokens.css is not that fork — it holds values where styles.css holds rules, which is a split by kind rather than a second copy of anything.

There is no custom not-found page, and that is a decision rather than a gap. Pages resolves a single top-level /404.html and does no per-directory lookup, so a per-language copy is reachable only by typing its own URL. Pages serves its own default instead. Restoring a custom 404 is an amendment to §2 first, not a file someone puts back because they noticed it missing.