# Design proposals and PRDs

> The canonical bilingual home for OINK PRDs and designs that are still being evaluated.

---

LLMS index: [llms.txt](/llms.txt)

---

> [!WARNING] Non-normative material
> A proposal describes behaviour that may not exist. Current behaviour is
> defined by the contracts, accepted decisions, implementation, and owning
> checkers. Never use a proposal as a configuration reference.

This section is the canonical home for OINK product requirement documents,
RFC-style designs, and unresolved maintainer proposals. Do not create a local
`plan/`, `plans/`, `proposal/`, or parallel design tree in the theme repository
or the documentation repository.

## Active proposals {#active-proposals}

| Proposal                                                                 | Current boundary                                                                                                     |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| [Backlinks and knowledge graph](/docs/design/proposals/knowledge-graph/) | Draft; no graph or backlink implementation exists                                                                    |
| [Media convergence](/docs/design/proposals/media-convergence/)           | Draft; records only the remaining cross-surface convergence after the shared content resolver and Zoom marker landed |
| [Bulk agent indexes](/docs/design/proposals/agent-indexes/)              | Draft; per-page Markdown and `llms.txt` already exist, while bulk text and navigation JSON do not                    |

## Where a new PRD goes {#where-a-new-prd-goes}

Create one English-primary page and its Simplified Chinese peer:

```text
content/docs/design/proposals/<slug>.md
content/docs/design/proposals/<slug>.zh.md
```

Use explicit, stable English heading IDs in both files. Keep code, keys, paths,
versions, and API names unchanged in Chinese. A proposal begins with visible
draft status and includes:

1. status, owner, date, and affected contract surface;
2. context and evidence;
3. goals and explicit non-goals;
4. proposed behaviour and output/accessibility/security boundaries;
5. compatibility and migration impact;
6. implementation and owning-checker plan;
7. acceptance criteria and open decisions;
8. a decision log for later changes to the proposal itself.

Large experiments may add a dated page under
[`../research/`](/docs/design/research/), but temporary logs and generated
artifacts stay outside Hugo content and outside Git.

## Lifecycle {#lifecycle}

```text
draft proposal
    ├── rejected/superseded → remove from the active tree; preserve Git history
    └── accepted
          ├── implementation + owning checker
          ├── affected EN/ZH contract
          ├── accepted Design decision when rationale is durable
          └── changelog, migration, and user docs when their audiences need them
```

Acceptance does not turn the PRD into a second contract. Move stable behaviour
into the owning contract, stable rationale into Decisions, and user steps into
the relevant guide. Then retire the proposal from active navigation. A local
build, commit, tag, public module, consumer pin, and deployment remain separate
completion states.

## Review gate {#review-gate}

Before implementation, reviewers confirm that the proposal does not duplicate
an existing shell, resolver, component family, or data authority. During
implementation, a changed design updates this bilingual proposal before code
silently diverges. Acceptance requires the narrow theme checker, the real
documentation site, rendered EN/ZH, relevant outputs, accessibility, and
responsive review.

---

Section pages:

- [Backlinks and knowledge graph](/docs/design/proposals/knowledge-graph/): A draft three-stage design for deriving backlinks and local or global graph views from ordinary Hugo links.
- [Media convergence](/docs/design/proposals/media-convergence/): A draft for the remaining convergence between content images, numbered figures, Landing media, and featured-image selection.
- [Bulk agent indexes](/docs/design/proposals/agent-indexes/): A draft for optional llms-full text bundles and a stable navigation JSON derived from OINK's existing Markdown output and navigation authority.