docs: a bilingual usage guide, published as a documentation site - #1
Merged
Conversation
The repository's documentation was readable only as loose files on GitHub: a 21 KB README, a glossary, eleven architecture documents and fifteen evidence notes, tied together by links and with no way in. This builds docs/ as a site instead. MkDocs Material rather than the Pages Jekyll build, because the content needs two things that environment does not have: mermaid through superfences, since the architecture documents are mostly diagrams, and mkdocs-static-i18n for the bilingual guide that follows. Existing documents are published exactly as they stand. The workflow enables Pages itself on its first successful run, and `mkdocs build --strict` is the check: a broken internal link or a nav entry naming a file that does not exist fails the build rather than shipping a 404. Dependencies are pinned; development has stopped and a floating version would break this build long after anyone is watching.
The README is a good reference and a poor guide. It answers "what is this" and "what are the flags", and never answers "how do I run my first lane", "why is this lane still pending", or "how do I write a brief that gets scored correctly". Development has stopped, so the reader this has to serve is one person setting a working design up to take it apart, not a team. Thirteen pages, in the order that reader meets them: install, configure an agent, drive one lane end to end, write briefs, prepare the driven repository, operate it daily, use plans and revisions, install it as a service, wire the Claude Code bridge, the API, troubleshooting, and what it does not protect you from. Everything is read off the source rather than off the README, which turned up one thing the README gets wrong by example: `owned_paths` is an anchored glob over file paths in which `*` does not cross a `/`, so `src/auth` does not cover `src/auth/login.ts`. Measured on a scratch repository, both the failure and the pattern list that passes are in the guide.
AGENTS.md says the artifacts are English and the conversation is Turkish. The guide is the one artifact where that split costs something: it is the document a person reads while their hands are on the keyboard, and the person driving this repository reads Turkish. So the guide ships in both. English stays canonical: it is the default locale, and mkdocs-static-i18n falls back to it for every page without a `.tr.md` sibling, which is the glossary, the architecture series and the evidence notes. Those are unchanged and stay English. Program output is not translated. Error strings, refusal texts, gate reasons, route paths, field names and the example briefs are quoted verbatim in both locales, because a reader searching for what their terminal said has to find it. Domain vocabulary stays English inside Turkish sentences (lane, hub, conductor, worktree, brief, gate), matching how the glossary defines it.
The site shipped on Material's stock indigo preset, one flat sidebar and a table for the entry points. It read like a default. What changed, and why each one: - Top-level sections become tabs, so the guide, the reference, the architecture and the notes are four destinations rather than one long scroll of a sidebar. The home page hides the sidebar entirely; it has no section of its own and the empty rail was noise. - A palette defined in one file rather than picked from the presets: near-black chrome, an indigo accent, and a slate dark scheme built on #0d1117 so the two schemes are one decision. - Inter and JetBrains Mono, looser line height, tighter heading tracking, and rules on the section headings. Rounded, bordered code blocks, admonitions and tables, and identifiers that no longer wrap mid-token in the configuration table. - The home page opens with a hero and ends in a card grid instead of a two-column table, in both languages. `navigation.instant` is deliberately not enabled: mkdocs-static-i18n cannot build a contextual language-switcher link with it on, and in a bilingual site losing "same page, other language" costs more than instant loading buys. The comment in mkdocs.yml says so, so nobody adds it back. One real bug fixed along the way: Material's `custom` palette redefines --md-typeset-a-color on <body>, which beat the :root declaration, so every link inside the content rendered near-black. Verified by computed style rather than by eye: links now resolve to the accent in both schemes.
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
2 participants
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.
The README is a good reference and a poor guide. It answers "what is this" and "what are the flags", and never answers "how do I run my first lane", "why is this lane still pending", or "how do I write a brief that gets scored correctly". Development has stopped, so the reader this has to serve is one person setting a working design up to take it apart, not a team.
What this adds
A task-first guide, 13 pages, in the order that reader meets them: install, configure an agent, drive one lane end to end, write briefs, prepare the driven repository, operate it daily, use plans and revisions, install it as a service, wire the Claude Code bridge, the API, troubleshooting, and what it does not protect you from.
The whole of
docs/published as a site at https://aethrox.github.io/laneward/. MkDocs Material rather than the Pages Jekyll build, because the content needs two things that environment does not have: mermaid through superfences, since the architecture documents are mostly diagrams, andmkdocs-static-i18nfor the bilingual guide. Existing documents are published exactly as they stand; none of their content changed.The guide in Turkish as well as English. English stays canonical: it is the default locale, and any page without a
.tr.mdsibling falls back to it, which is the glossary, the architecture series and the evidence notes. Program output is not translated: error strings, refusal texts, gate reasons, route paths and the example briefs are verbatim in both locales, because a reader searching for what their terminal said has to find it.One thing the README gets wrong
Everything in the guide was read off the source rather than off the README, which turned up a real defect in the quick start.
owned_pathsis an anchored glob over file paths in which*does not cross a/, sosrc/authmatches the filesrc/authand nothing under it. The README's own example (bun scripts/new-lane.ts fix-login brief.md src/auth) therefore fails any lane that editssrc/auth/login.ts, with an ownership violation, even when the work is correct.Measured on a scratch repository with two changed files:
owned_pathssrc/authFAIL: ownership violation: src/auth/deep/util.ts src/auth/login.tssrc/auth/*FAIL: ownership violation: src/auth/deep/util.tssrc/auth/*src/auth/*/*PASS: 2 changed path(s), all within owned_pathsThe guide documents this, with the table. The README example is left alone in this PR.
Verification
mkdocs build --strictpasses with zero warnings; a broken internal link or a nav entry naming a missing file fails the build.custompalette redefines--md-typeset-a-coloron<body>, which beat the:rootdeclaration and rendered every content link near-black.src/andscripts/, not against the README.Notes
configure-pageswithenablement: true. If the repository's Actions permissions refuse that, the one-time manual step is Settings, then Pages, then Source: GitHub Actions.unpkg.comat view time, which is Material's own behaviour. This repository vendorspico.classless.min.cssprecisely to avoid that kind of dependency, so vendoring mermaid too is worth considering; not done here.navigation.instantis deliberately not enabled:mkdocs-static-i18ncannot build a contextual language-switcher link with it on.🤖 Generated with Claude Code
https://claude.ai/code/session_012iekFATyXcd1UYAXVjPwPk
Generated by Claude Code