From fd81656c3d119cbf91ebcab7b10ba53abbae0b93 Mon Sep 17 00:00:00 2001
From: Yunfei He <i.heyunfei@gmail.com>
Date: Mon, 15 Jun 2026 00:08:12 +0800
Subject: [PATCH] docs: adopt Project Context Records (PCR) for agent docs
 (#188)

Replace the homegrown "Context Engineering" convention with the canonical
Project Context Records (PCR) block in AGENTS.md, and migrate the
.agents/docs/ records to match.

- cross-links: [[wiki-link]] -> relative markdown [name](./name.md)
- provenance: the old "Maintainer decision (DATE): KEEP" markers -> canonical
  [VOUCHED @hyf0] stamps (dates dropped, KEEP/OVERRIDE verdicts kept), covering
  every variant ((DATE, user-blessed), (maintainer decision DATE), and
  "(Decision recorded after review surfaced it.)")
- methodology prose describing the mechanism reworded to the vouch vocabulary
  (generic [VOUCHED @handle])

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .agents/docs/accessibility-api.md   |  8 ++--
 .agents/docs/api-contract.md        |  8 ++--
 .agents/docs/component-authoring.md |  6 +--
 .agents/docs/ink-divergences.md     | 69 ++++++++++++++---------------
 AGENTS.md                           | 34 ++++++++------
 5 files changed, 66 insertions(+), 59 deletions(-)

diff --git a/.agents/docs/accessibility-api.md b/.agents/docs/accessibility-api.md
index 545ea5a..96a8d95 100644
--- a/.agents/docs/accessibility-api.md
+++ b/.agents/docs/accessibility-api.md
@@ -1,11 +1,11 @@
 # Accessibility (ARIA + screen-reader) API
 
 How vue-tui exposes ARIA and renders screen-reader (SR) output, and why. Companion to the
-aria-camelCase blessed entry in [[ink-divergences]]; `renderToString` being layout-only and the
+aria-camelCase vouched entry in [ink-divergences](./ink-divergences.md); `renderToString` being layout-only and the
 `useWindowSize` name are now Ink parity (not divergences), and the reactive-refs return shape is
 covered by the shallowRef entry there. This file keeps the _why_ and the researched / run-verified
 findings those entries deliberately omit, so they are not re-derived expensively. The exported aria
-types are part of the public contract — see [[api-contract]].
+types are part of the public contract — see [api-contract](./api-contract.md).
 
 ## The constraint that shapes everything
 
@@ -29,7 +29,7 @@ to receive them and no browser to read them.
   `aria-role` ports from Ink/HTML unchanged — it is the runtime-compatible escape, not the
   type-safe path.
 - This is a Vue-idiom + reasonableness choice, **not parity** (Ink is kebab). See the
-  "Why align to Ink — and when not to" principle in [[ink-divergences]].
+  "Why align to Ink — and when not to" principle in [ink-divergences](./ink-divergences.md).
 
 ## Type-safety boundary (run-verified: `tsc` + `vue-tsc`)
 
@@ -80,7 +80,7 @@ sees the non-empty string as truthy) where ARIA says visible; bare / `={true}` h
   suite — the public string API does not surface SR (Ink also keeps its SR-string rendering
   test-internal).
 - **`renderScreenReaderOutput(node)`:** the linearizer that walks the host tree's
-  `internal_accessibility`. **`/internal`-only** (maintainer decision 2026-06-14). Ink keeps its
+  `internal_accessibility`. **`/internal`-only** [VOUCHED @hyf0]. Ink keeps its
   counterpart (`renderNodeToScreenReaderOutput`) module-internal and never exports it; we match
   that. It was never usefully public anyway — its only parameter type (`TuiNode`) and the
   node-construction primitives needed to build one are not in the public barrel, so a public
diff --git a/.agents/docs/api-contract.md b/.agents/docs/api-contract.md
index 8bfbb89..305b170 100644
--- a/.agents/docs/api-contract.md
+++ b/.agents/docs/api-contract.md
@@ -1,7 +1,7 @@
 # Public API contract & surface
 
 What is — and isn't — part of `@vue-tui/runtime`'s public contract, and how the contract is
-tested. (Behavioral _divergences_ from Ink live in [[ink-divergences]]; this file is about the
+tested. (Behavioral _divergences_ from Ink live in [ink-divergences](./ink-divergences.md); this file is about the
 SHAPE of the public surface itself.)
 
 ## The contract = public exports **and their user-consumable types**
@@ -24,7 +24,7 @@ Because it is contract, it is **tested, not merely shipped**:
   `@ts-expect-error`. Type-only exports are erased at runtime, so the _type_ surface is guarded
   individually rather than exhaustively snapshotted.
 - Type-_safety_ behavior is established by RUNNING the type-checker against real usage (`tsc` for
-  TSX, `vue-tsc` for templates), never assumed. See [[accessibility-api]] for a worked example —
+  TSX, `vue-tsc` for templates), never assumed. See [accessibility-api](./accessibility-api.md) for a worked example —
   which aria spellings the compiler does and does not catch, proven with both tools.
 
 ## `/internal` is NOT the contract
@@ -42,7 +42,7 @@ Placement rule for any export:
 
 Packaging/build internals (the `exports` field shape, `.mjs` paths, `dist` layout) are likewise
 **not** part of the behavioral/type contract and are not aligned to Ink — see the alignment-scope
-note in [[ink-divergences]].
+note in [ink-divergences](./ink-divergences.md).
 
 ### Accepted incidental exposure: `TuiNode` via `TuiApp`
 
@@ -53,4 +53,4 @@ non-fix, not a contract**: `_container` is a Vue-internal field no consumer uses
 is cosmetic (zero functional impact), and type-only surface isn't held to strict SemVer. Narrowing
 it (`App<unknown>` / a `Pick<App, …>` allowlist) was considered and skipped as ceremony for a
 cosmetic gain on a pre-1.0 library. Treat `TuiNode`-through-`TuiApp` as out-of-contract; don't
-re-flag it. (Decision recorded after review surfaced it.)
+re-flag it. [VOUCHED @hyf0]
diff --git a/.agents/docs/component-authoring.md b/.agents/docs/component-authoring.md
index 7def710..e9bb4bd 100644
--- a/.agents/docs/component-authoring.md
+++ b/.agents/docs/component-authoring.md
@@ -30,8 +30,8 @@ The deciding distinction — get this right and the split falls out:
   → **provide/inject**, never parent-walking or `.name` matching. `Text` and `Transform`
   `provide(TextContextKey, true)`; `Text` and `Newline` `inject` it. Template-friendly,
   matches vue-tui's existing `AppContextKey` / `FocusContext` style, and is the
-  maintainer-endorsed Vue idiom (provide/inject outnumbers slot inspection 4–20× in the
-  libraries surveyed). It replaced the old, duplicated `getCurrentInstance()` parent walk.
+  well-established Vue idiom (provide/inject outnumbers slot inspection 4–20× in the
+  libraries surveyed). It replaced the old, duplicated `getCurrentInstance()` parent walk. [VOUCHED @hyf0]
 - **"What are my children's actual contents?"** (filter inert/`Comment` vnodes, detect
   emptiness) → **render function** + `slots.default()`. A `<template>` can't reach the vnode
   array; forcing it means calling the slot twice per render — an accepted-but-unsanctioned
@@ -57,7 +57,7 @@ Ink, which colorizes lazily). That gate is **dissolved**: `Text` now validates `
 invalid value (`backgroundColor="bold"` — a chalk _modifier_, not a color; or `color="level"`
 — a chalk key that exists but is not a callable color method) is invalid regardless of
 content; content-dependent validation is a latent footgun (it throws only once content
-appears). This completes the [[ink-divergences]] "Invalid input is validated at the component
+appears). This completes the [ink-divergences](./ink-divergences.md) "Invalid input is validated at the component
 layer" principle — `Text` was the inconsistent holdout. Removing the gate is also what let
 `Text` stop inspecting children and become a template.
 
diff --git a/.agents/docs/ink-divergences.md b/.agents/docs/ink-divergences.md
index ae91c3d..71d8e5a 100644
--- a/.agents/docs/ink-divergences.md
+++ b/.agents/docs/ink-divergences.md
@@ -23,7 +23,7 @@ alignment.
 It follows that **alignment is not the top priority**. When Ink's behavior is itself a defect,
 is unreasonable, or is un-idiomatic for Vue, **conformance to Vue's philosophy and the plain
 reasonableness/correctness of the behavior outrank parity.** There vue-tui deliberately diverges,
-and records it here so the choice is conscious and blessed, not drift.
+and records it here so the choice is conscious and vouched, not drift.
 
 This guards against two opposite failure modes:
 
@@ -33,11 +33,11 @@ This guards against two opposite failure modes:
   as defects, not contracts.)
 - **Lazy divergence** — inventing a different behavior and rationalizing it as "Vue's way is
   better" with no genuine Vue-philosophy or correctness reason. Mere presence in this file is
-  **not** a blessing; every kept divergence needs a real reason and a maintainer decision.
+  **not** a vouch; every kept divergence needs a real reason and an explicit `[VOUCHED @handle]` stamp.
 
 So the test for any difference is never just "does it match Ink?" but "is this the most
 reasonable, most Vue-idiomatic behavior — and where it diverges from Ink, is that because Ink is
-wrong or un-Vue, recorded with a maintainer decision?" Reasonableness and Vue idiom come first;
+wrong or un-Vue, recorded with a `[VOUCHED @handle]` stamp?" Reasonableness and Vue idiom come first;
 alignment is simply the cheapest way to get there whenever Ink is already right.
 
 ## How to Classify a Divergence
@@ -62,7 +62,7 @@ sections are narrower, while later sections are broader fallbacks.
 4. If the note is not a divergence, put it in **Non-Behavioral Notes**.
 
 Each divergence entry states what Ink does, what vue-tui does, and why the difference is
-deliberate. Some entries also record consequences, costs, tests, or maintainer decisions
+deliberate. Some entries also record consequences, costs, tests, or the reasoning behind a vouch
 where those details are needed to understand the decision.
 
 ---
@@ -76,8 +76,7 @@ remain compatible; vue-tui only adds accepted inputs, contexts, or capabilities.
 
 - **Ink:** keeps a single `staticNode`; only one `<Static>` is honored.
 - **vue-tui:** `findStatics(root)` renders **every** `<Static>` in the tree.
-- **Why:** a tree with two `<Static>` regions renders both. Maintainer decision
-  (2026-05-30): KEEP.
+- **Why:** a tree with two `<Static>` regions renders both. KEEP. [VOUCHED @hyf0]
 
 ### Ctrl+C exits under the kitty protocol too
 
@@ -90,7 +89,7 @@ remain compatible; vue-tui only adds accepted inputs, contexts, or capabilities.
   `useFocus` / `usePaste`, or none).
 - **Why:** `exitOnCtrlC` is defined in terms of Ctrl+C, not one byte encoding. Keeping the
   exit at the single always-on layer avoids splitting the behavior across two places. Opt
-  out with `exitOnCtrlC: false`. Maintainer decision (2026-05-30): KEEP. Tests:
+  out with `exitOnCtrlC: false`. KEEP. [VOUCHED @hyf0] Tests:
   `usePaste-only app exits on {legacy,kitty} Ctrl+C` in `input-kitty.test.ts`.
 
 ### `parseKeypress` filters kitty query-responses
@@ -136,9 +135,9 @@ remain compatible; vue-tui only adds accepted inputs, contexts, or capabilities.
   node is reached via `$el`. Because `<Box>` is a `defineComponent`, the `$el` path is in
   fact the **primary** path a normal `ref` on `<Box>` takes — the bare host-node ref is the
   rarer raw-host case. Supporting both is a strict superset that matches how Vue refs behave;
-  a bare host-node ref still works identically to Ink. Maintainer decision (2026-06-13): KEEP
+  a bare host-node ref still works identically to Ink. KEEP
   — a reasonable Vue-idiomatic adoption (the component-instance ref is the natural Vue path;
-  the bare host-node ref stays Ink-identical).
+  the bare host-node ref stays Ink-identical). [VOUCHED @hyf0]
 
 ### Two apps sharing one stdin both receive input
 
@@ -159,7 +158,7 @@ remain compatible; vue-tui only adds accepted inputs, contexts, or capabilities.
   race, and a shared raw-mode refcount matches the ownership model when several renderers
   share one input. The common one-app-to-terminal flow is unchanged: one controller's
   `localRefs` equals the shared `refs`. Test: `raw-mode-lifecycle.test.tsx` ("two apps
-  sharing one stdin both receive input..."). Maintainer decision (2026-06-07): KEEP.
+  sharing one stdin both receive input..."). KEEP. [VOUCHED @hyf0]
 
 ## Vue API and Mental Model Divergences
 
@@ -190,7 +189,7 @@ current-props model, or API conventions.
   value by re-running the hook; Vue wraps it in a ref the template subscribes to. This is
   the general rule, not a per-API choice. `useFocusManager().activeId` is just one
   instance. This follows Vue's philosophy: changing state is exposed as a reactive source,
-  not as a one-time snapshot. Maintainer decision (2026-06-07): KEEP.
+  not as a one-time snapshot. KEEP. [VOUCHED @hyf0]
 
 #### A `setup()`-throwing component emits a dev-only `[Vue warn]` on stderr
 
@@ -210,7 +209,7 @@ current-props model, or API conventions.
   the stray warn is not mistaken for vue-tui behavior: it is Vue's framework diagnostics.
   The prefix filter may also drop user-authored stderr logs that intentionally reuse the
   reserved `[Vue warn]` prefix; use a different application prefix when that output must be
-  preserved. Maintainer decision (2026-06-06): KEEP.
+  preserved. KEEP. [VOUCHED @hyf0]
 
 #### React concurrent mode
 
@@ -256,8 +255,8 @@ current-props model, or API conventions.
   `() => []` collapse alone is **not** model-forced (Vue can see the empty array); it is
   a deliberate consistency rider — in each engine `() => []` and `() => [false]` behave
   alike (Ink renders a node for both, vue-tui omits both), and aligning only `[]` would
-  create an asymmetry that exists in neither engine without reaching parity. Maintainer
-  decision (2026-06-07): KEEP. Test: `transform.test.tsx`.
+  create an asymmetry that exists in neither engine without reaching parity. KEEP. [VOUCHED @hyf0]
+  Test: `transform.test.tsx`.
 
 ### Vue-Idiomatic Choices
 
@@ -271,7 +270,7 @@ current-props model, or API conventions.
   app handle are therefore Vue-shaped (`MountOptions` / `TuiApp`), not `render()`-shaped
   (`RenderOptions` / `Instance`). Do not add Ink-compatible aliases here: aliases would
   make the public API look render-shaped while the actual runtime contract is app-shaped.
-  Maintainer decision (2026-06-07): KEEP.
+  KEEP. [VOUCHED @hyf0]
 
 #### Removing `display` resets to the default (visible)
 
@@ -287,8 +286,8 @@ current-props model, or API conventions.
 - **vue-tui:** a removed/undefined `display` resets to the Box default `DISPLAY_FLEX`
   (visible): the same state as if the prop had never been set.
 - **Why:** render = f(current props): no `display` set means the default (visible).
-  Persisting a withdrawn prop, or flipping it to hidden, does not match that model. Maintainer
-  decision (2026-05-31): KEEP.
+  Persisting a withdrawn prop, or flipping it to hidden, does not match that model. KEEP.
+  [VOUCHED @hyf0]
 
 #### Nullish `flexDirection` / `flexWrap` reset to Box defaults
 
@@ -334,15 +333,15 @@ current-props model, or API conventions.
   `UsePasteOptions`, `UseFocusOptions`, `UseAnimationOptions`. `useAnimation`'s options type
   originally shipped as `AnimationOptions` — the lone holdout — and was renamed to
   `UseAnimationOptions` (a hard rename, no alias) while the package is pre-1.0 (`0.0.x`, no
-  stability promise yet). **Maintainer decision (2026-06-13): export composable options types
-  as `UseXOptions`; renamed `AnimationOptions` → `UseAnimationOptions`.**
+  stability promise yet). **Export composable options types
+  as `UseXOptions`; renamed `AnimationOptions` → `UseAnimationOptions`.** [VOUCHED @hyf0]
 - **Why:** the public surface should read like Vue code: named composable return types get a
   single convention (`UseXReturn`) instead of Ink's mix of `XProps`, result names, and bare
   names, and `XProps` keeps its Vue meaning (component props). Return shapes still mirror
   Ink field-for-field where the same public state exists; reactive state is represented as
   refs for the model-implied reason documented above. Do not export Ink-compatible alias
   names for these types: Vue-first naming is more important than making type imports look
-  portable across React and Vue. Maintainer decision (2026-06-07): KEEP.
+  portable across React and Vue. KEEP. [VOUCHED @hyf0]
 
 #### Function-valued composable inputs use `MaybeRef`, not getters
 
@@ -358,7 +357,7 @@ current-props model, or API conventions.
   with `unref()` when input/paste occurs. It deliberately does **not** accept
   `MaybeRefOrGetter<Handler>` because a handler is itself a function:
   `useInput(() => {})` must remain an input handler, not be reinterpreted as a getter that
-  returns one. Maintainer decision (2026-06-06): KEEP.
+  returns one. KEEP. [VOUCHED @hyf0]
 
 #### `<Static>` uses a scoped slot object instead of positional render arguments
 
@@ -370,11 +369,11 @@ current-props model, or API conventions.
 - **Why:** this is the framework-native match for React render children. Vue scoped slots
   pass one props object, not multiple positional arguments, and that object form is what
   Vue users expect for slot payloads. The rendered item/index values remain equivalent.
-  Maintainer decision (2026-06-06): KEEP.
+  KEEP. [VOUCHED @hyf0]
 
 #### ARIA props are typed camelCase; kebab still works but is not type-checked
 
-Full design, type-safety findings, and precedent survey: [[accessibility-api]].
+Full design, type-safety findings, and precedent survey: [accessibility-api](./accessibility-api.md).
 
 - **Ink:** kebab string-literal prop keys (`'aria-label'`, `'aria-hidden'`, `'aria-role'` union,
   `'aria-state'` object); JSX keys never camelize.
@@ -387,7 +386,7 @@ Full design, type-safety findings, and precedent survey: [[accessibility-api]].
   kebab `aria-*` is not (Vue/Volar treat it as a global attr). So `ariaRole` is the type-safe
   spelling and `aria-role` the runtime-only porting escape; the rejected kebab-only `$attrs`
   alternative loses typing + Boolean coercion for nothing the checker doesn't already give.
-  Maintainer decision (2026-06-14): KEEP.
+  KEEP. [VOUCHED @hyf0]
 - **Edges:** a future compound aria word must be declared as its mechanical camelize
   (`ariaHaspopup`, not `ariaHasPopup`) or folded into `ariaState`; `aria-hidden` is modeled
   boolean (bare → true), but the string `aria-hidden="false"` wrongly hides (recorded edge).
@@ -418,7 +417,7 @@ different runtime behavior, ownership rule, or out-of-contract handling.
   (string `.message` else `String(value)`) is useful for the lint-discouraged non-`Error`
   throw, and matching the rejected message to it removes a confusing internal inconsistency
   (`throw {message:'x'}` once displayed `x` but rejected `[object Object]`). Introduced
-  2026-05-31; consistency fixed 2026-06-12. Maintainer decision (2026-06-12): KEEP.
+  2026-05-31; consistency fixed 2026-06-12. KEEP. [VOUCHED @hyf0]
 
 ### Second `mount()` on a live stdout is an inert no-op
 
@@ -443,7 +442,7 @@ different runtime behavior, ownership rule, or out-of-contract handling.
   public path to it (`createApp` binds the tree to the app, so an Ink-style rerender would
   mean reaching into the live app's container or tearing it down first), and on a misuse path
   keeping the running app stable beats auto-tearing it down (which would churn on a re-render
-  glitch). Maintainer decision (2026-06-04): KEEP. Test: `instance-reuse-guard.test.tsx`.
+  glitch). KEEP. [VOUCHED @hyf0] Test: `instance-reuse-guard.test.tsx`.
 
 ### Raw mode is owned for the interactive lifetime by default (`rawMode` option)
 
@@ -474,7 +473,7 @@ different runtime behavior, ownership rule, or out-of-contract handling.
   an Ink app holding a `useInput` already does not). The "render and auto-exit" pattern
   (Ink's inline-output use) is `rawMode: 'auto'`. Tests: `raw-mode-lifecycle.test.tsx`
   (`'always'` holds raw with no input hook; `'auto'` stays cooked; no mid-session
-  oscillation). Maintainer decision (2026-06-13): KEEP.
+  oscillation). KEEP. [VOUCHED @hyf0]
 
 ### `useCursor()` re-asserts the declared caret every commit (persistent declaration)
 
@@ -515,8 +514,8 @@ different runtime behavior, ownership rule, or out-of-contract handling.
   frame) would dissolve that residue. Tests: PTY `cursor-sibling-repaint.test.ts` (a
   sibling-topology spinner tick re-asserts the caret, not the corner) and unit
   `frame-writer.test.ts` (a non-dirty changed-output re-render re-emits the declared suffix;
-  D5 clamp). **Maintainer decision (2026-06-12): OVERRIDE prior KEEP — adopt per-commit
-  re-assert.** The prior KEEP (2026-06-01) had kept the reactivity-tied behavior to avoid
+  D5 clamp). **OVERRIDE prior KEEP — adopt per-commit
+  re-assert.** [VOUCHED @hyf0] The prior KEEP (2026-06-01) had kept the reactivity-tied behavior to avoid
   diverging from Ink in the sibling direction; that rationale was overturned when running
   real terminal apps showed Ink itself zombies the caret there, so matching Ink was matching
   a defect, not parity.
@@ -579,8 +578,8 @@ different runtime behavior, ownership rule, or out-of-contract handling.
   children with child width/height after subtracting the border. Bubble Tea's viewport
   follows the same separation at the component level: content keeps its natural size while
   the viewport exposes a bounded visible window and offsets. The behavior also prevents
-  negative repeat/count math and paint crashes in tiny legal boxes. Maintainer decision
-  (2026-06-07): KEEP. Tests: `text-wrap-width.test.tsx`, `flex.test.tsx`,
+  negative repeat/count math and paint crashes in tiny legal boxes. KEEP. [VOUCHED @hyf0]
+  Tests: `text-wrap-width.test.tsx`, `flex.test.tsx`,
   `text.test.tsx`, `absolute-in-degenerate-box.test.tsx`.
 - **Future `content-box`:** this does not block adding an explicit content-box option
   later. That option would change how a requested size is expanded into an outer box size
@@ -622,7 +621,7 @@ different runtime behavior, ownership rule, or out-of-contract handling.
   exceptions fall back because they have a meaningful standalone behavior (zero metrics / a
   working animation), so throwing would remove a useful capability. Required app,
   terminal, focus, and input context should fail fast when absent; no-op defaults hide bugs.
-  Maintainer decision (2026-06-07): KEEP.
+  KEEP. [VOUCHED @hyf0]
 
 ### Invalid input is validated at the component layer, not the paint layer
 
@@ -655,19 +654,19 @@ different runtime behavior, ownership rule, or out-of-contract handling.
 - **Cost:** the component-layer check is eager (no paint-time layout/squash info), so it
   over-throws in a few degenerate, invalid-input-only cases Ink never reaches. For the
   covered public inputs in normal reachable cases, both libraries error; only the channel
-  (recoverable reject vs crash) differs. Maintainer decision (2026-06-07): KEEP. vue-tui
+  (recoverable reject vs crash) differs. KEEP. [VOUCHED @hyf0] vue-tui
   makes the more reliable library choice here: reject the same invalid input with a
   recoverable, prop-specific error instead of preserving Ink's lower-level paint crash and
   chalk implementation message. Tests: `background-color.test.tsx`, plus the `borderStyle`
   validation tests.
-- **Text validates regardless of content (2026-06-13, user-blessed):** `<Text>` now
+- **Text validates regardless of content:** `<Text>` now
   validates `color` and `backgroundColor` on every render, not only when its content is
   non-empty — matching `<Box>`, which already validates its own colors unconditionally. Ink
   does not throw for empty text only because its colorize call is lazy (an incidental
   implementation artifact, not a design choice); an invalid value is invalid regardless of
   content, and content-gated validation is a latent footgun. Principle: reasonable behavior
   over incidental Ink parity. The former `wouldRenderNonEmptyText` gate was removed.
-  Screen-reader-hidden Text still returns before validation (matches Box).
+  Screen-reader-hidden Text still returns before validation (matches Box). [VOUCHED @hyf0]
 
 ## Non-Behavioral Notes
 
diff --git a/AGENTS.md b/AGENTS.md
index 0551f42..ae540ad 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -26,21 +26,29 @@
 - Behavior claims must be **run, not reasoned**: a parity assertion or `ink-divergences.md` "what Ink does" line is a hypothesis until a real harness against the pinned version (real frames/stderr/exit) confirms it. Source-reading and memory can mislead; when a run contradicts the code you read, trust the run.
 - When documenting an intentional Ink divergence, update `.agents/docs/ink-divergences.md` and follow its "How to Classify a Divergence" flow. Do not add placeholder or unsorted entries; if the classification is unclear, state that uncertainty in the entry's rationale.
 
-# Context Engineering
+## Project Context Records (PCR)
 
-Long-lived design context lives in `.agents/docs/` (committed — distinct from the
-uncommitted `docs/` working-notes folder). Convention, borrowed from rolldown:
+This project follows **Project Context Records (PCR)** —
+methodology: https://github.com/hyf0/project-context-records. PCR keeps the
+project's durable design context — the _why_, the decisions, the architecture —
+so you inherit it instead of re-deriving or re-litigating what's already settled.
 
-- One concept per file; files cross-link with `[[other-doc]]`.
-- If a design doc covers the area you're about to work in, **read it first**.
-- If your change affects a design doc, **update it in the same change**. Docs that drift
-  from reality are worse than no docs.
-- Capture the _why_ — trade-offs considered, alternatives rejected, known pitfalls — not
-  just what the code does.
-- Be concise and direct: the essential what + why, led by the principle or intuition. Lose no
-  information, but don't write essays or exhaustive mechanism dumps. When a behavior is the
-  correct default (e.g. render = f(current props)), state the principle — don't dress it up as
-  a framework limitation.
+When working here:
+
+- **Where they live.** Records are in `.agents/docs/` — one topic per file,
+  cross-linked with relative Markdown links (`[name](./name.md)`).
+- **Read first.** If a record covers the area you're touching, read it before acting.
+- **Record as you go.** Proactively write down context worth keeping — and whenever
+  a human asks you to. No required format, no fixed list of what qualifies: if it's
+  true about this project, not visible in the code, and useful beyond the moment,
+  it's worth a record.
+- **Keep it fresh.** If your change affects a record, update it in the same change —
+  a stale record is a trap, not an asset.
+- **Provenance.** An unstamped line is AI-accumulated: challenge and verify it freely.
+  A `[VOUCHED @handle]` stamp (on a line, or at the top of a file) means a human
+  vouched for it — treat it as settled; reopen or re-verify only on new evidence, a
+  changed constraint, or a human's say-so. Add a stamp only on a human's explicit
+  instruction; reading past a line, or not objecting, is not a stamp.
 
 <!--VITE PLUS START-->