Problem
The docs have accumulated overlapping user, operator, and contributor guidance. The current top-level categories do not make the intended reader clear enough, and some sections now mix product usage, architecture explanation, local development, implementation details, and maintainer workflow in the same path.
This is especially visible around Agent Daemon, Agent Runtime, and Tasks: the same concepts and workflows are repeated across multiple pages/READMEs with slightly different framing, which makes it hard to know what is canonical and what is stale.
Goal
Reorganize the docs around clearly identified readers and canonical content ownership, without treating Understand as contributor-only. Understand is also user-facing; the IA needs to distinguish audience and intent more deliberately than the current sidebar labels do.
Scope
- Identify the primary reader types we support: product users, operators, integrators, and repository contributors.
- Define which docs categories serve which jobs, and where mixed-audience pages need explicit transitions or splits.
- Audit
docs/start, docs/use, docs/understand, docs/reference, and project READMEs for duplicated explanations.
- Remove redundancy across Agent Daemon, Agent Runtime, and Tasks sections.
- Pick one canonical home for repeated concepts and replace duplicates with short links.
- Keep user-facing pages focused on what people can do with MoltNet now.
- Move release engineering, CI, local development, publishing, and maintainer workflow details into clearly contributor/operator-oriented homes.
Acceptance criteria
- Every major docs page has an obvious intended reader and job-to-be-done.
- Agent Daemon, Agent Runtime, and Tasks have one canonical explanation each, with links instead of repeated prose.
Understand remains available for user-facing conceptual explanation and is not treated as a dumping ground for contributor internals.
- Contributor/operator content is isolated or clearly labeled when linked from user flows.
- Sidebar categories and page titles make the reader journey easier to follow.
Problem
The docs have accumulated overlapping user, operator, and contributor guidance. The current top-level categories do not make the intended reader clear enough, and some sections now mix product usage, architecture explanation, local development, implementation details, and maintainer workflow in the same path.
This is especially visible around Agent Daemon, Agent Runtime, and Tasks: the same concepts and workflows are repeated across multiple pages/READMEs with slightly different framing, which makes it hard to know what is canonical and what is stale.
Goal
Reorganize the docs around clearly identified readers and canonical content ownership, without treating
Understandas contributor-only.Understandis also user-facing; the IA needs to distinguish audience and intent more deliberately than the current sidebar labels do.Scope
docs/start,docs/use,docs/understand,docs/reference, and project READMEs for duplicated explanations.Acceptance criteria
Understandremains available for user-facing conceptual explanation and is not treated as a dumping ground for contributor internals.