Dotabase Operating Manuals

Description

Dotabase Operating Manuals combine derived schema facts with human-authored operating judgment and track whether that judgment still matches the live schema.

The manual service stores purpose, operating guidance, and curator-owned decisions beside a digest of the schema they describe. Derived helpers render mechanical facts such as properties and views from the current definition rather than asking a person to maintain them twice. A staleness behavior compares schema evidence after relevant changes and marks guidance for review without rewriting it.

User Story

As a database owner, I document how a Dotabase should be used and know when a schema change makes that guidance outdated. I write the intent, ownership, and working rules that only a curator can supply. The service attaches current derived facts and a schema digest. When the schema changes materially, I receive a stale signal and can review a redraft proposal. I walk away with documentation that says both how the database is built and how the team should operate it.

Extension Surface

Configurable: curators own judgment sections and can request governed redraft proposals.

packages/dotabases/src/services/manual-service.ts provides the read, update, and proposal workflow. packages/dotabases/src/manual/derived.ts fixes how mechanical evidence is generated, while owners remain free to author the manual's judgment within the supported record.

Capabilities & Limits

• Capability: Executes the scoped workflow described above through the cited live implementation paths.
• Capability: Preserves typed validation and applicable tenant, schema, lifecycle, or service boundaries.
• Limit: Automatic redrafting is a proposal and needs an LLM seam; the system does not silently replace operator-authored judgment. The feature can derive schema facts, retain curator content, calculate a schema digest, mark a manual stale, and stage an assisted redraft. It cannot know unwritten organizational intent or certify that guidance is correct. Provider absence blocks only the optional proposal; manual storage and deterministic staleness remain usable.

Implementation Map

• packages/dotabases/src/services/manual-service.ts
• packages/dotabases/src/manual/derived.ts
• packages/dotabases/src/behaviors/dbom-staleness/index.ts

Related Features

Documents Dotabase Workspaces and is maintained by the Behavior Automation Engine.

Operationally, these relationships preserve a clear ownership boundary around Dotabase Operating Manuals. Neighboring features can invoke, supply, or consume its results, but `packages/dotabases/src/services/manual-service.ts` remains the grounded implementation authority for this capability. That distinction prevents the catalog claim from widening into adjacent rendering, transport, or governance work. Teams can therefore combine the feature with the named dependencies while still diagnosing configuration, validation, and lifecycle behavior at the package boundary that owns it.