@fivespark/docs-template

A drop-in, layered documentation system you can scaffold into any project's docs/ folder with one command. Each layer has one declared audience and one job, and the layers link instead of duplicate — one source of truth per fact.

Usage

In the target project's root:

npx @fivespark/docs-template init

It prompts for a project name, then writes the docs tree into docs/. It never overwrites existing files (skips them) unless you pass --force.

npx @fivespark/docs-template init --name "Acme Portal"   # skip the prompt
npx @fivespark/docs-template init handbook                # target a different dir
npx @fivespark/docs-template init --force                 # overwrite existing files
npx @fivespark/docs-template init --help                  # all options

The only placeholder substituted on copy is {{Project Name}}. The other {{...}} markers ({{page}}, {{component}}, {{Theme}}, …) are intentional fill-in-later slots in the templates.

What it scaffolds

docs/
├── README.md            ← the map: every doc + its audience + purpose
├── OVERVIEW.md          ← 👥 "what & why", plain-language, meeting-friendly
├── ARCHITECTURE.md      ← 🛠️ "how it's built", for developers
├── PLANNING.md          ← 📋 build schedule / milestones (optional)
├── specs/               ← 🛠️ "exact details" — the source of truth per screen
│   ├── README.md
│   ├── _page-template.md
│   ├── _component-template.md
│   ├── OPEN-QUESTIONS.md
│   ├── pages/           ← one file per page (thin: composes + links out)
│   └── components/      ← one file per reusable block (owns its data/states)
└── decisions/           ← 🛠️ ADRs — the "why we chose X"
    ├── README.md
    ├── _template.md
    └── NNNN-*.md         ← numbered, never deleted (supersede instead)

The three rules that hold it together

1. One source of truth per fact — link, don't duplicate. OVERVIEW summarizes and links the specs; it never re-explains them. A page spec stays thin and links out to component specs.
2. Audience is declared. The root README.md maps each doc → audience → purpose, so anyone lands in the right place.
3. Docs are alive — updated in the same PR as the code. A feature isn't "done" until its OVERVIEW status line and affected specs are updated.

Key patterns

• Pages compose, components own. A page lists its blocks and links out; any block large enough to own its own data/states/estimate gets a component spec, linked from the page's Sub-component specs and linking back via Used on.
• States + Estimate as tables. Every spec ends with a State | Behavior table and an Estimate table broken down by scope — the estimates roll up into PLANNING.md.
• OPEN-QUESTIONS as a buffer. Park unresolved decisions in one consolidated, themed file; answer once and propagate the answer back into the affected specs.
• ADRs are append-only. Number sequentially, never delete — supersede with a new ADR and flip the old one's status.

Publishing (from a monorepo subfolder)

This package can live inside a larger repo (e.g. an AI-docs repo) and still be published on its own — npm publish only ships what the files field whitelists (bin/, template/, this README), ignoring the rest of the repo.

cd docs-template      # the package folder inside your repo
npm version patch     # bump the version
npm publish           # publishConfig.access=public is already set for the scope

To dry-run exactly what would ship: npm publish --dry-run.

If the repo root has its own package.json, you can instead make this a workspace and publish with npm publish -w @fivespark/docs-template.