Skip to content

Authoring Guide

How content in this repo is structured. Read this before adding or editing a page — consistency here is what makes the dashboard and search actually work, and what lets someone else's Claude read a brief and answer questions about it correctly.

Front matter

Every page except this one and the generated index.md needs:

---
type: brief | side-quest
status: draft | active | shipped | parked
project: <matches the top-level docs/ folder the page lives in>
summary: one line — this is what shows up on the dashboard
slack_thread: https://neosframe.slack.com/...   # optional, add once a thread exists
---
  • type — brief for a structured technical brief (the Resolver Engine and Template Composer sections are the reference shape: Foundations → Features → Examples, with Risks / Open questions / Done when tails on feature pages). side-quest for anything smaller or more exploratory — a working-notes doc, a decisions log, a one-off investigation. There's no third type; if something doesn't fit either, it's probably a side-quest.
  • status — the whole lifecycle is four states:
  • draft — being explored or written, not settled yet
  • active — this is the current position; still being built out
  • shipped — the thing this page describes is built
  • parked — deprioritized, not being worked on right now
  • summary — one sentence, plain language. This is what a non-technical teammate sees on the dashboard before they ever open the page.
  • slack_thread — where feedback on this doc should land. Fill it in by hand today; a future capture tool may create it automatically.

Editorial policy: current position only

A page states where things stand today. It never narrates how a position was reached, reopened, or revised — when a position changes, the old text is replaced, not kept alongside a "later superseded" note. This isn't a new rule — it's Template Composer's existing policy, now applied everywhere, because git actually keeps the history now: git log on any page is the changelog (shown per-page as "last updated"). A project that also has a hand-written history doc (Template Composer's history/template-composer-notes.md) keeps using it for the why behind past decisions; the page itself never does.

Structure

Follow the existing pages as templates rather than inventing a new shape:

  • Brief landing page (<project>/index.md) — Why this exists → Summary → a diagram if there's a pipeline/flow worth showing → the hard cases/scope → non-goals → a linked list of the brief's sub-pages.
  • Brief feature/foundation page — H1 the concept, prose + examples, then whichever of Risks / Open questions / Done when actually apply. Done when is the one section every feature page should have — it's the acceptance criterion.
  • Side-quest — no fixed shape, but say up front (an admonition is fine) that it's exploratory and hasn't been decided yet — see retail-studio-layout/index.md for the reference tone.

Keep using: titled admonitions (!!! note "...") for status/scope/warnings, the headerless two-column metadata table on landing pages, → for page-to-section cross-links ([Coordinate System → Pivot](...)).

Adding a new project

Each project is its own self-contained mkdocs site — separate mkdocs.yml, separate nav, separate search index. Clicking into a project from the dashboard means you're inside that project alone, not a shared global sidebar.

  1. New folder under projects/<project-slug>/, with its own mkdocs.yml (copy an existing project's as a starting point — same theme/extensions block, its own docs_dir: docs, site_dir: ../../site/<project-slug>, site_url: https://briefs.neosframe.ai/<project-slug>/) and its own nav:.
  2. Landing page at projects/<project-slug>/docs/index.md with front matter.
  3. Run python scripts/build_all.py — it picks up the new project automatically (it discovers every folder under projects/) and adds it to the dashboard.

A link from one project into another is a root-relative URL (/other-project/some-page/), never a Markdown relative link — there's no shared docs_dir for that to resolve against, since each project builds independently.

What's deliberately not built yet

  • No automatic Slack-thread creation.
  • No aggregate changelog page — per-page "last updated" (from git) ships today; a dated changelog view is a follow-up.
  • No braindump-to-brief capture tool yet — write directly, or ask Claude to draft from your notes by hand.