rajamesandClaude Opus 5.5
776c89457e
docs/CLAUDE.md Phase 1 output, after the reorganisation. - docs/README.md: rewritten as the map -- where each kind of document lives, which one to believe (CLAUDE.md, FABRIC, v4.0.0, reference/, BRINGUP, code), how to retire a document. - docs/INDEX.md: regenerated from the tracked tree, 489 rows, every document with a status (the 2026-06-16 snapshot was stale). - docs/DEAD-AND-REVISED.md (new): what was abandoned (L4Re, the hal_* contract, ACL RWT, the Hermes VM, elevation, the knowledge factor, ...) and what was corrected (ACL overhead, versions, block rules, parity baseline, ...), each with its date and record. - docs/DELETE-CANDIDATES.md: 12 duplicates, awaiting a ruling; nothing deleted. - CLAUDE.md: versions corrected (3.2.0 / 2.1.0). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
74 lines
4.1 KiB
Markdown
74 lines
4.1 KiB
Markdown
# 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).
|