indexion readme — README Construction

Build project READMEs from templates, doc comments, hand-written prose, and per-package READMEs. This skill covers the construction side: scaffolding, generating, planning, assembling, and verifying. For evaluating existing documentation, see

indexion-documentation

Where things live

The conventions vary by project; check what actually exists before editing:

Asset	Location patterns seen
Config	`doc.json` (repo root) or `.indexion/readme/doc.json`
Per-package template	`docs/templates/readme.md` (no SoT constant; declared via `--template` )
Static prose	`docs/intro.md` , `docs/installation.md` , `docs/license.md` , …
Per-package READMEs	`cmd/<name>/README.md` , `src/<name>/README.md`
Assembled root README	usually `README.md` . Some projects use a `.mbt.md` suffix so the file is also a MoonBit doctest module — when so, `README.md` is a symlink to `README.mbt.md` .
`.indexion.toml`	`[doc] config_path` / `per_package` auto-load doc.json

The first thing to check is

git diff

ls -la

for: a symlink on

README.md

, a

doc.json

(at root or under

.indexion/readme/

), and

.indexion.toml

. The presence of these tells you whether the README is hand-maintained, build-assembled, or a hybrid.

Workflow overview

doc init                      → .indexion/readme/template.md + doc.json (greenfield)
edit doc.json + docs/*.md     → declare sources of truth
doc readme --per-package      → cmd/<pkg>/README.md (API skeletons; non-overwriting)
hand-write each per-package README's Overview / Usage / Options / Examples
doc readme --config           → assembled root README
plan drift <prev> <new>       → verify the assembled output (or hand-edit) is purely additive

Step 1: Initialize (greenfield only)

bash

indexion doc init <project-dir>

Creates

.indexion/readme/template.md

.indexion/readme/doc.json

. Skip this step on a project that already has

doc.json

.indexion.toml

pointing at one.

Step 2: Configure doc.json

json

{
  "$schema": "./schemas/doc-config.schema.json",
  "version": "1.0",
  "spec": "moonbit",
  "output": { "format": "markdown", "filename": "README.md" },
  "packages": [
    {
      "path": "cmd/<name>",
      "title": "<command name>",
      "include_in_root": true,
      "sections": ["overview", "usage"]
    }
    // …one entry per package that should appear in the assembled root README
  ],
  "root": {
    "output": "README.md",
    "sections": [
      { "type": "static",   "file": "docs/intro.md" },
      { "type": "toc",      "title": "Commands" },
      { "type": "packages", "filter": "cmd/**" },
      { "type": "static",   "file": "docs/installation.md" },
      { "type": "static",   "file": "docs/license.md" }
    ]
  }
}

Root section types:

```
static
```
— include a markdown file verbatim
```
toc
```
— insert a table-of-contents heading
```
packages
```
— pull in entries from the
```
packages
```
array, filtered by glob

Package fields:

```
include_in_root
```
— whether to include in the assembled root README
```
sections
```
— README headings to extract; honored by per-package extraction flows. Note that
```
{ "type": "packages" }
```
in the root currently emits a table of package links, not the rich Overview/Usage expansion implied by per-package
```
sections
```
. See "Known limitation" below.

Step 3: Generate per-package READMEs

bash

indexion doc readme --per-package src/ cmd/

Generates

README.md

in each package directory that doesn't already have one. Non-overwriting — existing per-package READMEs are left alone.

The skeleton is API-only (extracted from

///

doc comments via KGF). Treat it as a starting point and hand-write the prose sections (Overview, Usage, Options, Examples) afterwards.

bash

# Single package to stdout
indexion doc readme src/kgf/lexer/

# Single package to a file
indexion doc readme -o=README.md src/kgf/lexer/

Note on side effects:

doc readme --template=<t> <paths...>

(the template-based mode below) walks the given paths and auto-creates per-package READMEs for any package that lacks one — even without

--per-package

. If you run it on a broad path (

cmd/

src/

), expect new files in unrelated packages. Run with a narrow path or grep

git status

afterwards to clean up unintended creations.

Step 4: Write static content

Create

docs/intro.md

docs/installation.md

, etc. — whatever your

root.sections

references. These are the hand-written prose; the assembler pulls them in verbatim.

Step 5: Generate writing plans (optional)

bash

indexion plan readme --template=docs/templates/readme.md --plans-dir=.indexion/plans src/

Emits per-section writing tasks for manual or LLM-assisted authoring.

Step 6: Assemble the README

bash

# Config-driven (preferred; doc.json controls layout and packages list)
indexion doc readme --config=doc.json

# Template-driven (alternative; {{include:…}} and {{packages}} placeholders)
indexion doc readme --template=docs/templates/readme.md -o=README.md cmd/

The config path can live at repo root or under

.indexion/readme/

. With

.indexion.toml

[doc] config_path = "…"

, the

--config=

flag becomes optional.

Step 7: Verify with

plan drift

After regeneration or any hand-edit of the root README, verify the change is purely additive (no silent deletions, no reflowing of unrelated sections):

bash

# Snapshot the previous version
git show HEAD:README.md > /tmp/README.before.md

# Compare against the new version
indexion plan drift --top=20 /tmp/README.before.md README.md

What to look for in the output:

Drift terms in /tmp/README.before.md (missing on the other side): (none)

— nothing was removed

```
Drift terms in README.md (missing on the other side): …
```
— exactly the new vocabulary you intended to add (command names, new flags, new concepts)
```
Cosine similarity
```
near 1.0 for a small additive change; substantially lower if you reshaped a section

For CI integration:

bash

indexion plan drift --vocab-threshold=0.05 /tmp/README.before.md README.md
# exits 1 if cosine_distance > 0.05 — useful as a guard against accidental large rewrites

This same workflow applies to translated README pairs (

README.md

↔

README-ja.md

): cross-lingual drift detection works natively because vocab sub-tokenization delegates to the natural-language KGFs in

kgfs/natural/

Template syntax

The template file supports

{{placeholder}}

substitution:

Placeholder	Expansion
`{{include:path}}`	Contents of the file (relative to project root)
`{{packages}}`	All discovered packages (filtered by CLI `--include` / `--exclude` )
`{{module_doc}}`	Module-level documentation only

.indexion.toml integration

toml

[doc]
config_path = "doc.json"   # auto-loads doc.json without --config
per_package = true         # makes `doc readme <path>` default to --per-package

Explicit

--config=…

always takes priority.

Known limitation:

packages

root section produces a table, not rich expansion

The

doc-config.schema.json

permits

sections: ["overview", "usage", …]

on each

packageEntry

, but the current

doc readme --config

implementation does not expand those sections inline when emitting

{ "type": "packages" }

in the root. The output is a markdown table of package links with empty descriptions.

Two practical consequences:

If the project's checked-in root README has rich per-command Overview / Usage paragraphs, they were not produced by
```
doc readme --config
```
as it stands now. They are hand-maintained. Diff
```
doc readme --config -o=/tmp/regen.md
```
against the checked-in README to see how much of it is hand-curated; very large diffs mean the README is mostly hand-maintained.
For new commands, you currently need to also hand-edit the rich section into the assembled README, in addition to adding the package entry to
```
doc.json
```
and writing the per-package README. Use the
```
plan drift
```
verification above to confirm the hand-edit only adds, never removes.

If you fix this limitation (so

{ "type": "packages" }

honors per-entry

sections

), update this skill to remove this section.

Common pitfalls

"doc readme --per-package generated nothing"

All packages already have READMEs. The command only creates new files, never overwrites. Delete existing READMEs first to regenerate.

"doc readme --template … on
cmd/
created READMEs in packages I didn't touch"

Template mode auto-generates missing per-package READMEs as a side effect. Either pass a narrow path, or revert unintended creations from
```
git status
```
.

"Auto-generated per-package READMEs are just API listings"

By design. Hand-write Overview, Usage, Options, Examples. For CLI commands, the authoritative behavior comes from
```
indexion <command> --help
```
.

"My hand-edit to README.md will be wiped out by
doc readme --config
"

It will if the assembler ever produces the rich shape (see "Known limitation"). Until then, the assembler produces a strict subset (the table) and your hand-edits to the rich sections survive. Always run the
```
plan drift
```
cross-check to be sure.

"README.md edit destroyed unrelated sections"

Run
```
plan drift HEAD:README.md README.md
```
and look at the "missing on the other side" output for the previous version. If it lists anything other than
```
(none)
```
, you removed content.

indexion-readme

NPX Install

Tags

SKILL.md Content

indexion readme — README Construction

Where things live

Workflow overview

Step 1: Initialize (greenfield only)

Step 2: Configure doc.json

Step 3: Generate per-package READMEs

Step 4: Write static content

Step 5: Generate writing plans (optional)

Step 6: Assemble the README

Step 7: Verify with
`plan drift`

Template syntax

.indexion.toml integration

Known limitation:
`packages`
root section produces a table, not rich expansion

Common pitfalls