Handoff
Everything in this repository is finished and none of it explains itself to somebody who was not here. This page is the one link that replaces the explanation: where to start, what you are holding, how it behaves, what it is made of, and how to add to it without breaking the rules that are keeping it whole.
Three doors, and the middle one is the product
Open the product first. Everything else on this page makes sense once you have seen a screen.
If you only have five minutes
Open the product, then why.html. That is the whole orientation. The rest of this page is for the day you have to change something.
The same three doors, published
Nothing here needs a clone, a build or a server. Every address below was requested on the day this section was written rather than remembered, because a link nobody has opened is a claim and not a route.
| What | Address |
|---|---|
| The repository | github.com/sergiodesign4u-dot/predict-market |
| The product | the Event Feed, published |
| The system | why.html, published |
| The front door | the repository index, published, which is where a stranger should be sent |
The published root answered 404 and every deep link answered 200
Worth knowing, because it is the one class of defect this package cannot see. A file at the root keeps the roadmap panel and the whole vitrine route alive on the published site, and its cost is that no page is generated from the README. So each of the three doors above worked and the address a person would actually be handed did not, while every instrument here passed: they all open files, and not one of them reads a response code. A route is only a route where somebody has walked it.
What this package is, and what it is not
It is not a running application. There is no build step, no server, no API, no router and no product code. What you open in a browser is what ships. That is deliberate, and the reason is written where the rules are: a repository that once carried dozens of generators and build gates deleted all of them in one commit and the product did not move a pixel.
| In the package | Inside the folder, outside the package |
|---|---|
| The painted product, the grey structure tree, the design system, the vitrine, the shared assets, and every source document under research, user research, IA, voice and concept. It is what version control tracks. | Two Python virtual environments, a nested tool repository, the critique logs and the editor configuration. All excluded from version control. They are tooling that happens to sit in the same directory. |
A state is a page. Loading, empty, error, signed in, signed out, chosen: each is its own file, in both trees. That is not a convenience, it is the only reason a state can be measured at all. A rule that cannot be rendered cannot be checked, and it will be wrong the day it first draws.
What it becomes
The software plan is decided and not started: the stack, the hosting, the routes and the cost are in docs/build-plan.md. This package is what that plan is built FROM, not a first version of it.
Where everything is
One row per question. Every destination here is one click from this page, and this page is one click from the README, so nothing in the package is more than two clicks from the root.
| If you want | Open |
|---|---|
| To see the product | ui-visual/event-feed.html, and overview.html for the index of all of it |
| To see the system | ui-kit/why.html, then ui-kit/overview.html for a page per component |
| The rules you must not break | CLAUDE.md at the root, then the one in the folder you are working in |
| How the system is built | ui-kit/docs/architecture.md, and components/tokens.css, which is a document as much as a stylesheet |
| What every component is and where it stands | ui-kit/docs/inventory.md |
| What the product IS | PRODUCT.md: the job, the audience, the market types, the money, the open legal question |
| Where a reader can go | ia/docs/sitemap.md and ia/docs/flows.md |
| Every word the product says | voice/docs/microcopy.md, and voice/docs/voice.md for which words are allowed |
| Why anything is the way it is | docs/decisions.md, dated, newest first, never edited |
| What is still open | docs/backlog.md |
| Why every screen exists twice | The grey tree in wireframes/ owns structure and copy and the painted tree owns the visual layer only. It is frozen and it is history of the process, not a source you edit: read its conventions once and then work in the painted tree |
When two documents disagree, the repository is right
Prose goes stale and code does not. Measure the thing, then believe the file that owns it, then believe the prose. Every fact here has exactly one owner, and the ownership table is in the root CLAUDE.md.
Which theme is primary
The dark theme is the product. The light one exists to prove that the semantic token layer is real: a second theme can only be written by re-declaring roles, so if the roles were fake the light theme could not exist. It is a proof, not a preference.
The shipped product has no theme switch. The toggle you can see lives in the reviewer's panel down the left of every screen, which is review chrome and not the product. In the source it looks like an ordinary button; in the rendered page its only ancestor is that panel. Anyone reading the markup alone will ship a theme switch into the product by mistake.
If you write a probe that reads the theme
The theme boots from browser storage before the first paint, and the boot script removes the attribute when there is no stored value. Setting the attribute is therefore not setting the theme. Every theme-aware reading needs a control: the page ground has to differ between the two runs, or you have measured one theme twice.
Behaviour, the map, and accessibility
Nothing else in the repository answers these three questions, because a page renders a state and cannot tell you what reaches it, what it is made of, or what it promises a reader who cannot use it the ordinary way.
| Document | The question it answers |
|---|---|
| behaviour.md | What the product DOES: five flows step by step, every terminal and its recovery edge, the states each surface has, what each field enforces, and the edge cases where the obvious build is wrong. Every row cites the source that already said it, and a row with no source is not in the spec at all: it is in the NOT DECIDED list at the foot, addressed to a person. |
| map.md | Which screen is made of which components, which tokens those read, where each zone gets its words. Then the same data inverted, which is what the file is for: if I change this token, what moves. It opens in two knees, component to role to primitive, because a component never names a raw value and a one-knee list reports the whole primitive level as dead. |
| a11y.md | Every accessibility ruling the system already carries, each with the instrument that checks it and a status of two values. Confirmed means a run on the day, not a memory that an earlier stage did it. Three rows are debts and each names its backlog row. |
| onboarding-gaps.md | The critique log of this stage: what a reader with no context could not work out, and what they worked out wrongly. The second list is the expensive one. |
How to add a feature
There is a documented procedure for adding a component and for adding a pattern, in architecture.md. There was none for adding a SCREEN, which is the first thing a new person needs and the thing they will assemble wrongly out of six files. one-shot.md is that procedure, written as a prompt you can hand to somebody or to a model and get a finished screen back.
The rule underneath all of it
New goes into the system first and onto a screen second. A screen that grows a part every time it meets a new page has not been tested by that page, it has been edited by it. If your screen needs something with no component, no token and no pattern behind it, that is not an exception for the screen, it is an order for the system.
Who decides now
Two open lists in this package are addressed to a person rather than to a process: the NOT DECIDED rows at the foot of behaviour.md, and docs/backlog.md. Without an addressee the first such row stops the work, so the addressee is named here.
| Question | Decided by |
|---|---|
| Everything about the product, the design and this repository | The one person who wrote all of it. There is no second contributor, no owners file and no maintainer list, and that is a fact about the project rather than an omission |
| Jurisdiction, and therefore what the four legal documents actually have to say | Counsel, on retainer before the first real money moves. It is the one decision in this package whose owner is not in the repository, and it is written that way in PRODUCT.md |
| An open row's answer, once taken | Goes into docs/decisions.md with its date, and the backlog row is struck rather than deleted |
What was deliberately not done
So that a decision is not read as a hole. Each of these is a ruling with a reason, not something that ran out of time.
- No product code. The plan for it is decided and dated; this package is its input.
- No build gates and no generators. They were deleted on purpose. Every rule is kept by being read, and each one carries the measurement that produced it.
- No production domain. Open by decision, with the cost written beside it: no canonical address and no share address can be written until it is chosen. The trigger and the decider are both named.
- No support screen. Registered as a node, decided post-release, because it carries a form and a form is a different page type with its own vocabulary and its own states.
- No registry for the two screen trees. The vitrine and the course roadmap each have one; the screen trees carry their panel as copied markup in every file. It is a known debt, it is written in the vitrine's own registry, and closing it is an edit to every document in both trees.
The full list, with a row per item and the stage that owns each, is docs/backlog.md.
What was unclear, and what it became
This stage was not an audit of the product. It was an audit of whether the product can be picked up, and the reader was a subagent with a clean context rather than an imagined newcomer: whoever builds a thing cannot read it, only recall it. Its two lists, verified line by line, are in onboarding-gaps.md.
| Was unclear | Became | Who found it |
|---|---|---|
| How do I add a screen? There is a procedure for a component and for a pattern and none for this | one-shot.md, a prompt rather than a checklist of edits | the entry reader |
| What does the product actually do between screens? | behaviour.md, five flows and seventeen terminals with a source on every row | the entry reader |
| If I change this token, what moves? | map.md, the inverted list, in two knees | the entry reader |
| What is already promised about accessibility, and is it still true? | a11y.md, thirteen points, each with the instrument that checks it and a status of two values | the entry reader |
| Is this an app? Where is the start command? | The boundary section above | the entry reader |
| Which theme is real, and why is there a switch? | The theme section above | the entry reader |
| Who do I ask? | The governance section above | the entry reader |
| The one address a person is handed answered nothing, while every deep link answered | A front door at the root of the repository, which holds no fact of its own | the published site, asked rather than remembered |
| A node can be built, refused, or waiting, and the guidance named two of the three | The three states as a table in one-shot.md, with the test that separates a refusal from a deferral | the first examination |
| Which page is the base one, when the screen is a control and not a view | The representative state, and the choice written down where the type is banked | the first examination |
| One accessibility row carried a status from an earlier stage with its instrument named and never run | A debt with its own measurement: four documents have no heading at all | the first examination |
| Ask the block bank whether your composition is banked, and it holds one page type and no product screen | Expect no, and use the bank's method: a built precedent beats a specification of one | the second examination |
| The layer boundary was counted two ways in five files, one of them the file loaded whole every session | One count, turned and dated in all four live claims | the second examination |
| This package published an accessibility checklist on a page that failed the text criterion | One palette value swept over fourteen documents; the rest filed rather than swept | the closing critique |
The contract this stage held itself to
Written before the work and checked at the end, as its own table rather than as a paragraph claiming it went well.
| The rule | How it was checked | Result |
|---|---|---|
| The reader is a clean context, never an imagined newcomer | three runs, each with the forbidden paths named one by one and a reading journal as the proof | held. No forbidden path opened in any run; two readers disclosed a near miss unprompted |
| Documentation references, it never copies | a mechanical read of every file in the package for a colour, a length, a shipped string or a rule | held. Zero on every class |
| Every behaviour row cites one of exactly three sources | the spec's own roll-call, closed with a number | held. A row with no source is in the open list addressed to a person, and there are ten |
| A point with no instrument never gets a status | the checklist read against itself | broken once, and that is the entry worth keeping. One row carried a status inherited from an earlier stage; an examination found what it was hiding, and it is a debt now |
| This stage documents; it does not repair the product | the record of what was changed | held. Both examination screens reverted and kept on branches; thirteen open rows filed instead of fixed. The one repair made is in the course chrome, which is not the product |
| Every route opens | every link in the package and its route, resolved against the disk, against a control | held. Zero dead |
| A count is computed, or it is dated | read across the files that carry one | held after eighteen repairs, and the last two were found by a reader rather than by a sweep |
| The second examination's list is shorter than the first | the two lists, counted | NOT held. Ten and ten. Split by who owns the gap it went from five to two, and none of the five closed came back, but the rule as written was not met and it says so in the log |
The habit worth taking with the repository
Numbers here move and prose lags behind them. Treat every figure without a date beside it as a claim rather than a fact, and re-measure before citing one. That rule caught eighteen stale claims during this stage alone, in the files whose own job is to state it, and the last two were found by readers who had never seen the repository before.