LithosAnanake/docs/CLAUDE.md

CLAUDE.md — StarshipOS Documentation Root

Instructions for Claude Code

Location: docs/CLAUDE.md

Mission

The documentation for StarshipOS/StarForth/LithosAnanke is scattered across the repository. It exists in multiple forms, at multiple vintages, with no consistent structure. The immediate goal is to triage, reorganize, and establish a two-tier documentation system that can support patent review, academic citation, commercial licensing, and hobbyist adoption.

Cash flow depends on this. Treat it accordingly.

---

Two-Tier Documentation Model

docs/
├── CLAUDE.md          ← you are here
├── Makefile           ← builds both tiers
├── formal/            ← polished, versioned, citable (LaTeX → PDF)
│   └── CLAUDE.md      ← formal/ specific instructions
└── working/           ← living documents, design notes, active drafts
    └── CLAUDE.md      ← working/ specific instructions

docs/formal/

Three-volume LaTeX set. Audience: patent counsel, SSRN reviewers, potential licensees, paying customers, hobbyists with hardware in hand. Nothing goes here until it is ready to be cited. See formal/CLAUDE.md for all authoring conventions.

docs/working/

Living documents. Design notes, DoE logs, architecture decision records, experiment reports, draft specs, prose not yet promoted to formal. These are NOT garbage — they are the source material that feeds formal/. The distinction is audience and stability, not quality.

---

Makefile Targets

Corrected 2026-08-18 — this section previously described a docs/Makefile with docs-formal/docs-working/docs-index/docs-audit/docs/docs-clean targets. That file does not exist and none of those targets exist anywhere in the tree. The real build lives one level down, at docs/formal/Makefile, with a different target set entirely:

# Run from docs/formal/

make            — everything: all three volumes + books + standalone docs + doxygen
make vols       — vol1 + vol2 + vol3 (the three-volume LaTeX set)
make vol1       — Volume I only
make vol2       — Volume II only
make vol3       — Volume III only
make books      — dev-guide + user-guide + cookbook
make standalone — experiments + proofs + ssrn + patent (standalone LaTeX docs)
make doxygen    — API reference PDF (requires the `doxygen` binary installed;
                  runs doxygen → fix-doxygen-unicode.py → doxygen/latex → PDF)
make clean      — remove build artifacts

docs/working/ has no build step of its own (no HTML rendering target exists) — it's read directly as markdown. docs/INDEX.md exists but is maintained manually, following this file's own Phase 1 triage process below — there is no docs-index/docs-audit automation that generates or checks it; treat INDEX.md as something a triage pass produces by hand, and expect it to go stale between passes (confirmed stale as of this correction — check its own date against git log -1 before trusting it).

---

Phase 1: Triage (DO THIS FIRST)

Before writing, moving, or deleting anything, conduct a full inventory pass.

Step 1 — Find everything

Locate every documentation file in the repository. Cast a wide net:

find . -type f \( \
  -name "*.md" \
  -o -name "*.txt" \
  -o -name "*.tex" \
  -o -name "*.rst" \
  -o -name "*.adoc" \
  -o -name "*.org" \
  -o -name "*.pdf" \
  -o -name "*.odt" \
  -o -name "*.docx" \
\) | sort > /tmp/doc-inventory-raw.txt

Also check for README files without extensions:

find . -name "README*" | sort >> /tmp/doc-inventory-raw.txt

Step 2 — Read and classify each file

For every file found, read enough to assign it one of these status tags:

Tag	Meaning
CURRENT	Accurate, up to date, reflects present architecture
WORKING	Active draft or living design document, still being edited
HISTORICAL	Accurate for its time, superseded but worth keeping as record
SUPERSEDED	Replaced by a newer document — note which one
OBSOLETE	Refers to architecture, naming, or design that no longer exists
DELETE	No value. Duplicates, temp files, auto-generated noise

Step 3 — Produce docs/INDEX.md

Create docs/INDEX.md with one entry per file:

| Path | Topic | Status | Notes |
|------|-------|--------|-------|
| src/starforth/README.md | StarForth build instructions | CURRENT | Good candidate for Vol I Ch 3 |
| notes/old-ssm-design.md | Early SSM design | SUPERSEDED | Replaced by SSRN paper |
| scratch/ivmp-draft-v1.txt | IVMP protocol | HISTORICAL | Hermes spec v0.5.1 supersedes |
| tmp/foo.md | Unknown | DELETE | Empty file |

Do not delete anything during this pass. Tag only.

Step 4 — Report to Bob

After producing INDEX.md, summarize:

• Total files found
• Count by status tag
• Top candidates for promotion into formal/ chapters
• Files recommended for deletion (DELETE tag) — list them explicitly and wait for confirmation before removing anything

Never delete files without explicit confirmation from Bob.

---

Phase 2: Reorganize

Only begin Phase 2 after Bob has reviewed and approved the INDEX.md triage.

Moving files into docs/working/

Files tagged CURRENT or WORKING that are not yet in docs/working/ should be moved there. Use this naming convention:

docs/working/
├── architecture/      — system design, capsule model, Uberkernel
├── experiments/       — DoE logs, run reports, raw data notes
├── specifications/    — IVMP, Jacquard, ACL, capsule specs
├── hardware/          — board bring-up notes, platform specifics
├── legal/             — patent-adjacent material (handle carefully)
├── papers/            — SSRN drafts, Math Companion, academic writing
└── scratch/           — genuinely informal notes, not yet categorized

When moving a file:

1. Move it with git mv to preserve history
2. Add a one-line header comment if the file format supports it:

   <!-- Moved to docs/working/architecture/ from [original path] — [date] -->
   

3. Update INDEX.md with the new path

Files tagged HISTORICAL

Move to docs/working/archive/ with a dated prefix:

docs/working/archive/2024-ssm-early-design.md

Files tagged SUPERSEDED

Move to docs/working/archive/ and add a header noting what supersedes it:

<!-- SUPERSEDED by docs/formal/common/starship.bib — citation james:2024:ssrn -->

Files tagged DELETE

List them in a file called docs/DELETE-CANDIDATES.md and wait for Bob.

---

Phase 3: Seed formal/

After working/ is organized, identify passages, sections, or entire documents in working/ that are ready to be promoted into formal/ chapter stubs.

For each candidate:

1. Note the source file and section in a %% SOURCE: comment at the top of the chapter stub
2. Do not copy blindly — adapt to the formal/ voice conventions in formal/CLAUDE.md
3. Mark anything that needs Bob's dictation with:

   %% TODO(bob): [description of what's needed here]
   

The goal of Phase 3 is compilable stubs, not finished chapters. Every chapter in all three volumes should exist as a .tex file that compiles without errors, even if most of it is TODO comments.

---

Ground Rules

• Never delete without confirmation. Tag as DELETE, list, wait.
• Never rename Bob's technical terms. James Law, SSM, Uberkernel, Hades, Jacquard Selector — these are proper nouns.
• Never invent content. If you don't have source material for a section, stub it and mark TODO.
• git mv, not mv. All file moves preserve history.
• One commit per phase. Triage in one commit, reorganize in another, seed formal/ in a third. Clean history matters.
• INDEX.md is the source of truth for what exists and where it lives. Keep it updated as files move.
• Ask before touching legal/. Anything patent-adjacent gets flagged for Bob's explicit instruction before moving or editing.