Repository documentation
my-pi supplies locally loaded Pi configuration, extension packages, skills, the evaluator, and in apps/ the Pi frontends, Pi core, and clink. Start with the document that answers the current question.
| Question | Read |
|---|---|
| What does a session on this machine do, by capability, and which document owns each behavior? | Behavior map |
| What owns the runtime behavior, and what crosses a package or process boundary? | Architecture |
| How does a frontend drive Pi, and where does its code live? | Frontends |
| What is clink, and where do its instances live? | Clink |
| What does a local term mean, and which words should I avoid for it? | Glossary |
| How do sessions, inputs, runs, user turns, and async tasks relate, and where does each come from in Pi? | Object model |
| Why was a hard-to-reverse design decision made? | Decision records |
| How can I validate this change without modifying the live runtime? | Verification |
| How do I add, load, or version an extension? | Extension authoring and inventory |
| How does configuration reach a session? | Pi configuration |
| Which requirement source does a review compare against? | Requirements and work tracking |
| How are instructions evaluated? | Evaluator |
| Why did we adopt or reject an external convention? | References |
| Which harness features or design decisions are worth considering? | Benchmark review |
| What upstream behavior have we already mapped, and at which review scope? | Reference-map index |
Authority
Section titled “Authority”The root AGENTS.md owns repository working instructions. A package README that declares itself the behavioral owner owns that package’s supported outcomes, together with any docs/ pages it names as part of that owner. Otherwise, use its local decision code and tests; not every invariant needs a contract document.
The glossary owns local naming, not behavior or wire formats. The object model relates those names and maps them to Pi’s. The behavior map routes capabilities to owners without adding promises. Decision records explain why a choice was made; they do not own current behavior. Types and schemas own exact executable shapes. Tests and host probes are evidence; verification recipes are procedures. Upstream APIs are compatibility dependencies, not owners of our product choices. Historical plans explain decisions but do not replace current package documentation.
Update the affected owner and its links when behavior, vocabulary, setup, or a validation route changes. Do not copy a promise here merely to make it easier to find.