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

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

Scope of this file. What the application builds, and how the user experiences it, at high level. What is built is the repository, never a list here; what survives here is the decision behind it.

Out of scope. The website, and the consulting services.

Related but not elaborated here — architecture, style, calculation rules.

The document is evolving.

• UX decisions made pre-build are marked [UNBUILT]. They may change during the build, and a present-tense passage is not a report on running code. The marker closes when the thing is built.
• Do not reject the build if the chat discussion is not aligned with this file — stop and ask.
• The alternatives considered and the options rejected behind a decision are logged in DECISIONS.md where they are needed.
• Open items are marked [OPEN] or recorded in BACKLOG.md.
• Work surfaced during a build is added as a section in the respective document, not as a new file.

---

1. Product and phases

1.1 Services and service legs

The four services are defined in SCOPE.md. Their boundaries are §4 to §6 below; which are admitted is §11.

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.

1.2 Phases

The application is built in phases, and a phase is a decision, not a document. It is defined by the product owner and is not always strictly tied to a leg.

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

---

2. Foundations

2.1 Language

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.

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 browser is the default on first arrival for both; the login's settings govern once one exists. The locale the browser reports resolves to CN where it is any Chinese variant, and to EN otherwise. Traditional resolves to CN. The mapping is rewritten when a locale is added. A user may toggle either at any time, and the toggle writes to the login.

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, maintained by HappyShip, is the supported path and the default. Which file formats the parser accepts is the build's.

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

Files that resemble the template but do not conform are rejected with a clear reason rather than interpreted.

Non-template files are a service. HappyShip staff may convert a client's non-standard file into the HS template, which then enters through §4.5. In module 1 the handoff is offline, by email. In module 2 the client attaches a file and shares it with HappyShip, and once HappyShip has converted it the client approves the file. In module 3 a recurring non-HS-template file is parsed automatically. At launch, module 1 is sufficient. It is recorded here so nobody builds a second parser.

The card-entry path carries a how-to, on the client path and the internal one alike, covering how to fill the template and what is rejected.

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 (§5).

A card upload reports two distinct things, and they do not behave the same way. Rejections stop the upload. Confirmations do not. The confirmation set and the plausibility bound are RULES-<leg>.md. This is an act of card upload, not of a run; the substitution acknowledgment of §5 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. Where two services within a carrier product group 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.
4. A test asserts behavior, never the repository's content. A count of documents, markers or sections pins what happens to exist rather than what the code does, so an ordinary documentation commit turns the suite red and the assertion has to be lowered rather than fixed. Assert against a fixture the test constructs, never against the repository the code happens to be run over.

2.4 Interface patterns

Written once, instantiated everywhere. A new leg reuses these rather than copying them.

Two surfaces: internal, and clients.

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

Entity context and entity identification are different, and the shell must not collapse them. The internal tool reads across entities, so it shows which entity is in view — a context that changes while the login does not. A client login binds to one entity 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 in the shell, and it is the only control that ends a session. A session also ends on its own, on limits ARCHITECTURE.md sets; no screen states them.

Language and time zone are set from the shell, taking effect immediately.

The run pattern is upload → validate → acknowledge → run → dashboard → report. A card upload uses the first two stages and stops at stored: nothing about it runs and it produces no report.

• 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).
• The report is the record, because the run leaves nothing behind (§7). A screen implying a result can be reopened is describing something that does not exist.

Exception management. What stopped the work and what was found and did not stop it are both shown for the client's acknowledgment. Card upload, comparison upload and every master-data upload show both, visually distinct.

• Rejection. The blocking column is exhaustive on the first pass, because a fail-fast parser turns a twenty-error file into twenty round trips.
• Non-blocking findings. An apparent deviation from the standard or the norm is highlighted. The test is whether a substitute can be used, or a condition changed, to proceed.
• Empty state. An empty state that is normal must not be dressed as incomplete — a region added but not yet mapped is empty in a way that does mean something is unfinished. The test is whether the empty state is where the thing is meant to rest or a stop on the way somewhere else.

Loading and long-running work is [OPEN]. Nothing beyond "it may take a few minutes" says how long a run takes, what the screen shows while it runs, or whether a user may navigate away. It waits on the job execution model (ARCHITECTURE.md) and on what session expiry looks like part-way through a run.

2.5 The ID scheme

Two rules, not one. An entityID identifies an entity. A typed ID identifies one record belonging to an entity and embeds the entityID that owns it. They share an alphabet for their generated characters and share nothing else.

An entityID is four characters — one letter A-Z, then three from the safe set. It is generated by HappyShip at entity creation, randomized and collision-checked at issue, and never supplied by a user. 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.

A typed ID is eleven characters — an entityID, a hyphen, one type letter, then five from the safe set. It is unique within one entity and one type rather than globally. Stored with the hyphen; a stored value not matching the pattern is a defect, not a variant. The format itself is the build's.

Two alphabets, because two different things are being protected.

• The safe set governs the generated characters only — positions 2 to 4 of an entityID, and a typed ID's five-character suffix. It excludes the characters that confuse visually — 0/O, 1/I/L, 2/Z, 5/S, 8/B — because a machine produces those characters and a person reads them back, and that exchange is what the exclusion protects. That is the reason the set is not wider, and the alphabet itself is the build's.
• The type letter is chosen, not generated. It sits in a fixed position with no generated character beside it, so nobody has to tell it apart from one. It takes any letter or digit, and the confusable exclusions do not reach it.

**This is why S is a type letter while staying outside the safe set:** the two alphabets answer different questions, and S is chosen rather than generated. It leaves the HS reservation below untouched — that argument turns on position 2 of an entityID, and position 2 is generated.

**HS is reserved as an entityID prefix for HappyShip's own entities**, the last two characters being a country code for a branch office — HSUS, HSCN, HSHK. It collides with nothing because S is excluded from the safe set, so no generated ID can begin HS. The reservation is forward-only: it governs entities allocated from now on, and HappyShip's incumbent US entity predates it, keeps the ID it was given, and does not move.

The type letters.

Live means a table stores identifiers of that type and constrains the letter — R alone, in rate_cards, whose CHECK accepts an R and rejects every other letter. Reserved means the letter is claimed and no table will accept one. A reserved letter becomes live when the table that stores it is built, and that table carries its own constraint, as rate_cards already does for R.

A table that stores a typed ID constrains its first four characters to the owning entity. rate_cards carries that CHECK beside the letter's own, and every table that goes live with a letter carries the same pair. The rule is what makes a typed ID's uniqueness checkable by the entity that owns it: isolation hides other entities' rows (ARCHITECTURE.md, isolation), so without the constraint a collision could sit in a row the checking session cannot see, and the check would report clear against an identifier already issued. With it, every identifier that could collide belongs to the owning entity and is already visible. A table built without it does not fail loudly — it produces a check that is silently wrong.

**R is minted by app_new_rate_id(); no other letter has a generator.** It runs under the caller's own binding rather than as a definer, because the owner-prefix rule above makes the collision check answerable from inside the entity's own visibility. It returns a candidate and does not insert, so the write path carries the retry: rate_cards_pkey is the backstop if two sessions draw the same suffix between the check and the insert. An entityID is generated separately, at entity creation. A reserved letter has no generator and no table, and gains both together.

The reassignment cost no migration, and the next one will not be so cheap. S and C carried placeholder meanings in the schema — a shipment set and a charge file — but nothing was ever issued under either, so freeing them moved no stored value. That is the whole reason this was safe, and it is not a precedent: once a letter is live, the rule below governs instead.

A letter is registered in the type-letter catalog, and a generator reads it before minting. app_new_rate_id() refuses unless R is live there, so the catalog is what a generator is checked against rather than a record kept beside one. Adding a letter is still a schema change; the catalog remains master data with no write path, and nothing consults it at any other moment.

A reserved letter can be added or removed freely, because nothing carries it. A live letter cannot. The type letter is stored inside the identifier rather than beside it, so changing one rewrites the stored value of every row that carries it — and the foreign keys referencing those values declare no ON UPDATE, so they reject the update outright. Removing a live letter is a data migration, not a deletion.

---

3. Entities and access

3.1 Entities and authorization

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

• 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 (§8).

HappyShip creates the entity record with its first login; the client completes it. The identifying fields — entityID (§2.5), company name, nickname, country or territory — are HappyShip's to set and correct. The client maintains its own contact details and its ship-from locations (§3.3). The relationship and commercial fields are HappyShip's and read-only to the client. Which fields exist is the build; what follows are the decisions about them.

• Country or territory is on ISO 3166-1, because separate customs territories are separate rows. A create form defaults to the browser's region, which the operator corrects; the screen must not present it as a detection.
• The country is the entity's headquarters, not a shipping location. Ship-from locations and their regions are §3.3, and the two are unrelated.
• [UNBUILT] Phase 1 offers four values: the US, mainland China, Hong Kong, and Other. Hong Kong is separate from mainland China for the reason above — separate customs territory, separate row. Other is not a country: HappyShip does no business outside the three in phase 1, so the value captures that the headquarters is elsewhere and records nothing further. The build ships the full ISO list today, and a test pins both its length and that Hong Kong, Macao and Taiwan render, so narrowing it is a code and test change rather than configuration.
• The value sets for services subscribed and for profile status are not settled. Services subscribed depends on BL-001 in BACKLOG.md. [OPEN]
• Currency is what the client pays HappyShip in, not what a card is denominated in. Cards are USD in phase 1, so no conversion exists 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).

An entity with no logins is a normal state, not an incomplete one.

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

Who may become a client, and on what terms. A client may be created only to compare rates or to subscribe to another service.

• Compare rates — in phase 1 HappyShip creates the client; a client with a company email address may self-register in a later phase. The service is free, on conditions that are [OPEN].
• Manage rates — the client must be created by HappyShip staff and must agree to the service terms and conditions. Self-service is a later phase. The same holds for audit invoices and track shipments.

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 §8 rests on that split.

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

Access is by invitation only. HappyShip creates an entity with its first login email address, and that record is the account. The client may add further logins. An address that is not logged cannot log in.

An entity may bind several logins, and they all see the same thing. [UNBUILT] Each entity is permitted up to three; no limit is enforced today. No per-login view, no per-login permission, nothing one login can do that another cannot — that would be a role system under another name, which §3.1 forbids. Language and time zone are the only things held per login (§2.1).

Passwordless. A six-digit verification code is emailed to a pre-registered address. No stored passwords and no reset flow. There is no sign-up — the first visit and every later one are the same two screens, an address then a code. Code expiry, resend cooldown and wrong-attempt limits follow industry standards; nothing here needs inventing. An unregistered address gets a page with a link to the website's contact form, and a delivery failure has one recovery path: contact us.

A session survives a browser close and ends on its own, on the limits ARCHITECTURE.md sets. Signing out is the only way a user ends their own. What expiry looks like part-way through a run is [OPEN].

Internal access is entity binding, not a role. HappyShip is itself an entity; a login registered against it is internal. The address is never inspected — no domain match, no list, no role field. Two conditions must both hold: the internal surface was reached (§9), and the login is bound to HappyShip.

Recording which login acted is not a permission. Publication and withdrawal record the acting login and a timestamp (§4.4). The record answers who, not who may.

There is no edit on a login's identity. The address is the account, so correction is delete and recreate.

• Deleting a login ends its session immediately, checked per request rather than at expiry. Delete serves both a typo and 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; deleting a login sends a notification. Both are sent outside a session, so both are EN. A delete-and-recreate correction sends both within moments, and the wording must survive that. There is no suppression window.

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

3.3 Regions and locations

Regions are master data maintained by HappyShip (§9): 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.

[UNBUILT] A US region may hold 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. No prefix is stored today and nothing resolves a region — a location's region is declared directly.

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

An entity may hold several ship-from locations, and the client maintains them. ZIP is required. The entity's own address is not a ship-from location. Holding none is a valid state.

[UNBUILT] Each location maps to a region, and the ZIP is what resolves it. The seller may declare a region and is not required to; HappyShip audits the declarations and may remap. Remapping works today; the resolution the audit compares against does not exist, so a declaration cannot yet disagree with anything. The declaration is a hint, never the answer — a must-met condition tested against a seller's own unverifiable claim is not much of a test, and resolving from the ZIP makes the same condition checkable. The screen must not present a declared region as the answer.

The warehouse service leg will add attributes to this object; they are not admitted — carried as placeholders under §11.2, deferred as BL-008.

---

4. Rate cards — manage rates

Lite — upload, conditions, lifecycle, publication, all below. 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 admitted. 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]

4.1 Definitions

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 (§9).

A reference standard may be converted from a carrier-published rate card or declared by HappyShip as a template. It may or may not have published rates tied to it; with none tied to it, it is the same as a rate template. A reference standard is not versioned. [OPEN]

Rate classes.

Two kinds of rate card.

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

Shipment sets follow the same split, but only the transient half is admitted. 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 serve invoice audit, which is not admitted — named so the symmetry is on record, and not built or scaffolded for (§11.2).

How a card is identified, last mile. *[→ RULES-LAST-MILE.md; stays here until that file receives it.]* Reference standard → rate group → rateID → nickname.

• Reference standard is the carrier's published rates. A carrier publishes official rates once a year and continues to issue edits, conditions, new rates and seasonal charges through it. Example: FedEx Ground & Home Delivery 2026.
• Rate group is assigned by HappyShip when a reference standard is selected. It drops the year and keeps the carrier's main services. Example: FedEx Ground & Home Delivery.
• rateID is a rate with a set of conditions defined on the web form. One of the first selections is the rate group, which is how the two are mapped.
• Nickname is user-defined per rateID and shows on the user's dashboard.

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 (§8.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.

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.3), and that is deliberate — the declaration is coarse on purpose.

The requesting entity states a set of regions per run, or none (§5.1). 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.

RateCondition is evaluated per run against the requesting entity's serviceability facts (§5.1). What a condition can express, and how it is evaluated, is RULES-<leg>.md. The region list as it stands, and the condition's evaluation, are written in RULES-LAST-MILE.md.

*[→ RULES-<leg>.md; stays here until that file receives it.] Multiple conditions set by the rate seller are an AND: the buyer must meet all of them. Multiple conditions set by the rate buyer are an OR, with AND as the perfect match.* [move to RULES?]

4.3 Lifecycle

The lifecycle states are the build's, and the set is closed. An expired card cannot generate a new quotation, but can still compute a comparison or an invoice validation.

Lifecycle is set by the user, not computed. A card is created as draft and the owner promotes it; the owner archives it when finished with. Expiry is the one exception, being automatic.

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.
• Three conditions must all hold to publish: the entity is authorized, the owning entity sets the flag, and the owner accepts the terms. [UNBUILT] — the third is new; the build enforces the first two. Authorization is an entity-level setting HappyShip controls, and it exists so that entering the pool can be charged for. Only the client may authorize publishing: the owner reviews the card's content and conditions once more and clicks I agree to HappyShip's policies before publishing, which is the legal condition of entering the pool. Separately, a published card must declare at least one region (§4.2). That precondition is different in kind — the three above are consent, the region declaration is completeness — so the 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 (§7), 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 admitted. Publication is the only way a card becomes comparable to others.
• A single status label may be derived from lifecycle plus flag for display, never stored. The label set is the build's. No control may turn publication on as though it were a status step: an entity's own buy rates are active and must never enter the pool, and that separation must not sit one misclick from going active.
• Publishing must be explained where it is offered, because the word suggests display and that is not what happens: a published card is comparable to other entities, never visible to them.
• "You have not published this" and "your entity cannot publish" must be distinguishable. An unauthorized entity meeting a dead control with no explanation concludes the product is broken. What that state offers is [OPEN].
• The three ways a card leaves the pool must not be presented as one event. Only one is a decision by anyone at the entity.

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

Reference standards, including carrier-published rates, are HappyShip's and internal only.

For a client's rate card there are 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, and the owner is emailed when it lands, so a transcription can be checked before anyone stands behind it. 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.

The internal path diverges from the client's at two points. At the start it asks what kind of card — client, or carrier published — and names the entity the card belongs to; a client has neither, the entity coming from the session. At the end a client's card lands as a draft in that client's library, while a carrier-published card becomes a HappyShip-owned card plus a designation.

The order of what is asked is the same on both paths, and it is this:

1. What kind of card — client, or carrier published. Internal only.
2. Rate owner — the entity the card belongs to. Internal only.
3. The reference standard, from those already designated. It names the carrier, the service group and the leg, so choosing it settles all three and they are read rather than asked for. A carrier-published card branches here: it has no standard to name because it becomes one, so it asks for carrier and service group directly, those being what determine the template's shape.
4. Describe the card — nickname, dim factor, FSC discount, currency and weight unit, notes.
5. Thresholds — the conditions, each marked must-met or prefer-met with no default (§4.2).
6. Download and fill.
7. Upload, then declare which services the card covers, after the parse.
8. Saved as draft.

The card's details are settled before the file is downloaded, and the effective dates sit in the file's header block rather than on the form. No reason is recorded for the ordering beyond that it was chosen during design (DECISIONS.md).

4.6 The library dashboard

The output of manage rates is the user's dashboard, showing the state of the rate cards the entity maintains.

---

5. Comparing — compare rates

5.1 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.
• They are the only input the pool is filtered on.
• They are the entity's own claim. Nothing verifies them, and a false claim produces a comparison against cards the entity cannot actually use.

5.2 The 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."

The two are chosen first, because they take different inputs. Serviceability facts are then supplied on the web form (§5.1), and the rates or shipments either uploaded on the HS template or — for rate-for-rate — selected from the entity's own library. An uploaded file here is transient and nothing may offer to keep it.

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

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.

5.3 The run-time pool

A comparison runs against every published card, filtered by the requesting entity's serviceability facts (§5.1) 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.

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.

5.4 Output

The output is a dashboard result, with the option to download an executive summary. Neither the dashboard nor the downloaded report is stored for retrieval. The output does not list rateID, entityID or any other identifier — where a client is happy with a rate, the next step is to contact HappyShip.

What the dashboard and the report must both carry, constrained by §8.1. Layout is [OPEN].

• An executive summary — where the entity's card stands in the pool, against the reference standard and against the cheapest serviceable rate; and where a shipment profile was supplied, the total cost difference against both.
• Counterparties labeled by a reference code, different in every run. The reference standard is named outright, being public.
• The same codes in the PDF, since no run record survives to resolve them against later.
• Marked substitutions — every line priced at the reference standard because the card lacked mandatory data.
• The count of the entity's own priced lines above the reference standard.
• Excluded cards as a count and a reason, naming the condition type only.
• Prefer-met flags, with the rate and the condition type.
• The consultation CTA.

After the run the screen must be honest that nothing is retained rather than implying a result can be reopened. What it offers is the download, and the report already in the entity's inbox.

---

6. Audit invoices and track shipments

[OPEN] — filled when the two are scoped. Neither is admitted (§11.2).

---

7. 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. An ID that appears on a delivered PDF is never 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. [UNBUILT] Which ID types the ledger covers follows the revised scheme at §2.5. No ledger exists: issued_ids was dropped in migration 0015, and nothing had ever been issued under it, so a ledger is new work rather than a migration of stored identifiers.
• 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 §8.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.

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

---

8. Isolation and visibility

8.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 §9.

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 (§7), 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 (§7), 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.

8.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 (§5.3), 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).

[UNBUILT] 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).

---

9. The internal surface

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.

**The client surface opens on a menu of the four functions, labeled exactly as SCOPE.md names them** — one vocabulary across the documents and the interface. A function not admitted is inert: a label, not a route, a stub, or a screen that explains itself.

The internal tool covers five areas:

• Manage clients — create, delete and archive an entity, authorize an entity to publish, set the document link. The terms on which a client is created are §3.1. A client is responsible for its own locations; mapping them to regions is optional for the client and may be overwritten by HappyShip staff.
• Manage master data — countries and territories, regions, rate groups, the published national fuel surcharge index.
• Manage rates — create reference standards, define HappyShip charge codes, publish carriers' published rates, draft a client's rates.
• Manage billing — view a client's account, record ACH payments manually, issue coupons.
• Reference documents — rules, vocabulary.

9.1 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.

9.2 Internal reference views

The rule report 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 (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 admitted (§11.2).

---

10. Billing and metering

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

[UNBUILT] 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.

[UNBUILT] 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.

[UNBUILT] 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.

[UNBUILT] The account surface shows the balance and each coupon held with its expiry, rather than one merged number. Stripe is the path; ACH and wire are instructions rather than a form that submits. An exhausted balance blocks a run and leaves the account reachable so the entity can pay — what that blocked state looks like at the point of running is [OPEN].

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

---

11. Phase 1

This section says what phase 1 admits, not what exists. What is built is the repository — the migrations, the modules and the tests — and no list here can stay true to it. A passage describing admitted work that does not exist yet carries [UNBUILT].

11.1 Admitted

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 carries 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 §11.2 governs. Phase 1 purges.

11.2 Not admitted

Anything not listed in §11.1 is not in scope. If you are asked to build it, stop and ask — and only start work on it after it has been added to §11.1.

A placeholder is allowed, to remind us of a future build. It must be greyed and not clickable, it carries no value set, and it stores nothing. The deferred work it names must be recorded — as a BACKLOG.md row, or by being named in the not-admitted list below — so the placeholder is a reminder of something recorded rather than the only record of it.

Named explicitly, because each is described somewhere and could be mistaken for admitted: derivation of sell rates from buy rates (§4) · invoice audit (§6) · shipment tracking (§6) · stored shipment sets (§4.1) · card sharing by rateID (§4.4) · the internal control tower (§9.2) · 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 cards).

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.

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 typed identifier's owner prefix is a CHECK, and the collision check depends on it. rate_cards constrains the first four characters of rate_id to entity_id. Forced row-level security means a session sees only its own entity's rows, while a unique constraint is enforced beneath those policies and sees every row — so a SELECT-based collision check inside a bound session can report clear against a row it cannot see, and the INSERT then fails on a constraint the check never consulted. The prefix CHECK removes that gap by confining every identifier that could collide to the owning entity, which is the session's own visibility. It is a precondition of the ID scheme (APPLICATION.md, the ID scheme), not a local nicety, and a table minting a new type letter without it inherits the gap.

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 (APPLICATION.md, internal reference views) — 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 reach 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 surface).
• 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 surface).
• 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]
• The card-entry function, which writes a card and its rows into another entity's library on HappyShip's behalf (APPLICATION.md, who writes a card). It is the only one that writes card contents; the roster, entity-record and login-address functions above it write too. [UNBUILT] It does not log.

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.

A write exemption is bounded by what it may write, since a return type bounds nothing when the point of the call is its effect. app_card_create_for returns one identifier and writes a card and its rows into another entity's library, so the return type is no ceiling at all. What bounds it instead is the set of tables it touches, its parameter list (there is no parameter for an entity other than the target, nor for a rateID), the values it fixes rather than accepts — a card it writes is always a draft and never published — and the grant that lets it run, held by one role the internal surface alone uses. Widening any of the four takes a migration somebody can see, which is what the rule above is for. [UNBUILT] It does not yet log, and the audit write described below is where that belongs: no cross-entity write logs today, and a write into another entity's library is the one that most obviously should.

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 needs no application running (SCOPE.md), so 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 (APPLICATION.md, identity and 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).

In practice, this file is FedEx Ground and Home Delivery. §2 through §7 are written against that carrier throughout — the charge code set, the 139 divisor, the trigger thresholds and the grid shape are all FedEx's, not the leg's. A second carrier arrives as its own sections under §8 rather than as a new file (SCOPE.md, service legs), and §8.2 records what it will need.

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, which is why the standard is not a post-upload form field (APPLICATION.md, ingest). 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 FedEx Ground & Home Delivery 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, 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 cards). 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.2.
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).

Several conditions on one card are an AND. The buyer must meet all of them. Several regions or facts stated by the buyer are an OR, with a full match being the perfect one — which is why stating more widens the pool rather than narrowing it (§3.2).

3.1 How a card is identified [phase 1]

Reference standard → rate group → rateID → nickname. That a card names the standard it is compared against, and what a reference standard is, are APPLICATION.md, rate cards.

• The reference standard is the carrier's published rates. A carrier publishes official rates once a year and continues to issue edits, conditions, new rates and seasonal charges through it. Example: FedEx Ground & Home Delivery 2026.
• The rate group is assigned by HappyShip when a reference standard is selected. It drops the year and keeps the carrier's main services. Example: FedEx Ground & Home Delivery.
• The rateID is a rate with a set of conditions defined on the form (§2.6). One of the first selections is the rate group, which is how the two are mapped.
• The nickname is user-defined per rateID and shows on the user's dashboard.

3.2 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).

A second carrier in this leg needs a normalization layer before anything compares across the two. Recorded here so it is not discovered at build time; nothing acts on it now.

• Zones do not correspond. A FedEx zone 5 is not a UPS zone 5, so a zone-indexed grid cannot be read across carriers without a mapping (ARCHITECTURE.md, known future work).
• Charge codes do not correspond. The set at §2.3 is FedEx's, closed and coded. A second carrier arrives as its own coded set, so comparison needs a mapping between the two — and where a charge exists on one side only, an absence rather than a zero.
• Trigger definitions and minimum billable weights do not correspond. §4.1's thresholds are FedEx's published values. Another carrier's AHS equivalent tests different measurements at different limits, so a package can be surcharged on one card and not the other for reasons the comparison must state rather than net out.
• Structural equality (§5.5) currently rejects what it cannot compare. That is the right behavior while one carrier exists; across carriers it would reject everything, so cross-carrier comparison is a different mechanism rather than a loosened check.

---

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. [UNBUILT] is different — the decision is made and the build has not caught up — and it is deliberately not collected as an open question. Nothing in the open-questions list will ever be an [UNBUILT].
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.

Because numbers are banned, a cross-file reference names the file and the topic inside it, which makes a section's name a citation. Renaming one breaks every reference to it exactly as silently as renumbering would. A restructure searches the other files for the old names before it lands.

---

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 describe the application whole — every phase, every leg. ARCHITECTURE.md is 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 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.