Repository navigation
docs: publish the user documentation as a Zensical site - #41
Merged
Merged
Conversation
The README had grown to 822 lines of guides. They move to a documentation site built with Zensical, laid out like Tiroir's: Get Started, How It Works, Guides and the changelog. The README keeps a quickstart and the contributor sections. The site has a pixel-art workbench for a logo, the Daubenton headings it shares with Tiroir, and workwear blue where Tiroir has brown. The decision records and the harness validation stay out of it as maintainer records, so the changelog links them on GitHub. mise run docs:build builds it in strict mode, and the docs workflow builds it on every pull request and publishes it to GitHub Pages from develop. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The install command names the v0.1.0 tag and no agent. The skills CLI puts the skills in .agents/skills/ with links in .claude/skills/ on its own, so the -a flags were a workaround for a problem that only -a claude-code alone caused. The page now warns against that one flag instead of asking readers to pick a harness. The review lenses were presented as an install step. They only shape the suggestions where.sh makes for the human review of a pull request, while the automatic review is etabli-refine, which needs no setup. They get their own guide, Review the Pull Requests, and the install page keeps one sentence. The previous and next buttons come from Zensical's navigation.footer feature, so the hand-written Next links go. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The Drive the Route page showed the launcher and the follow loop as if a person typed them. An info note now says the orchestrator runs them in the background and that nobody has to, and the install page no longer cites the skills CLI's version. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Watch and Resume Lanes read as a routine. The orchestrator watches the lanes through the follow loop and reports what needs a person, so an info note now says the page explains how a lane works and what to reach for when one misbehaves. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Milestones move to the top of The Route, with a tip recommending them: without them the route is one pass and not incremental. A milestone is described as a working slice, an MVP in the agile sense, and how one runs is listed step by step. The two Mermaid diagrams on that page become HTML and CSS, so they follow the theme and fit without scrolling. One shows the route in six steps, once for the project and once per milestone, with the human gates and the loop back to the next cut. The other shows how a project holds milestones, epics and tasks, and that only the current milestone is cut. The units table becomes a table of the artifacts: where each lives, who writes it, and what it is for, decision records and contracts included. The PRD gets a page of its own: what it is, its sections, what an outcome looks like, how it is written and what to check before approving it. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…d step cards Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…adges, mirrored saw Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…xels Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…the note Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ancelin-code
force-pushed
the
docs/zensical-site
branch
from
November 6, 2026 09:31
70c41ad to
37c15f7
Compare
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What and why
The README had grown to 822 lines of guides. They move to a documentation
site built with Zensical, laid out like
Tiroir's: Get Started, How It Works,
Guides and the changelog. The README keeps a quickstart and the contributor
sections (120 lines).
How to review
mise run docs:serve, then open thehome page. The look is the part a diff cannot show.
drawer knob, nodding to Tiroir (
docs/assets/logo.svg).bench stays in the logo and in the human gates of the diagrams.
docs/start,docs/concepts,docs/guides) are the README'sguides moved and split, with some text tightened. Skim them: no rule changes.
uv.lock(addszensical==0.0.73in adocsgroup),.gitignore(
/site/), and four changelog links to the ADRs, made absolute because thesite leaves the ADRs out and the strict build refuses a dead link.
docs/decisions/anddocs/harness-validation.mdstaymaintainer records, outside the site.
How to try it
mise run docs:build # strict: fails on any warning mise run docs:serveThe build reports no issues. Lint and the 360 tests pass locally.
Before it goes live
.github/workflows/docs.yamlpublishes to GitHub Pages fromdevelop, so therepository needs Settings → Pages → Source: GitHub Actions once. Until then
the deploy job fails; the build job still checks the site on every pull
request.
Does it earn its place?
It adds no rule to the kit. The docs live outside the skills, so no agent pays
tokens for them.
AGENTS.mdgains two lines: whatdocs/holds now, and thata change to how the kit is installed or run updates its page.