docs(witan): add Concepts and Walkthroughs sections to the docs site - #289
Open
blarghmatey wants to merge 3 commits into
Open
docs(witan): add Concepts and Walkthroughs sections to the docs site#289blarghmatey wants to merge 3 commits into
blarghmatey wants to merge 3 commits into
Conversation
Guides and Explanation assume readers already have a mental model of memory kinds, the task/project graph, and the CLI/agent/skills split. Concepts gives that model directly; Walkthroughs works one scenario through all three interfaces so the difference between them is concrete rather than asserted. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012wCHjz7AaaqLeQirfPYaXD
Contributor
There was a problem hiding this comment.
Pull request overview
Adds Concepts and Walkthroughs sections to explain witan’s mental model and demonstrate its CLI, agent, and skill interfaces.
Changes:
- Documents memory, graph, and interface concepts.
- Adds three parallel workflow walkthroughs.
- Updates navigation and cross-links.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
zensical.toml |
Registers the new navigation sections. |
docs/concepts/index.md |
Introduces the Concepts section. |
docs/concepts/memory.md |
Explains memory kinds and relationships. |
docs/concepts/graph.md |
Describes task and project graphs. |
docs/concepts/interfaces.md |
Compares CLI, agent, and skill interfaces. |
docs/walkthroughs/index.md |
Introduces and compares walkthroughs. |
docs/walkthroughs/cli-driven.md |
Demonstrates the CLI workflow. |
docs/walkthroughs/agent-driven.md |
Demonstrates direct MCP tool usage. |
docs/walkthroughs/skills-driven.md |
Demonstrates skill-guided task handling. |
docs/index.md |
Links the new sections from the homepage. |
docs/getting-started/tasks-and-projects.md |
Cross-links the new material. |
docs/explanation/index.md |
Directs conceptual readers appropriately. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Agents consuming the docs site shouldn't have to parse rendered HTML. bin/gen_llms.py derives llms.txt (llmstxt.org), llms-full.txt, and a per-page markdown mirror from docs/ and zensical.toml's nav after the HTML build, so there's no second copy of the site structure to hand- maintain. Runs as plain python3, not uv run, so it doesn't drag the uv workspace into the RTD build the way the rest of bin/ deliberately does not. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012wCHjz7AaaqLeQirfPYaXD
- task_create() examples (agent-driven, skills-driven, concepts/graph) omitted the required `description` argument. - concepts/graph.md's DiscoveredFrom diagram had the edge reversed: task_link/task_create write it new-task -> source-task, not the other way round. - concepts/memory.md: `memory_for_contract` needs `kind` to run the code-graph lookup at all; `kind` doesn't gate what `recall` returns by default (it searches every kind unless the caller filters); `agent_context` has no automatic scope or expiry, contra the prior wording; `related_to` was missing from the edge table. - walkthroughs/agent-driven.md overstated what `recall` expands across (applies_to/related_to + siblings, not "any linked memory"). - walkthroughs/cli-driven.md showed a claim output format and a --ready listing that don't match witan/cli/tasks.py. - walkthroughs/skills-driven.md closed the task without storing the lesson the overview page claims all three walkthroughs preserve; added the memory_store step and corrected the comparison table. - concepts/interfaces.md: missing connector made a sentence unparseable. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012wCHjz7AaaqLeQirfPYaXD
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 are the relevant tickets?
N/A
Description (What does it do?)
Adds two new top-level nav sections to the witan-context docs site, between "Get started" and "Guides":
docs/concepts/) — the mental model the Guides/Reference/Explanation pages assume:memory.md(what a memory is, the four kinds, the edge types),graph.md(the task/project graph — hierarchy, dependency, and provenance edges, with a worked multi-step example),interfaces.md(CLI vs. direct agent tool calls vs. packaged skills, and when to reach for each).docs/walkthroughs/) — one running scenario (the retry-bug task already used in the "Tasks and projects" tutorial) worked through three times, once per interface:cli-driven.md,agent-driven.md,skills-driven.md, plus an index comparing what actually differs between them.Also wires both sections into
zensical.tomlnav and cross-links them fromdocs/index.md,docs/explanation/index.md, and the existing tip box indocs/getting-started/tasks-and-projects.md. No generated or mirrored pages touched.How can this be tested?
uvx zensical@0.0.56 build— reports "No issues found" (this is what CI's link/anchor checker in.github/workflows/docs.ymlruns)../bin/gen_docs.py --check— confirms nothing generated/mirrored drifted.docs/concepts/anddocs/walkthroughs/for tone/accuracy against the existing Explanation and Guides pages, and check the new nav entries render in the right order (zensical servelocally, or the RTD preview once CI runs on this PR).