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:

```bash
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:
```bash
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:

```markdown
| 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:
   ```latex
   %% 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.