README.md

Documentation

This directory owns code-chan's detailed product and implementation documents. The root AGENTS.md contains durable working policy; it must not become a copy of the specifications stored here.

Current document authority

Document	Responsibility
../AGENTS.md	Repository-wide agent policy and stable product boundaries
../README.md	Concise public project introduction
../media/README.md	Published presentation media: what may be tracked, naming, and size
README.md	Detailed-document ownership and organization policy
PRODUCT.md	Detailed product scope, user experience, supported behavior, and explicit non-goals
GLOSSARY.md	Plain meaning of every term used narrowly, and the code or wire name it matches
ARCHITECTURE.md	Current runtime components, ownership, dependency direction, processes, and data flow
HOST_BRIDGE.md	Current host package, agent adapters, foreground ownership, permission path, and transports
FIRMWARE.md	Current hardware target, firmware behavior, power boundary, and build procedure
PROTOCOL.md	Current device message semantics, framing, sequencing, and errors
SECURITY.md	Current trust boundaries, the bounded shapes crossing them, supply chain, and reporting path
VERIFICATION.md	Current test layers, review evidence, and physical acceptance boundary

Detailed document ownership

Create a detailed document only when its subject has accepted requirements or implemented behavior to record. Do not create empty placeholders.

Use these filenames when the corresponding content becomes necessary:

Document	Sole responsibility
PRODUCT.md	Detailed product scope, user experience, supported behavior, and explicit non-goals
ARCHITECTURE.md	Runtime components, ownership, dependency direction, processes, and data flow
HOST_BRIDGE.md	npm package, CLI, MCP tools, lifecycle hooks, coding-agent adapters, configuration, and device connection behavior
FIRMWARE.md	Hardware targets, display, servo, sound, touch, power, build, flash, and hardware verification requirements
PROTOCOL.md	Device message semantics, schemas, framing, errors, and sequencing
SECURITY.md	Trust boundaries, data admitted across each boundary, threat model, supply chain, and vulnerability reporting
VERIFICATION.md	Supported test layers, build checks, hardware checks, evidence requirements, and release gates

If a new subject does not fit one of these owners, establish the smallest clear owner rather than placing the same rule in several documents.

Content rules

• Each contract, schema, identifier, limit, command, and current-state claim has one authoritative owner.
• ../README.md and PRODUCT.md are written for a reader who has never seen this repository, and use ordinary words in place of the narrow vocabulary. The implementation documents keep the narrow terms because those are also the code and wire names, and point at GLOSSARY.md rather than defining them again.
• Reference the owner instead of copying detailed rules into another document.
• Distinguish Current implementation from Required behavior when both are needed. Never present a requirement as already implemented.
• Add build, test, setup, and flash commands only after their tracked scripts or package entries exist and have been verified.
• Record hardware mappings and limits only from the actual target design or direct hardware evidence.
• Keep public documents free of credentials, private captures, local absolute paths, and user-specific configuration.
• Replace stale current-state information instead of maintaining chronological implementation diaries.
• Keep task plans and current working notes under .WORK/note/, collected evidence under .WORK/research/, and external reference repositories under .WORK/sources/, not in durable specifications.

Change policy

When implementation changes a documented contract, update the owning document in the same change. When two documents conflict, stop at the affected boundary, identify the true owner, and remove the duplicate or stale statement instead of inventing an undocumented precedence rule.