# Documentation ownership and maintenance

`docs/current` is the maintained handbook for the current website. Root `README.md` introduces the
project; `CONTRIBUTING.md` and `AGENTS.md` provide the working entry points. Tool-local READMEs describe
their tool and link here for application context. Do not create another dated “current architecture”
index each time a feature changes.

## One handbook, two website audiences

The handbook catalog selects chapters and their public or staff audience. The application packages
those exact Markdown files and serves them through Engineering and Admin handbook routes. Production
must not depend on a developer checkout or a Desktop directory. Public chapter navigation excludes
staff material. The Admin handbook adds setup, operator and implementation procedures.

CMS Engineering notes remain editable articles with the existing review/publish lifecycle. They are
not silently overwritten from repository docs at startup. Link the current handbook from that area
and the Admin Console, and keep the Engineering Observatory project inventory synchronized with the
Full solution. Akari's architecture description uses that corrected inventory. Handbook chapters are
also projected into the public Engineering or staff Architecture Review lane according to their
audience. A content fingerprint detects changed packaged text or project inventory and refreshes the
projection through its existing owner; no model invocation is needed to index the guides.

### Ask Akari: Engineering topics

The member Engineering conversation requires a selected public Engineering article or handbook
chapter. Its selector uses the existing published CMS index and packaged public handbook catalog;
do not duplicate this material in Site Guide. Article and handbook links carry the canonical page
path, which preselects the matching reference. A general `/Engineering` arrival has no selected topic.
The focused [Pinokio and ChatterBox guide](pinokio-and-chatterbox.md) keeps provider setup and GPU
evidence together within one selected reference, separate from the longer conversation-contract
chapter. Its public catalog entry also makes it available to the Engineering knowledge projection.
The left-edge **Topics** tab opens a sliding overlay drawer; closing it or pressing Escape restores
the chat space without clearing the reference. Topic controls do not occupy the chat composer.
Changing the topic starts a fresh conversation and preserves the member's draft question.

Each Engineering request resolves that path again through the public page-context owner before
creating a conversation or invoking inference. Missing, withdrawn, draft and staff-only references
are rejected, including direct requests that bypass the selector. The canonical path participates in
the existing operation fingerprint and retry payload. The selected publication is primary evidence,
with up to 12,000 characters of its text and explicit partial-coverage marking when shortened; normal
public Engineering retrieval supplies supporting references. The response must acknowledge missing
evidence and ask for clarification or a different topic when appropriate. Topic selection itself
does not call AI or spend credits. Site Guide remains a separate Guide-mode workflow.

The Developer Learning Lab's four standalone lessons have a separate Tutor entry point:
`/Engineering/Interview?lesson={key}`. Each link selects that lesson and uses a separate resumable
conversation, preserving unrelated interview sessions. **Learning Topics** is a button next to Menu;
its dialog overlays the scene without taking chat space. It offers the published lessons
alongside maintained learning topics. General conversation remains available and has no selected
lesson reference. Interview activity and its hidden scenario rules remain independent of topic selection.

`PublishedDeveloperLessons` in Application owns the public concepts, code, exercises and reflection
questions used by the page, knowledge index and Tutor. Tutor resolves the selected lesson directly
for each request and returns its canonical lesson link; it does not depend on index freshness or a
duplicate Site Guide entry. The client captures a content revision before sending. Unknown lessons,
wrong surfaces and stale revisions fail before inference; a changed lesson requires a new request.
If live tutoring fails, the reviewed fallback stays on the selected lesson and labels itself as
reference material. A supplied reference improves relevance, but does not guarantee every model claim.

The October 29 Engineering refresh's reviewed CMS payload is
`Content/Engineering/beta-refresh-2026-10.json`. It is an explicit editorial publication input, not
startup seed data. Updates preserve existing dossier identities and use the normal change, submission,
approval and release owner in one transaction. The task's read-only plan binds the payload and current
records before applying it; an intervening edit requires a fresh review. Later CMS edits remain authoritative.
Versioned Gynara artwork provenance is in `Content/PublicAssets/engineering-gynara-v1.json` and
`engineering-gynara-v2.json`; canonical bytes follow the public-media manifest rather than entering Git.

## What was archived

Superseded engineering guides, plans, runbooks, audits and acceptance reports move to the resolved
Windows Desktop's `DrakimaLegacyDocumentation` folder, preserving their repository-relative paths.
The archive manifest records source paths, SHA-256 hashes, byte lengths and current replacement guides.
Original bytes are moved, not copied into additional backup sets. Prior versions remain in Git history.

Story manuscripts, character prompts, artwork production/review records, JSON catalogs, source masters,
test fixtures and private runtime records are not obsolete engineering documentation merely because
they are under `docs`. Their historical source references are provenance, rather than current operating
instructions. The owner-authorized lean-workspace archive moves production artwork binaries and generated
creative exports to `Desktop/DC_Archive_Data_v01`, preserving repository-relative paths beneath `repository`.
`docs/operations/workspace-artwork-archive.json` records byte lengths and SHA-256 hashes. Current runtime
assets, machine-readable production contracts, prompts, receipts and image-processing regression fixtures
remain with their owners. Restore a source master from the receipt before rerunning its production recipe;
ordinary builds and published packages do not require the artwork archive. Immutable releases are unchanged.

## Updating the handbook

1. Verify the relevant implementation, configuration and tests. A historic plan is evidence of intent,
   not proof of current behavior.
2. Edit the affected chapter and its source evidence. Add a chapter only when an existing owner cannot
   cover the topic clearly. Maintain public/staff audience deliberately.
3. Repair current local links and catalog artifact locators. Keep the project inventory in sync with
   `DrakimaCore.Full.slnx` and verify packaged resources.
4. Run the documentation contracts plus normal checks for changed code. Preview the affected pages on
   desktop/mobile and through the appropriate authenticated or anonymous route.
5. Commit guides with the implementation. Record live verification separately from implementation claims.

Avoid credentials, private transcripts, machine-specific live status, fixed historical test totals and
unreviewed release promises. A documentation archive does not replace a coordinated recovery plan.

## Gynara knowledge hub

Six public Gynara explanations and six staff manuals are registered in `catalog.json`. The public entry point is [the game platform](gynara-game-platform.md). The sibling Maker handbook owns its source-facing manuals and built-in Help. `Content/Engineering/gynara-beta-knowledge.json` is the reviewed editorial payload; `Content/PublicAssets/engineering-gynara-v3.json` records character references, prompts and asset hashes.

Maintain the packaged chapters and editorial payload together, then explicitly publish CMS revisions through normal review. Startup must not overwrite editorial records. Public links remain inside the public catalog; private diagnostics, release operations and source handoff stay staff-only.