# StarForth / LithosAnanke documentation — the map

Start here. This page says where each kind of document lives and which one to believe.
Reorganised 2026-10-14 (the docs triage): one place for current reference, one archive for
everything kept as record, and every superseded or abandoned document labelled as such in
its own header.

- **[INDEX.md](INDEX.md)** — every document in the repository, with its status.
- **[DEAD-AND-REVISED.md](DEAD-AND-REVISED.md)** — the ideas that were abandoned, and the claims
  that were revised, each with the date and where the decision is recorded.
- **[DELETE-CANDIDATES.md](DELETE-CANDIDATES.md)** — duplicates proposed for deletion, awaiting a
  ruling.

## What to believe

| For | Authoritative | Where |
|---|---|---|
| How to work in this repo, and current status | `.claude/CLAUDE.md` | repo root |
| What was decided, and why; work as it happened | the FABRIC record | [fabric/](fabric/) — `FABRIC-3.md` is the living one |
| StarForth v4 (the F18-derived engine) | the v4 design | [v4.0.0/](v4.0.0/) and `../v4/README.md` |
| Roadmap and release-versioning policy | `ROADMAP.md` | [reference/](reference/) |
| Getting onto the boards | the bring-up checklist | `../boards/BRINGUP.md` |
| A word, a primitive, a term | the dictionaries and the ontology | [reference/](reference/) |
| What the code does | the code, and its folder's `README.md` | `../kernel/`, `../v3/`, `../v4/` |

Where two documents disagree, the one higher in this table wins, and code wins over all.

## Layout

- **[fabric/](fabric/)** — the design and work record, numbered in order. `FABRIC-3.md`
  (bare-metal boot and everything since) is open; the others are closed:
  - FABRIC-0, -1 and -2 are history;
  - FABRIC-3.5 and -3.6 are the Tripod/kernel reshuffle, still authoritative for what they ruled;
  - FABRIC-3.7 (elevation) is closed as not needed;
  - FABRIC-4 holds ideas caught early, not yet scoped.
- **[v4.0.0/](v4.0.0/)** — StarForth v4: justification, engine, decomposition, nucleus, mesh,
  parity with v3. `plans/` holds the step plans, all executed.
- **[reference/](reference/)** — current reference material:
  - `ROADMAP.md` (roadmap and the ratified versioning policy);
  - `M7.1.md` (init capsules and birth);
  - `word-acl/` (the word-level ACL design);
  - `kernel-args/` (the boot command line);
  - `hosted-acceptance-test/`;
  - `DICTIONARY.md` and `STARFORTH_PRIMITIVES.md` (the words);
  - `ONTOLOGY.md` (the lexicon);
  - `L8_ADAPTIVE_CONFIG_TABLE.md`.
- **[working/](working/)** — living material and the source for `formal/`:
  - `architecture/` (design notes and HOWTOs);
  - `experiments/` (DoE designs and campaign data);
  - `papers/` (academic sources, the system narrative, proposals);
  - `hardware/`, `specifications/` and `scratch/`;
  - **`archive/`**, which has four parts:
    - `historical/`: finished work, kept as record;
    - `superseded/`: replaced, and each file's header names what replaced it;
    - `dead/`: abandoned or never adopted;
    - the older `legacy/`, `quality/`, `operations/`, `research/` and `session-logs/`.
- **[formal/](formal/)** — the press-ready LaTeX tier (three volumes, books, standalone
  reports). Governed by `formal/CLAUDE.md`.
- **[book/](book/)** — the LithosAnanke and StarForth book build.
- **[pptx/](pptx/)** — slide decks for different audiences.
- **[patent/](patent/)** — provisional patent material. **Legal hold: ask Captain Bob before
  touching anything here** (also `formal/patent/`, `formal/scraps/legal/`, `working/legal/`).
- `lithosananke/hal/` — the last of the old `lithosananke/` folder: duplicates of the dead HAL
  contract, listed in DELETE-CANDIDATES.md.

## Adding a document

- Draft in `working/`; promote to `formal/` when it is ready to be cited (`formal/CLAUDE.md`).
  Reference material that describes the system as it is goes in `reference/`.
- When a document is overtaken, do not delete it: `git mv` it into `working/archive/superseded/`
  or `dead/` with a header saying why and what replaces it, and add a line to
  `DEAD-AND-REVISED.md`.
- Rules for documentation work: [CLAUDE.md](CLAUDE.md).