# 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/) | G1 (static backlinks) is accepted, implemented on the theme's main branch, and ships with OINK 0.8.0; the local and global graphs (G2/G3) remain draft |
| [Media convergence](/docs/design/proposals/media-convergence/)           | Partially implemented; the media-result contract and Landing resource metadata shipped, M3 resolved for native-image processing, retirement (M4) open |
| [OINK CLI and the next product stage](/docs/design/proposals/oink-cli-roadmap/) | Independent Go repository and first-stage boundary accepted; local CLI candidate implemented, not publicly released; later theme, migration, adoption, versioning, OpenAPI, and platform stages remain proposals |
| [Visual presets and appearance switching](/docs/design/proposals/visual-presets/) | Paper/Slate locally implemented; Ink/Terminal remain research; see the accepted decision and dated acceptance record |

The bulk agent-index proposal retired after the outputs shipped. Its stable
behaviour now belongs to [Architecture](/docs/design/architecture/#outputs-and-runtime),
and user steps belong to [Agent-ready output](/docs/customize/agents/).
The Book publication proposal likewise retired after `BookManifest` and the
EPUB/PDF tooling shipped. The stable behaviour belongs to
[Architecture](/docs/design/architecture/#outputs-and-runtime) and
[Writing a book](/docs/write/book/#print); dated downstream adoption evidence
belongs to [Consumer evidence](/docs/design/research/consumer-evidence/#publication-adoption).
Remaining consumer adoption does not keep an upstream design proposal active.
Both proposal drafts remain available in Git history.

The generated-configuration-schema proposal has been retired through the
lifecycle: the behaviour is documented normatively in
[Configuration](/docs/customize/config/#editor-schema), the long-lived
rationale moved to the
[generated configuration schema decision](/docs/design/decisions/config-schema/),
and the draft text is preserved by Git history.

## CLI workspaces and adapters {#cli-maintenance-candidate}

Explicit workspaces and optional adapters remain in the current reduced CLI.
The [current contract](/docs/design/decisions/cli/#workspace-registry) and
[usage guide](/docs/start/cli/#workspace-registry) define the command boundary.
The dated R1–R8 and A18 record is historical source/binary-bound evidence.
It does not qualify later command or output changes. The finite maintenance
roadmap remains retired from active navigation; no public CLI release or
deployment is established.

## 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.

## Read-only Studio candidate {#cli-studio-candidate}

Studio is removed from the current CLI on 2026-10-04. Use `oink dev`,
an ordinary editor, and structured `inspect`/`check` reports. The
[R7 record](/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r7)
preserves historical acceptance of the earlier browser implementation.

## Reviewed editing {#cli-editing-candidate}

General source editing is removed from the current CLI. Guarded `new`,
`move`, review records, and baseline plans remain. Old editing plans are
rejected. The [R8 record](/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r8)
remains historical evidence rather than the current command API.

---

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.
- [OINK CLI and the next product stage](/docs/design/proposals/oink-cli-roadmap/): The accepted independent CLI boundary and local first-stage candidate, with later adoption, theme, migration, and content-model proposals kept explicit.
- [OINK CLI maintenance roadmap](/docs/design/proposals/oink-cli-maintenance-roadmap/): The historical R1–R8 requirements record for documentation maintenance and Oink Studio, retained alongside acceptance evidence and the current reduced CLI contract.
- [Visual presets and appearance switching](/docs/design/proposals/visual-presets/): Paper and Slate ship in 1.2.0; Ink and Terminal are explicitly enabled experiments awaiting design acceptance.

---

Backlinks:

- [Design](/docs/design/)
- [Decisions](/docs/design/decisions/)
- [Research](/docs/design/research/)
- [CLI overview](/docs/start/cli-overview/)