Design proposals and PRDs
A proposal describes behavior that may not exist. The contracts, accepted decisions, implementation, and owning checkers define current behavior. Never use a proposal as a configuration reference.
This section contains the authoritative 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
| Proposal | Current boundary |
|---|---|
| Backlinks and 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 | 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 | 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 | Paper/Slate ship in v1.2.0; Ink/Terminal ship as explicit opt-in experiments awaiting design acceptance; see the accepted decision and dated acceptance record |
Component refinement, unified diagram reading and local search refinement ship in 1.4.0 and now live under accepted decisions. Translation comparison ships in 1.5.0 as an accepted decision; its draft is retired.
The table-reading draft is also retired: the accepted decision
and component contract define the narrower,
.expand behavior released in OINK 1.4.0.
The bulk agent-index proposal was retired after its outputs were released.
Architecture defines the accepted
behavior. Agent-ready output gives the user steps.
The Book publication proposal was retired after BookManifest and the
EPUB/PDF tools were released. The accepted behavior is documented in
Architecture and
Writing a book; dated downstream adoption evidence
is recorded in Consumer evidence.
Pending consumer adoption does not keep an upstream design proposal active.
Git history retains both proposal drafts.
The generated-configuration-schema proposal completed its lifecycle and was retired: Configuration defines the required behavior, the generated configuration schema decision records the accepted rationale, and Git history retains the draft text.
CLI workspaces and adapters
Explicit workspaces and optional adapters remain in the current reduced CLI. The current contract defines the command boundary, and the R1–R8 and A18 record preserves the historical acceptance evidence. The finite maintenance roadmap remains retired from active navigation.
Where a new PRD goes
Create one English-primary page and its Simplified Chinese peer:
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:
- status, owner, date, and affected contract surface;
- context and evidence;
- goals and explicit non-goals;
- proposed behaviour and output/accessibility/security boundaries;
- compatibility and migration impact;
- implementation and owning-checker plan;
- acceptance criteria and open decisions;
- a decision log for later changes to the proposal itself.
For a large experiment, you may add a dated page under
../research/. Keep temporary logs and generated
artifacts outside Hugo content and Git.
Lifecycle
Acceptance does not make the PRD a second contract. Move accepted behavior to the owning contract, stable rationale to Decisions, and user steps to the applicable guide, then retire the proposal from active navigation.
Review gate
Before implementation, confirm that the proposal does not duplicate an existing shell, resolver, component family, or data authority. If the design changes during implementation, update this bilingual proposal before changing the code. Acceptance requires the focused theme checker and the real documentation site. It also requires rendered EN/ZH, applicable outputs, accessibility checks, and responsive review.
Read-only 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
preserves historical acceptance of the earlier browser implementation.
Reviewed editing
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
remains historical evidence rather than the current command API.