docs: the map, a fresh index, and a register of dead ideas and revised claims
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>
This commit is contained in:
rajames
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
7aed588f78
commit
776c89457e
+67
-53
@@ -1,59 +1,73 @@
|
||||
# StarForth / LithosAnanke Documentation
|
||||
# StarForth / LithosAnanke documentation — the map
|
||||
|
||||
This is the `lithosananke` branch: the bare-metal StarKernel side of the project
|
||||
(contrast `master`, which is the hosted-VM-only side). Documentation follows the
|
||||
two-tier model described in `docs/CLAUDE.md`: **`formal/`** is the polished,
|
||||
citable LaTeX tier; **`working/`** is living design notes and drafts that feed it.
|
||||
Everything else in this directory is branch- or subsystem-specific material that
|
||||
doesn't fit either tier.
|
||||
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
|
||||
|
||||
- **[formal/](formal/)** — Three-volume LaTeX documentation set (research volumes,
|
||||
practitioner books, standalone reports) plus the `scraps/` fragment library it's
|
||||
assembled from. Audience: patent counsel, SSRN reviewers, licensees, hobbyists
|
||||
with hardware in hand. See `formal/CLAUDE.md` for authoring conventions.
|
||||
- **[working/](working/)** — Living documents: architecture design notes, DoE
|
||||
experiment logs, hardware/platform notes, draft specs, academic-paper source
|
||||
material, and an archive of superseded docs. Source material for `formal/`.
|
||||
- **[03-architecture/](03-architecture/)** — Tripod VM architecture constraints and the
|
||||
word-level ACL system design. (Note: the fleet is now **Hera/Artemis/Hestia** post-
|
||||
reshuffle; the old Hera/Hermes/Artemis framing in older docs is historical. The older,
|
||||
triaged copy of this tree is `working/architecture/03-architecture/`.)
|
||||
- **[lithosananke/](lithosananke/)** — LithosAnanke kernel branch documentation:
|
||||
milestone roadmap, system architecture, HAL reference, kernel command-line argument
|
||||
design, and the amd64 APIC-timer ISR postmortem.
|
||||
- **[birthing/](birthing/)** — VM birthing plan and status for the Hera-spawns-
|
||||
Hermes/Artemis constellation, plus three-architecture QEMU acceptance logs.
|
||||
- **[patent/](patent/)** — Provisional patent application source. **Legal hold —
|
||||
ask Bob before touching anything in this directory.**
|
||||
- **[api/](api/)** — Generated Doxygen tag file and warnings log (gitignored;
|
||||
not part of the tracked doc tree).
|
||||
- **[pptx/](pptx/)** — Elevator-pitch and deep-dive slide decks for different
|
||||
audiences (technical, non-technical, academic, PhD-level).
|
||||
- **[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.
|
||||
|
||||
## Current Active Work
|
||||
## Adding a document
|
||||
|
||||
> **⚠ `INDEX.md` is a dated triage snapshot (2026-06-16) and is stale.** The authoritative
|
||||
> current status lives in `.claude/CLAUDE.md` and `docs/fabric/FABRIC-2.md` /
|
||||
> `FABRIC-3.md` / `FABRIC-3.5.md` / `FABRIC-3.6.md` — not in the status tags in `INDEX.md`.
|
||||
|
||||
- **LithosAnanke M7.1 — live** — init capsules, the Tripod fleet, Stadium physics-economy,
|
||||
and word-level ACL (Phases 1–7 complete; Phase 8 Ed25519 PKI pending). See
|
||||
`lithosananke/ROADMAP.md` and the FABRIC documents above.
|
||||
- **Tripod VMs (post-reshuffle)** — Hera (governor), Artemis (memory/block storage),
|
||||
Hestia; the Hermes VM was removed and messaging moved into the kernel as kernel-Hermes.
|
||||
See `.claude/CLAUDE.md`.
|
||||
- **StarForth v4** — the F18-derived 32-opcode engine with the node/mesh design. See
|
||||
`v4.0.0/` and `../v4/README.md`.
|
||||
- **Word-level ACL system** — see `03-architecture/word-acl/` and `lithosananke/ROADMAP.md`.
|
||||
|
||||
## Contributing
|
||||
|
||||
- Place new material in `working/` first; promote to `formal/` only when it's
|
||||
ready to be cited (see `formal/CLAUDE.md` for promotion criteria).
|
||||
- Never touch `patent/`, `formal/patent/`, `formal/scraps/legal/`, or
|
||||
`working/legal/` without Bob's explicit instruction.
|
||||
- Add a `README.md` to any new category-level subdirectory, following the
|
||||
format used throughout this tree: orientation paragraph + bullet list of
|
||||
real files with one-line descriptions.
|
||||
- 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).
|
||||
|
||||
Reference in New Issue
Block a user