The Documentation Pile Is Becoming a System
Documentation becomes dangerous when it is almost right.
A stale document can look authoritative. A useful decision can disappear inside a chat. Shared guidance gets copied into five product folders, changes in one, and quietly becomes six different answers. Search returns something related, but not necessarily the thing that owns the truth.
The latest M7 documentation pass is aimed squarely at that problem.
This was not a README touch-up. The tracked cleanup alone spans 61 existing files, with roughly 5,000 additions and 1,300 removals. The broader work adds hundreds of documents, research records, product packages, schemas, reusable components, and operational tools.
The important change is not the file count. The documentation is starting to behave like a system.
One fact should have one home
The repository now makes a hard distinction between durable knowledge and generated retrieval data.
Markdown remains the source of truth. Product requirements stay with their product. Shared frontend and API-backend guidance moves into common tracks. Reusable patterns get their own contracts. Research remains visibly classified as research until it is mature enough to promote.
The local search database is disposable. It can be deleted and rebuilt from the maintained documents. That boundary matters: the index helps find knowledge, but it does not become the knowledge.
The storage process is now explicit:
- Put the durable document in its canonical home.
- Register a stable route when exact addressing matters.
- Rebuild the local index.
- Prove that the material can be found and read.
- Keep ordinary source control as the review boundary.
That is a much safer model than treating chat history, scratch files, or an opaque vector database as institutional memory.
Routes replaced document archaeology
The documentation control plane now has distinct ways to ask for things.
Semantic lookup is for finding the best relevant material. Canonical document routes are for exact M7-owned documents. Source routes identify externally owned repositories and references. Commands describe repeatable operational workflows.
The distinction sounds small, but it eliminates a lot of ambiguity.
An operator can search for guidance when the destination is unknown, or request an exact route when it is known. An agent does not have to guess whether a phrase means “find me information” or “execute this workflow.” Remote projects can use thin entry points while the full contract remains maintained in one place.
The current registry validates 322 documentation routes and nine command contracts. Those routes are not a bag of bookmarks. Each one carries identity, ownership, status, aliases, tags, and a maintained target.
Search now has a reproducible spine
The local retrieval layer currently sees 627 corpus files, including 577 Markdown files. It expands those sources into 976 logical documents and 4,680 searchable chunks.
Those numbers are useful, but reproducibility is the real feature.
The index can be rebuilt deliberately. Search results retain their canonical route and source location. Local tools can search, read, and assemble context without turning the generated database into an authority of its own.
The same retrieval surface is available through a local MCP adapter, alongside discovery and validation for reusable component patterns. That gives agents and tools one bounded interface instead of a collection of private scraping habits.
Shared rules moved up; product differences stayed down
A large part of the cleanup was removing knowledge from the wrong level.
API-backend installation, startup, SQL setup, authorization, token identity, route behavior, CORS, and repository structure have been tightened as shared guidance. Frontend installation, session recovery, bearer-header behavior, themes, and component conventions received the same treatment.
Product packages can now stay focused on the part that is actually unique.
The active product structure is deliberately narrow: product contract, specification, track, concrete surface, cover document, and local implementation steps. When several products need the same rule, that rule moves outward into the shared corpus instead of being copied again.
The document service received a particularly broad refit. Its work is now separated into preparation, configuration, SQL, service, API, and general implementation layers. Blog, news, post, public-site, identity, and other product work now have clearer places to live without collapsing every concern into one enormous implementation note.
Public API documentation has a publication discipline
Public API documentation now has an authoring guide and a defined refresh process.
The maintained service repository owns its public_docs source. A publication workflow researches the implementation, separates public integration contracts from administration and internal behavior, reviews authentication and authorization claims, refreshes the service landing page, and mirrors the result into the public documentation repository.
That last part is important. The public copy is a publication target, not a second place to make private fixes.
Authorization documentation also follows evidence. A header being accepted by CORS does not make it part of the supported authentication contract. A platform capability does not become a service promise until the service enforces it end to end.
Documentation should describe what the system actually supports, not what a nearby library could theoretically do.
Research stopped pretending to be a contract
The research collection now has a clearer boundary.
Identity architecture, Active Tags adoption, content strategy, market intelligence, positioning work, and sanitized OAuth interface studies can be retained without quietly becoming production doctrine.
Research is allowed to compare, question, and explore. Active tracks and product specifications are expected to direct implementation.
Promotion between those states is deliberate. Stable findings move into shared guidance or product contracts. Historical material remains behind only when it still helps explain how a decision was reached.
That gives uncertain work somewhere honest to live.
Reusable patterns became packages
The component work received the same cleanup.
A reusable pattern is no longer just a screenshot, a loose PHP fragment, or a folder somebody remembers. Patterns now have profiles, root packages, selectable components, machine-readable manifests, schemas, and explicit build requests.
The builder separates discovery, planning, validation, and writing. Component implementation files remain inert during planning. A profile-owned installer controls how a validated package is assembled. Runtime content has declared installation strategies instead of being smuggled through arbitrary parameters.
That work is already supporting reusable product-site sections and multiple page variants while keeping the package contract independent of PHP, JavaScript, or any one rendering system.
Validation is part of the documentation
The cleanup is not complete because there are many files. It is useful because the system can check itself.
Command routing validates. Document routing validates. Retrieval rebuilds and finds newly registered material. Pattern packages have schemas and tests. Public API documentation has source, mirror, and classification rules. Durable knowledge has a placement and indexing procedure.
There is still plenty to refine. Some material will be promoted, some will be consolidated, and some experiments will be discarded.
But the repository now has a stronger answer to the question that matters: when someone finds a document, how do they know what it is, who owns it, whether it is active, and what should happen next?
That is the difference between a pile of Markdown and a working knowledge system.