Skip to content
indexion-readme logo

indexion readme — README Construction

indexion-readme

README construction — initialize template structure, generate per-package READMEs from doc comments, plan writing tasks, assemble root README from docs/ and package READMEs via doc.json config, and verify edits with `plan drift`.

trkbt10/indexion-skills5.1Kinstalls2stars

SKILL.md

Full skill instructions

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:

AssetLocation patterns seen
Configdoc.json (repo root) or .indexion/​readme/​doc.json
Per-package templatedocs/​templates/​readme.md (no SoT constant; declared via --template)
Static prosedocs/​intro.md, docs/​installation.md, docs/​license.md, …
Per-package READMEscmd/<name>/​README.md, src/<name>/​README.md
Assembled root READMEusually 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)

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 or .indexion.toml pointing at one.

Step 2: Configure doc.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

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.

# 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)

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

# 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's [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):

# 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:

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:

PlaceholderExpansion
{{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

[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:

  1. 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.
  2. 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.

More skills from trkbt10

indexion-kgf logo
trkbt10/indexion-skills

indexion-kgf

Debug and inspect KGF specs — view tokenization results, parse trees, and extracted edges from source files. Use when adding/fixing language support or when indexion's analysis output looks wrong.

2 4.9K
View
indexion-wiki logo
trkbt10/indexion-skills

indexion-wiki

Project wiki lifecycle — create pages, track source changes with ingest, update stale pages, lint structural integrity, detect code-to-doc drift with reconcile, and manage search indexes. A runbook for navigating and maintaining the wiki as an agent.

2 4.9K
View
indexion-agent-orient logo
trkbt10/indexion-skills

indexion-agent-orient

Generate and use a pre-edit structure brief so coding agents learn likely owners, consumer surfaces, and unsafe edit locations before implementing.

2 4.9K
View
indexion-identity logo
trkbt10/indexion-skills

indexion-identity

Detect and review name/content drift in code using `indexion identity audit`, then plan verified renames, moves, folder changes, or splits.

2 4.9K
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View