Skip to content

W-106: Documentation site structure

Type: chore · Size: M · Epic: E-setup · Target: zensical.toml and docs/ · Breaking: no Depends: – Refs: zensical.toml, docs index, AGENTS.md (Layout), pyproject.toml (zensical dev dependency)

Goal

Build the foundation of the Zensical site in docs/: a configured zensical.toml (site name, description, and an explicit nav that follows the folder structure; URL and repository settings wait on the open questions) and a folder structure in which each subfolder (products/, specs/, work/) has an index.md and is reachable from the nav. The nav contains: Home, Concept (docs/concept.md), Demos (docs/products/ with index.md), Specs (docs/specs/ with index.md, sub-grouped into Demos and Packages), and Work (docs/work/ with index.md, with Board (docs/board.md) nested under it, then Archive). Top-level order: Home, Concept, Demos, Specs, Work. zensical build passes. The existing zensical dev dependency is used, so no new dependency. Scope is structure and navigation only: replace the Zensical template sample pages (docs/index.md, docs/markdown.md) with minimal pages that have a title and one line each, remove markdown.md from the nav, and delete it in an explicit step. No new copy beyond that. Page content is not rewritten, including links that leave docs/; those are only listed.

Steps

Nav approach: explicit nav in zensical.toml. Each section lists its index.md first, so navigation.indexes (already enabled) makes the section title the index page. docs/work/ has about 100 W-NNN files, so the nav lists only work/index.md, board.md and work/archive.md (under Work). Zensical, like MkDocs, is expected to build pages that are not in an explicit nav (reachable by URL and by links, absent from the sidebar); S4 verifies this. The W-NNN pages are reached through the board table links (work/W-NNN-*.md) and the work index.

  • S1 (scaffold): write the minimal pages, each a title plus one line, no template front matter or sample sections: docs/index.md (what the site is, same wording as README.md line 3), docs/products/index.md (product briefs, one per demo), docs/specs/index.md (package and demo specs), docs/work/index.md (work items, with one link to ../board.md and one to archive.md); files: docs/index.md, docs/products/index.md, docs/specs/index.md, docs/work/index.md
  • S2: in zensical.toml [project], set site_name = "zard ecs" and a one-line site_description (same wording as docs/index.md), and replace the nav with the explicit nav: Home (index.md), Concept (concept.md), Demos (products/index.md first, then the 4 brief files), Specs (specs/index.md first, then sub-group Demos: demo-anno, demo-ck3, demo-dnd, then sub-group Packages: ecs-devtools, ecs-prefab, ecs-relations, ecs-schedule, ecs-serialize), Work (work/index.md first, then Board (board.md), then work/archive.md); markdown.md is not listed. Leave site_url, repo_url, repo_name, edit_uri, copyright unchanged until the open questions are answered; files: zensical.toml
  • S3: delete the template sample page docs/markdown.md (explicit step; nothing links to it after S1 and S2); files: docs/markdown.md
  • S4: run uv run zensical build (fall back to zensical build if uv is not used) and fix structure and nav errors only (TOML syntax, wrong paths, missing nav files). Confirm the docs/work/W-*.md pages are built although they are not in the nav; if Zensical drops them or fails, record it in the Log and raise open question 3 instead of listing 100 files by hand. Then check the build for links between docs pages: board.md to work/W-NNN-*.md, specs/* to ../products/*, work/* to ../specs/*, ../products/*, ../concept.md#..., and W-NNN-*.md. Fix only breaks caused by this item (nav, new index pages). Also list links that leave docs/ (../../.github/skills/..., ../../AGENTS.md, ../../README.md, ../../reference/..., ../../packages/...), which cannot resolve in the built site. Write the broken in-docs links and the out-of-docs links (count per top-level target) into the Log; do not rewrite content; files: zensical.toml (only if the build requires it), Log
  • S5 (optional part approved 2026-11-02): add the missing ignore entries for the build output (site/) and .venv/ to the root .gitignore (neither is covered today; only dist is); optionally, only if trivial, add a line under ## Docs in README.md with uv run zensical serve and uv run zensical build, and matching docs and docs:build scripts in the root package.json. Skip the optional part if it needs more than those lines; files: .gitignore, optional README.md, package.json
  • S6 (acceptance): uv run zensical build passes; the built nav shows Home, Concept, Demos, Specs, Work in this order, with Board nested under Work (Work > index, Board, Archive) and Specs split into Demos and Packages sub-groups, each section with its index as landing page; docs/markdown.md is gone; the board links to the W-NNN pages (the work index links to the board and archive, per S1); git status shows no change to apps/, packages/, or docs/board.md; no new dependency in pyproject.toml, package.json, or the lockfiles; the Log lists the broken in-docs links and the out-of-docs link groups

Open questions

  1. (answered 2026-11-02: defer) site_url: the placeholder https://www.example.com/ is wrong. What is the real deployment URL, or should the line be removed until the site is published? (Not guessed; S2 leaves it as is.)
  2. (answered 2026-11-02: defer) repo_url, repo_name, edit_uri, copyright, site_author: what are the repository URL and the copyright holder? Without them, no edit or view links and no copyright footer. Also, should content.action.edit / content.action.view be enabled once edit_uri is known?
  3. (answered 2026-11-02: accept) docs/work/ in the nav: the plan lists only work/index.md and work/archive.md, so the W-NNN pages are reachable via board links and are not in the sidebar. Is that accepted? Alternatives: list all ~100 files by hand (stale on every new item), or use a generated nav (needs a script, out of scope).
  4. Work and Board: the Work section holds the work index and archive, and Board stays a separate top-level entry (a page should not appear twice in the nav). Should work/index.md link to ../board.md only, or is another layout wanted? (answered 2026-11-02: Board is nested under Work in the nav, Work > index, Board, Archive; top-level order Home, Concept, Products, Specs, Work.)
  5. (answered 2026-11-02: list every file) Section pages in the nav: Products and Specs list every file so they appear in the sidebar. As more demos or specs are added, zensical.toml must be updated. Accepted, or should these sections only list the index (like Work)?
  6. (answered 2026-11-02: defer, list only) Links that leave docs/ (about 20 files link to ../../reference/..., ../../.github/skills/..., ../../README.md, ../../AGENTS.md) will render as broken links on the site. Is a follow-up item wanted (rewrite to plain text or absolute repository URLs once repo_url is known)? This item only lists them.
  7. (answered 2026-11-02: add README line and root scripts) S5 (optional part): should docs/docs:build scripts go in the root package.json, or is Python tooling kept out of it (README line only)?

Log

  • 2026-11-02 created from user request under E-setup (Triage)
  • 2026-11-02 sized M, epic E-setup (Triage)
  • 2026-11-02 placed in Later, not prioritized (Triage)
  • 2026-11-02 Goal changed (user decision): docs/board.md and docs/work/ are now in the nav, with Home, Concept, Products, Specs, Work, Board (Planner)
  • 2026-11-02 Steps written, 6 steps, 7 open questions; nav approach: explicit nav, section indexes, work/ lists only index and archive (Planner)
  • 2026-11-02 moved Later -> Next, plan awaiting user approval (Triage)
  • 2026-11-02 open questions for user: site_url; repo_url, repo_name, edit_uri, copyright; nav layout (work/ index only); links outside docs/
  • 2026-11-02 plan approved by user (Triage)
  • 2026-11-02 answers: Q1, Q2, Q6 defer (site_url, repo_url, repo_name, edit_uri, copyright unchanged; links outside docs/ only listed, follow-up later); Q3 accept; Q5 list every file in Products and Specs; Q7 approved: README line and root docs/docs:build scripts (S5 optional part approved). Q4 not answered, still open (Triage)
  • 2026-11-02 moved Next -> Now, state active (Triage)
  • 2026-11-02 S1 attempt blocked by guard hook: Implementer scope excludes docs/ pages, zensical.toml, .gitignore, README.md, package.json; user widens Implementer scope (Triage)
  • 2026-11-02 user decision: docs/index.md wording uses README line 3 (project description), not line 5 as the S1 text says (Triage)
  • 2026-11-02 user switched implementer for docs/ pages to DocumentationWriter (docs/index.md, zensical.toml, docs/markdown.md); section indexes written by ProductOwner, SpecWriter, Triage per their scopes; .gitignore, README.md, package.json (S5) not covered by any agent scope (Triage)
  • 2026-11-02 S1 reviewed, approved (Triage)
  • 2026-11-02 S2 reviewed, approved (Triage)
  • 2026-11-02 S3 blocked for agents: no agent can delete files; user must run git rm docs/markdown.md (nothing links to it, verified) (Triage)
  • 2026-11-02 S5 files (.gitignore, README.md, package.json) are outside every agent scope; needs user decision (Triage)
  • 2026-11-02 S3 done by user (git rm docs/markdown.md), reviewed, approved (Triage)
  • 2026-11-02 S5 done by user (.gitignore site/, .venv/, plus .cache/ beyond the step text; README Docs line; root package.json docs and docs:build scripts), reviewed, approved (Triage)
  • 2026-11-02 S4 uv run zensical build (user ran it): passes ('Build finished'), 0 errors, 69 warnings, none caused by this item; all W-NNN pages are built although not in the nav (site/work/W-*/ exist), so open question 3 stays accepted; no nav or TOML problems (Triage)
  • 2026-11-02 S4 broken in-docs links: 14 anchor warnings, all ../concept.md#8-demo--feature-mapping (concept heading slugs to #8-demo-feature-mapping, single hyphen); in products/demo-anno, demo-ck3, demo-dnd, demo-totalwar; specs/demo-anno, demo-ck3, demo-dnd; work/W-013, W-016, W-017, W-018, W-070, W-072, W-075. Pre-existing content, not caused by this item, not rewritten; follow-up candidate (Triage)
  • 2026-11-02 S4 links leaving docs/ (55 page-does-not-exist warnings): ../../.github/skills/* 24, ../../reference/flecs|bitecs/docs/* 27, ../../AGENTS.md 3 (W-104, W-105, W-106), ../../README.md 1 (W-018). Links to non-.md files (turbo.json, pnpm-workspace.yaml, pyproject.toml, zensical.toml) are not warned. Not rewritten; follow-up candidate once repo_url is known (Q6) (Triage)
  • 2026-11-02 user decision 1 (Triage): Board nested under Work in the nav (Work > index, Board, Archive), not a separate top-level entry; Goal, S2, S6, nav approach and Q4 amended; top-level order Home, Concept, Products, Specs, Work
  • 2026-11-02 user decision 2 (Triage): Specs nav has sub-groups Demos (demo-anno, demo-ck3, demo-dnd) and Packages (ecs-devtools, ecs-prefab, ecs-relations, ecs-schedule, ecs-serialize); S2 and S6 amended
  • 2026-11-02 user decision 3 (Triage): S6 board link wording now "the board links to the W-NNN pages (the work index links to the board and archive, per S1)"
  • 2026-11-02 correction (Triage): the earlier Log claim about nav (S2 reviewed, approved) is superseded: the nav was changed by the user after S2 review, and the decisions above supersede it
  • 2026-11-02 user decision 4 (Triage): top-level nav label Products renamed to Demos (folder docs/products/ unchanged); Goal, S2, S6 amended
  • 2026-11-02 S6 accepted: board.md change is only the W-106 state transition and table reformat (user accepted) (Triage)
  • 2026-11-02 final review approved after plan amendments (Triage)
  • 2026-11-02 state active -> review -> done, moved Now -> Done (Triage)