Skip to content

This is the multi-page printable view of this section. .

Return to the regular view of this page.

Design decisions

Accepted decisions that explain why OINK’s current contracts and implementation have their present shape.
Accepted rationale

A decision explains why OINK selected one compatible design instead of another. The five contracts define the required current behavior. The implementation and its checkers define the executable facts.

OINK previously kept reviews, PRDs, and execution notes in a local plan/ directory, which made useful reasoning hard to find and allowed abandoned designs to appear authoritative. Accepted rationale now lives here, beside the contracts it supports, in the same bilingual, versioned site.

Decision map

Decision What it settles
Warnings and safe fallbacks Why ordinary preview survives invalid input while publication remains strict
Configuration model Where configuration belongs, how pages override it, and why OINK has no parallel configuration namespace
Markdown-first authoring Why native Markdown is preferred and Docs, Blog, Book, and Landing extend shared systems
Generated configuration schema Why the editor schemas are a generated projection, and how the drift gate keeps a third configuration authority from appearing
Optional CLI and result contract Independent Go executable, versioned diagnostics, coverage, and explicit write boundaries for the local CLI candidate
Visual presets Paper default, Slate compatibility, opt-in Appearance menu, independent mode and font boundaries
Expo albums Resource bundles, optional metadata, shared appearance, and album viewing
Blog gallery Article covers, shared Expo geometry, independent preferences, and readable captions
Table reading Explicit .expand, independent .wide, and a direct corner action with native table restoration
Translation comparison One switch, real same-origin translations, a lazy two-pane reader, and heading-based sync

| Component refinement | Shared styling, divided cards, compact steps and command strips | | Unified diagram reading | Shared Mermaid and local PlantUML viewing, source export and demand loading | | Local search refinement | Mixed queries, real section anchors, partial matches and section scope |

Record format

An accepted decision records its context, choice, consequences, and evidence that the choice remains current. It does not repeat a parameter reference or tutorial. Each decision links to its contract and verification checks, and its English and Simplified Chinese pages change together.

When a decision changes, update the implementation, checker, affected contract, and decision record in one delivery. Preserve the previous decision in Git history and the release changelog rather than leaving two active answers in the navigation tree.

1 - Warnings and safe fallbacks

Invalid input produces visible warnings and safe fallbacks. Checks verify diagnostics and rendered output without aborting on every warning.
Decision

OINK does not call Hugo’s errorf. Invalid author or site input produces a warning. OINK then uses a documented safe fallback or omits the invalid fragment. Development, CI, release, and deployment use Hugo Extended 0.168.0 without --panicOnWarning or HUGO_PANICONWARNING. Warnings stay visible; checks verify the specific diagnostic and the rendered fallback.

Context

Hugo builds the whole site as one transaction, so an errorf from one edited page makes every URL served by that rebuild return an error, including unrelated pages and the home page. The server process continues and recovers after the input is corrected, but other authors cannot use the preview in the meantime.

A warning allows the affected value to use a safe fallback while other pages remain available for inspection and the author receives a precise message. Production builds keep these warnings visible for review. The upstream LibSass deprecation warning is accepted; unexpected theme or content warnings need review.

Decision

Validation follows four rules:

  1. Name the invalid key and value, the allowed shape, and the fallback.
  2. Include a page position when the value came from page front matter; avoid repeating one site-wide warning for every page.
  3. Never pass an invalid value into a later operation. Validate first, then render from the normalized value.
  4. If no valid fallback exists, give a warning and render nothing. Do not invent content, make a network request, or emit an unsafe URL to continue.

The shared enum, boolean, CSS-length, and number shapes are in layouts/_partials/validate.html. Domain resolvers may add narrower checks, but they preserve the same warning/fallback contract.

Safety boundary

A build must never continue with unsafe output. OINK replaces a rejected CSS length before it reaches a style attribute, omits a component with incomplete remote service configuration before the browser can make a request, and removes unsafe action URLs. These fallbacks protect the reader without terminating Hugo.

Editing and publication share the warning and fallback behavior:

Stage Invalid input
hugo server or an ordinary local build Warn, fall back or omit, keep other pages available
CI, release validation, deployment Warn and fall back; review diagnostics and verify the output

Consequences

  • Every fallback is part of the public contract and must match the default declared by the theme.
  • When failure behavior changes to a fallback, update its tests. A negative test must check build success, warning text, and the rendered fallback or omission. A warning alone must not fail the Hugo build.
  • Checkers must test rejected output directly. For example, a URL security test must confirm that the unsafe URL is absent and that the warning is emitted.
  • Rendered markup checks verify the DOM, attributes, order, and emitted tokens, while the browser suite checks computed color, size, spacing, breakpoints, and interaction. When the public result is directly observable, a checker does not require exact Sass text.
  • Source-level checks detect forbidden constructs such as errorf and structural requirements that output cannot prove, such as one authority, one resolver, or a deliberately restricted caller set.

Verification

The owning references are the architecture contract, bin/check-params.py, and production builds of both the theme fixture and this integration site with Hugo Extended 0.168.0.

The warning policy was updated on 2026-10-18. Do not restore a warning-fatal publication gate.

2 - Configuration model

Hugo and Docsy-compatible configuration, with a narrow OINK interface and no parallel configuration namespace or global resolver.
Decision

OINK retains Hugo’s native keys and useful Docsy-compatible keys. Theme presentation and behavior use params.ui.*. A page override uses the matching top-level front-matter key. OINK does not add a params.oink.* tree or a second registry for Hugo configuration.

Context

OINK extends existing configuration with shells, content output, and local interaction. Earlier designs attempted to move all theme-owned keys to a new namespace and resolve a complete configuration dictionary for each page. That approach added a second configuration language beside Hugo’s keys, complicated section cascades, and required a large migration for limited behavior changes.

The current model defines these responsibilities:

Layer Responsibility Examples
Hugo Site identity, languages, menus, outputs, taxonomies, markup, modules baseURL, languages, outputs
Site facts and integrations Repository, version, author, local search, comments, external services params.github_repo, params.version, params.comments
OINK interface Shell, navigation, presentation, and local interaction params.ui.sidebar_*, params.ui.typography, params.ui.share
Page or section A narrow override of an eligible site default sidebar_enabled, featured_image, share
Data files Structured facts and ordered content that are not switches data/landing, data/download, data/docs_nav.json

Decision

The configuration API follows these rules:

  1. Site facts remain at the established top level. Interface choices belong under params.ui.*.
  2. A page override drops the ui. prefix and otherwise keeps the same name. A section cascade can apply that top-level key to its descendants.
  3. If a scalar describes the complete policy, use it for a boolean feature. Use a map only when a feature has subordinate settings. An established map may accept a boolean shorthand.
  4. Use positive, snake_case names grouped by function. Closely related settings share a prefix without requiring another nested resolver.
  5. Declare theme defaults in the theme’s hugo.yaml. Templates may derive a default only when one static value would remove a deliberate distinction between shells.
  6. Each feature family owns its normalization and validation, using a shared helper for common shapes. There is no global compatibility registry that silently rewrites arbitrary old keys.

The complete current key list, types, and defaults are in the configuration reference. This decision records the placement rules rather than maintaining a second parameter catalog.

Compatibility

For each public rename, the owning resolver gives a targeted warning, supported by a migration note and a negative test. Removed or misspelled keys do not require a permanent alias layer. If a rename would break the native API, retain Hugo and third-party camelCase keys. OINK-owned additions use snake_case.

Hugo’s ordinary front-matter and cascade model resolves page values. OINK does not ask authors to build a nested ui: tree in front matter or promise to merge arbitrary nested page maps.

Consequences

  • Adding a public setting requires a declared default or an explicitly derived default, an owning resolver, documentation, and a positive and negative test.
  • Configuration guides link to the one reference table instead of repeating types and defaults.
  • A new data structure is justified by ordered or repeated facts, not merely by a desire to avoid adding a parameter.
  • Invalid scalar values follow the warning and fallback decision.

Verification

bin/check-params.py checks declared defaults, page aliases, warning behavior, and the no-errorf requirement. The integration site’s bilingual and rendered-link suites check the public reference and its Chinese peer.

3 - Markdown-first authoring

Native Markdown carries common semantics, shortcodes fill capability gaps, and new content models extend shared shells.
Decision

If Goldmark can preserve the intended meaning, prefer a native Markdown form. Keep a shortcode only when the native form cannot provide its capability. For a new content scenario, extend an existing shell and data model. Do not create a parallel rendering system.

Context

OINK supports short manuals, large references, release archives, landing pages, and books. A survey of eleven consumer sites examined more than five thousand Markdown files and found both extremes: pages with almost no theme syntax and pages assembled from many nested shortcodes and local layout overrides.

A component API optimized only for the second group becomes a private DSL, while one limited to plain Markdown leaves books, rich figures, tab groups, and structured releases to site-local HTML. The useful boundary is capability, not novelty.

Decision

OINK applies the following order:

  1. Native Markdown first. Lists become Steps, Cards, or FileTree markers; tables become Fields or matrices; blockquotes become callouts; fenced code, images, and passthrough blocks carry attributes through render hooks.
  2. Shortcodes for missing capability. A full-form shortcode remains where CommonMark indentation, nested containers, processing options, or cross-page registration cannot express the same result safely.
  3. One semantic implementation. Native and full forms share normalization, partials, and an output contract, making them one component rather than two components with the same appearance.
  4. One extension line. A new Landing section joins the section registry; a new Blog presentation remains a Blog variant; Book numbering joins the content primitive and navigation systems. OINK does not add a second card, landing, navigation, or article shell for one feature.
  5. Facts stay outside presentation strings. Versions, repositories, dates, and ordered records come from front matter, site parameters, or data files. A shortcode argument is not a second source of truth.

Output contract

An authoring form is complete only when it defines a result for its semantic content in every enabled output:

Output Requirement
HTML Semantic server-rendered content; JavaScript only enhances it
Print Static, expanded, and free of controls that require interaction
Markdown / LLMS Source-shaped prose, links, lists, tables, and fences; no component HTML
RSS Safe static content or an explicit omission

This requirement prevents an HTML-only component from removing or corrupting content in agent output, feeds, or a printable book.

Trust and presentation

Render hooks and shortcodes use explicit allowlists to remove unsafe URL schemes, inline event handlers, and arbitrary style input. Author-provided classes are accepted only where the documented contract permits downstream site CSS. Icons use one Font Awesome class pair, without a second icon-ID language.

Consequences

  • A proposed component must first show why Markdown plus an existing hook is insufficient.
  • Keeping a full-form shortcode requires a named capability and tests for both forms reaching the same normalized output.
  • Shell variants use independent presentation keys so opting into a hero or a flow outline does not change taxonomies, feeds, pager order, or content type.
  • Consumer evidence is dated research, not a permanent excuse to freeze an accidental syntax. The current public surface remains defined by the component contract and shell contract.

Verification

Theme component, Book, output, and golden checkers test the authoring contract, followed by this site’s bilingual examples and browser suites for the integrated result. The Goldmark behavior that supports native forms is recorded in block-attribute research.

4 - Generated configuration schema

Editor schemas generated from existing configuration sources, with a CI gate that prevents drift.
Decision

bin/generate-config-schema.py generates the two JSON Schemas under schema/. It reads the theme’s hugo.yaml and the template read-point scan. CI rejects manual schema changes. The schemas are read-only projections of the existing configuration authorities. They are not a third authority.

Context

The theme already has two configuration authorities: hugo.yaml declares each default beside an explanatory comment, and the read-point scan in check-params.py identifies each key that the templates consume. Editors do not read either source, so authors have to enter params.ui.* keys and front matter from memory.

A JSON Schema gives editors completion and hover documentation, but a manually maintained schema can become a third authority that drifts from the implementation. Incorrect completion can cause more problems than no completion, so the schema must follow the existing sources.

Decision

bin/generate-config-schema.py generates two files under schema/. site-params.schema.json validates a site’s hugo.yaml, taking types and defaults from the theme’s own hugo.yaml and descriptions from its comment blocks. front-matter.schema.json validates page front matter and includes each key that the templates read as an authoring input, with descriptions from the matching site key. The generator excludes, by name, keys read only to warn about a rename or removal.

Two deliberate restraints are part of the decision:

  • The front-matter schema has no type constraints. Several keys accept a bare-boolean opt-out in addition to their site type (share: false, theme_color: false). An incorrect editor warning for valid input would be worse than no warning.
  • The hugo.yaml reader parses only the shapes that the file uses: nested maps, scalars, and inline lists. If the parser cannot read an input, it fails. The drift gate then fails instead of generating an incorrect schema.

The parameter checker identifies maps with documented boolean shorthand. The generated site schema preserves both boolean and object forms for those maps, including ui.dark_mode; pure configuration maps such as print and ui.expo remain objects. Front-matter read points such as feedback.enable produce nested properties under feedback, never literal dotted keys. Those properties do not exclude the supported boolean page override.

Consequences

To change a schema, change hugo.yaml or the templates that the scan reads. When public configuration changes, regenerate the schemas in the same commit. Maintainers do not need a second parameter inventory, but the generator and read-point scan constrain the public configuration surface: a new parameter key must use a shape they understand, or CI fails.

Verification

python3 bin/generate-config-schema.py --check regenerates schemas in memory and fails if schema/ is stale or missing. Theme CI runs this check with the parameter contract checker. Editor configuration and schema behavior are documented normatively in Configuration.

Visual preset enum values are also derived from preset-config.html. The preset_menu union accepts a boolean or a list of those resolver-owned values; the schema does not maintain its own list.

5 - Optional CLI and result contract

Executable ownership, versioned diagnostics, isolated validation, and guarded maintenance plans for the current local CLI candidate.
Current scope; local candidate

This contract describes the reduced local 0.1.0-dev command surface on 2026-10-04. Keep site diagnosis, real Hugo checks, initialization, builds, upgrades, and guarded maintenance plans. Cobra provides command help; colored English text is the default, with JSON/YAML results available. Studio, general editing, context, snippets, editor setup, and CI generation are retired. Historical R1–R8 acceptance applies only to its recorded source and binaries; it does not replace validation of the current implementation. The CLI is currently a local candidate and is not yet published as a standalone release or Homebrew package.

Context and ownership

The theme is a Hugo module, while consumer tooling is an optional executable with a separate installation and release lifecycle. pgsty/oink-cli owns that executable, named oink, and its Go tests. It invokes an external Hugo binary without importing Hugo’s private runtime or depending on a sibling checkout, Python, Node.js, or unpublished theme scripts at runtime.

Hugo owns configuration resolution, rendering, routes, and anchors. The CLI inspects Hugo’s effective configuration, module graph, mounts, and rendered files. It does not create a second route resolver, navigation authority, or configuration namespace. Theme-only regression scripts remain maintainer tools. Configuration preprocessing relocates workspace, replacement, and cache paths only in the temporary copy. Hugo still owns defaults, configuration merging, language selection, validation, and rendering semantics. The public architecture contract continues to own theme behavior; this page owns the initial CLI boundary and result envelope.

The CLI introduction provides a short overview and local build steps. The dated acceptance record separates executed checks from open limitations and release states. The maintenance acceptance record preserves the earlier R1–R8 program and its source-bound evidence. The roadmap retains future proposals and adoption hypotheses rather than duplicating the current command reference.

Command and mutation boundary

Help groups commands by daily, maintenance, and release work. Run oink COMMAND --help for the exact options.

Command Behavior and mutation boundary
doctor Read-only toolchain, configuration, module source, workspace/replacement/vendor diagnosis
check [links|translations|style] Actual Hugo output and declared source/translation policy in isolated copies
init DIRECTORY Validate the fixed Starter before creating a new or empty site
dev, build Ordinary Hugo processes. Hugo owns normal output/cache writes
upgrade --to TAG Preview by default. Only --write applies verified module changes
translations status, translations diff PAGE Read-only relationships, hash-review states, and differences
translations review SOURCE TARGET, baseline capture Requires an explicit reviewer/reason. Preview with an optional new --plan
new BUNDLE --title TEXT, move SOURCE TARGET Validate a candidate and preview its full diff. An optional new --plan saves the plan
plans apply FILE Revalidate supported saved plans. Write only selected files in the selected site
inspect PAGE, impact --since REF Read-only actual page and historical/current impact facts
workspace list, workspace check [GROUP] Select only explicitly registered sites
build --check Check, seal, and export the same isolated production render
artifacts verify Compare local artifacts with a manifest offline
verify Compare deployed HTTP responses with a manifest after explicit --network

Network access is off by default. All commands are non-interactive. Only dev and build accept Hugo arguments after --. Removed commands and their old plans cannot apply. Supported plan kinds are authoring.new, translations.review, baseline.capture, and content.move.

Versioned result envelope

Option Output
Default Concise colored English text
--json, -J One JSON oink.result/v1 object
--yaml, -Y One YAML document with the same result fields and types
--verbose, -v All findings, coverage details, and tool logs
--no-color Plain English text

Choose one structured format. Nonempty NO_COLOR or TERM=dumb also disables text colors. Structured output adds no terminal colors. Tool logs go to stderr. --format json|yaml and --non-interactive remain hidden compatibility options. Every command is non-interactive.

Default text shows status, counts, up to eight active findings, and explicit coverage omissions. Detailed facts and reviewed findings remain available in structured results. Plan and upgrade previews retain their complete diffs. Cobra owns command dispatch and focused help. CLI messages use short, active English sentences inspired by ASD-STE100. User content and external tool evidence retain their original language.

Field Type and meaning
schema_version String; oink.result/v1 for this contract
version String; CLI build version, including a development suffix when applicable
command String; requested command, or help / version
site Optional string; selected source or generated target directory when available
exit_code Integer; the CLI result code defined below
diagnostics Array of findings; an empty array means no recorded findings
coverage Array of scoped coverage statements; callers must inspect these alongside findings
evidence Array of subprocess records; empty when no subprocess ran
data Optional command-specific JSON value; current commands return objects such as inspected facts, initialization provenance, or an upgrade plan

The JSON Schema describes this envelope.

The first version permits additive fields and new rule IDs. Consumers should ignore unknown fields and treat IDs as opaque strings rather than parse their spelling. A change to the meaning or type of an existing envelope field requires a new schema version. Command-specific facts and raw tool output serve as evidence, not an SDK for importing internal Go packages.

The machine-readable schema is shipped in the CLI repository as schema/result.v1.schema.json.

Each evidence record has command (an argument array), optional directory, stdout, stderr, and the subprocess’s exit_code. Captured inspection and build output remains available in the result. Directly streamed dev/build output is sent to the logging stream rather than buffered again in evidence. The subprocess status remains separate from the CLI’s 0/1/2 result; a negative subprocess status can mean that no normal exit code was obtained.

Findings, severity, and locations

Every diagnostic has rule_id, severity, message, and action, plus an optional location. Stable rule IDs identify the condition. Raw Hugo wording, translated messages, paths, and build-specific details are not stable IDs. Existing IDs must not be reassigned to a different condition.

The optional incomplete: true identifies a required-work failure that policy cannot downgrade. Reviewed exclusions and baseline acknowledgements retain the finding in diagnostics with disposition: "excluded" or "baseline" and review containing reason, reviewed_by, and RFC 3339 reviewed_at. An excluded finding remains visible with its recorded severity. It does not block the completed policy check. Any uncompleted required coverage, including not_checked, determines exit 2. Only complete or not_applicable satisfies required coverage.

The severity vocabulary is info, warning, and error. error is blocking. info and warning are advisory unless the underlying required Hugo build or its owning output check fails, in which case required work is incomplete. Informational completion and scope explanations belong in coverage details. Automation must use the result exit code and coverage, not only count severities.

When present, location contains file, with optional kind, line, and pointer. kind distinguishes source from output. A rendered finding points to the actual artifact and may include an element, attribute, or JSON location hint in pointer. This field does not always use RFC 6901 syntax. A line number is included only when known. A rendered link failure does not justify inventing a Markdown source line.

The CLI does not reject unknown valid front matter merely because a generated editor schema omits it. Configuration validity continues to follow Hugo and the owning theme resolver/checker. See the generated schema decision.

Coverage and exit semantics

Each coverage entry contains id, status, required (boolean), and detail. Entries describe the scope that actually ran. A report may contain several statements about the same broad area. Inspect all of them.

Status Meaning
complete The stated operation, inspection, or artifact-check scope completed
not_checked This run did not inspect the stated scope
not_applicable The stated check is unnecessary for these inputs
unsupported The stated contract or required input shape is unsupported
incomplete The stated work was required but could not finish
CLI exit code Meaning
0 Requested required work completed without blocking findings
1 Completed checks identified a policy violation, such as a broken local link or an unsafe requested write
2 Required work is incomplete, including argument, tool, build, I/O, cancellation, or required unsupported-contract failures

Incomplete work takes precedence over policy findings. Required coverage that has not completed cannot produce success. Only complete or not_applicable can satisfy it. Hugo build failure preserves the raw evidence and stops output acceptance. The CLI does not report stale or partial output as a passing check. Disabled optional machine outputs do not become missing-output errors.

The rendered-reference scope includes supported HTML URLs and anchors and supported emitted machine contracts. Coverage explicitly excludes browser interaction, accessibility, visual presentation, external URL availability, hosting redirects, and production deployment. It also identifies uninspected dynamic resources and content semantics. Static output checks inspect declared translation pairs and rendered files; browser execution and semantic translation review remain separate.

Hugo’s public Page.OutputFormats supplies expected artifact names and URLs per page and per enabled language. The isolated copy adds an unlisted probe with a unique per-run identifier. Each enabled language must emit its own verified manifest. Identified probe files are removed before artifact checks. Existing authored pages retain their output selections. Static content hidden from ordinary page lists is resolved through Hugo’s GetPage, without deriving its route or output filename from source syntax. Effective per-language base URLs and local-search settings accompany that enumeration. Enabled supported machine artifacts are checked against these exact expectations. Optional disabled outputs remain optional.

The same Hugo probe supplies data.pages through public Page.Path, Page.File, Page.Translations, Page.Aliases, and Page.OutputFormats. Facts retain language, actual URLs, publication settings, translation relationships and declared outputs. sourceKnown: false and sourceScope: "unknown" identify pages without proven source provenance. Generated sections do not receive invented source files. Site-owned known paths are relative to the selected site. Known copied dependency inputs have explicit dependency scope. These facts describe the production view. A separate internal analysis view can include drafts, future, and expired pages. It does not change production artifacts or claim publication of those pages.

data.references records observed HTML and machine-output references, their actual resolved URL, output file/pointer, local target when present, and anchor status when checked. It does not infer a Markdown source line. Page and reference data remain additive command evidence. They are not a public Go SDK.

Project check policy

An optional regular oink.yaml at the selected site’s root uses schema_version: oink.policy/v1. It owns check selection, severity overrides, reviewed finding exclusions, reviewed external URL scopes, translation scopes, protected prose declarations and the optional baseline file path. Hugo inputs continue to own languages, titles, URLs, menus, and configuration. Module files own dependency versions. A symlink, unknown key/group, unsupported version, invalid review metadata or multiple YAML documents is required input failure (exit 2). Diagnosis and checks only read this policy.

Without a policy, links, translations and style are enabled and required. check links, check translations, or check style explicitly selects one required group, regardless of its policy selection. Unselected or disabled optional groups report not_checked. Every check invocation retains the required Hugo build and diagnostics and output-enumeration prerequisites. Standalone translation/source checks also use an explicit nonpublishable draft/future/expired analysis view. It never replaces production artifacts. Managed build --check renders only the production view and returns 2 for unknown required scope identities.

The rules mapping assigns error, warning or info to exact opaque rule IDs. A reviewed exclusions entry requires rule_id, a clean relative file glob, reason, reviewed_by, and RFC 3339 reviewed_at. ** patterns and path escape forms are unsupported. Findings remain visible with review metadata. Site-local source locations match their relative site path. Source paths outside the selected site cannot match an exclusion. Required build, input, tool or coverage failure cannot become success through severity changes or exclusions.

Same-origin HTML references outside the configured base path are policy findings unless a reviewed external_scopes URL declares a separately deployed path scope. Each scope needs the same review metadata and an absolute HTTP(S) URL without credentials, query or fragment. Matching uses complete path segments. The scope cannot exempt missing targets inside the project or required local machine-output targets. Different-origin references remain explicitly unverified by offline static checks.

Translation policy and review evidence

translations.scopes selects source pages using clean absolute Hugo Page.Path prefixes, then finds targets through Hugo’s translation identity. It does not infer a public route or language from a filename. Each scope has path, source_language, required_languages, mode and drafts. mode defaults to localized. strict is also supported. drafts defaults to include. ignore excludes draft sources/targets. require-published requires the selected source and required targets in production. Known disabled Hugo languages are not_applicable. Unknown languages make the policy invalid. The most specific matching path owns a source page.

Without scopes, existing pairs rooted in Hugo’s enabled default language and duplicate relationships are inspected. Universal localization is not required. translations.coverage records the unconfigured language scope as optional not_checked. Missing required targets and duplicate selected relationships are policy findings. Draft/publication state is independent of review state.

Constraints require explicit selection. explicit_ids compares the full recognized explicit-ID map in strict mode. Localized mode requires a selected ids list. ids requires each named ID in both files, placeholders compares exact declared prose-literal counts, and code_labels protects fenced blocks with each named language/info token. required_fields requires nonempty dotted front matter fields in both files. equal_fields compares their actual values. No rule requires matching heading counts, translated prose or all code blocks by default.

.oink/translations.json uses oink.translations/v1. Explicit review records bind Hugo source/target IDs, source language, complete source/translation byte SHA-256 values, reviewer, reason, and RFC 3339 time. An absent record is unknown. Equal hashes are current. Source-only, target-only, or both changes are source_changed, translation_changed or both_changed. These states track byte changes since the recorded review rather than file modification times. Unproven sources stay unknown. If a recorded review or protected constraint cannot be verified, required work is incomplete.

Native content rules and coverage

Source rules extract evidence from Markdown structure and independent enabled Hugo attributes, preserving original UTF-8 bytes, CRLF/BOM, source offsets and YAML/TOML/JSON front matter with unknown fields. Actual effective Hugo attribute switches and configured math passthrough delimiters control recognition. Fenced/inline code, shortcode bodies, raw HTML and passthrough contents do not become prose or invented headings. Unsupported body syntax remains visible. Required source coverage cannot silently pass.

Generic rules detect duplicate recognized explicit IDs and evaluate declared style.protected entries with file, exact prose literal and expected count. The bounded OINK v1.1.0 and v1.2.0 catalogs add advisory code/table attribute, deprecated front matter and dropped unsafe-attribute findings. Each rule records module, version, immutable revision, module sum, license and exact source-file SHA-256 provenance in data.native_rule_provenance.

The catalog runs only when the actual mounted public v1.1.0 or v1.2.0 module-cache inputs match that release’s recorded hashes. Later releases need an explicit source audit before they gain native-rule coverage. A replacement, vendor copy, other version or unknown source does not select a latest-theme fallback. native-theme-rules is optional not_checked. Generic syntax checks still run.

Baselines and reviewed file plans

baseline selects a clean relative file, default .oink/baseline.json, using oink.baseline/v1. Capture requires completed work and explicit review metadata. The fingerprint binds exact rule ID, normalized location/pointer and condition message. It excludes severity. Acknowledged findings stay visible with disposition: "baseline" and their original severity. New conditions still block according to policy. Required incomplete findings/coverage cannot be acknowledged.

Review and capture preview oink.plan/v1 with selected edits, readable diffs, base existence/bytes/modes, after bytes and read guards. The plan ID excludes mutable validated/applied/recovery state. --plan FILE exclusively saves the plan. These commands do not accept --write. plans apply FILE --site DIR requires that exact selected site, fresh isolated candidate validation through the same checks and rechecked source guards before any write. Escapes, .git, symlinks, and nonregular files are protected. Overlapping candidate/source trees are refused. Stale plans fail safely. Optional external_inputs_hash binds captured non-site input bytes, full modes and inventory into the plan ID. This opaque SHA-256 grants no external paths or permission to read them. The owning validator compares fresh proven inputs. Trusted original external guards are rechecked around selected writes.

Exclusive installation preserves a file created during commit. Partial failures restore owned unchanged writes. Subsequent editor bytes, modes, or deletions remain intact. The reported recovery directory keeps original bytes/modes and actual concurrent captured evidence. Unrelated files and new editor children are preserved. No file content authorizes shell execution or publication.

Captured page inspection and impact

inspect PAGE selects an actual Hugo page by exact language:path ID, Hugo Path, permalink or proven site-owned source file. A known default language resolves a multilingual Path. Remaining ambiguity or an unknown selector is required incomplete (2). data.inspection exposes source byte hash/full mode, actual output identities, observed inbound/outbound references, translations and physical bundle attachments. Physical attachments are distinguished from observed published resources.

impact --since REF compares captured current inputs and an isolated committed Git tree rendered by the same Hugo engine. It retains deleted prior pages and their inbound edges, unchanged referring pages, translation peers, attachments and actual derived outputs. Global or uncertain inputs expand causal scope. An actual HTML output without proven ownership, such as an alias, also forces conservative full scope. Alias declarations never create guessed route ownership. Historical inputs in proven Git mode scopes compare only Git’s executable bit. Other module/foreign inputs and current facts retain full modes.

Historical materialization reads bounded Git objects without checkout hooks, filters, smudge execution or document execution. The limits are 10,000 files, 16 MiB per file, and 128 MiB per tree. Required private history is bounded at 256 MiB. Symlinks, submodules, capped or missing objects, required incomplete history and unsupported monorepo GitInfo are explicit incomplete states. Committed site-owned dependencies can be proven. Current external local replacement/workspace bytes cannot substitute for historical evidence.

data.impact.baseline_state is complete, incomplete or unavailable. When the required baseline is unavailable, the result returns 2, retains all known current pages/attachments/references/outputs and expands full scope. It creates no prior pages or invented changes. Only an actually resolved commit is recorded. check [GROUP] --since REF deliberately performs the full current check and declares data.check_scope: full so validation coverage stays complete. data.impact.full_scope describes causal uncertainty separately from that validation scope.

Completed inspect and impact fact queries return 0 even when their separately reported data.current_check has completed quality findings (1). Required capture failures remain top-level 2. check --since keeps the current policy’s quality exit code and required completion precedence.

context is removed. Read page facts through the JSON/YAML report from inspect.

Content move plans

move SOURCE TARGET [--plan FILE] previews a physical site-relative file or bundle relocation. Actual Hugo identities determine translation peers and old/new outputs. The plan includes byte/full-mode-preserved files and binary attachments, readable diffs, proven Markdown destination rewrites, observed route changes and alias advice. Front matter is not rewritten to install aliases. Raw HTML, shortcode output, transformed destinations and ambiguous source/output ownership remain visible as manual actions. Opaque source spans are not changed. Repeated ordinary Markdown destinations can also lack a unique source/output occurrence proof, including aggregate/print appearances. Matching URLs alone do not authorize rewriting those occurrences. A relocated physical attachment does not prove its new published URL. Resource URL changes require paired actual rendered edges and equal emitted bytes. A proven processed image URL does not prove an absolute original-resource URL. Unproven original URLs stay manual and are not constructed from the directory move.

The original before check and provisional route_probe are separate from the final candidate check. The provisional relocation may expose findings 1 from stale inbound links. A plan is validated or saved only after the final isolated candidate and reference proof pass. Unsupported identity or required capture failure returns 2. An actual final quality failure remains 1 and cannot save an applicable plan.

Content move plans must be saved outside the selected site. Their additive oink.plan/v1 move selectors and source_inputs_hash bind the complete raw source inventory, bytes, and full modes. External-input and fresh-directory guards also apply. Saved apply regenerates the original/relocated Hugo proof and requires exact expected plan ID and files before final reference verification. It rechecks current guards before writes, restores raw original modes rather than private-copy modes, and preserves later editor bytes/modes on refusal or guarded recovery. Stale inputs or an occupied fresh target lack the required proof and return 2. Only explicit plans apply writes selected files. Previews never stage or commit Git changes.

Supported input boundary

Initial full validation supports materialized files in a normal checkout or without Git metadata, including supported local module replacements copied into the isolated tree. It does not follow mounted symlinks or external mounts back into the user’s workspace. Auxiliary symlinks outside effective mounts are omitted rather than validated. Linked Git worktrees with a .git file need a materialized review copy. Git-dependent behavior needs a copy with its own Git metadata.

The snapshot excludes top-level public, resources, node_modules, tmp, and the Hugo build lock. A mount that needs excluded input cannot silently pass. Root configuration and the standard config tree are supported. Explicit configuration files must be inside the selected site. Custom HUGO_CONFIGDIR locations are refused. Supported configuration relocation is not a second implementation of Hugo validation.

Content adapters (_content.gotmpl) can create unlisted pages that cannot be enumerated completely through the supported public Hugo APIs. Full output validation therefore reports incomplete work for those inputs. A disabled page kind or render segment that omits an enabled language’s probe is also incomplete. Multihost language configuration is outside the first full-check scope and returns incomplete work. Multilingual paths on a single host remain supported. These cases must not be presented as a successful partial check.

Ordinary content plans

new BUNDLE --title TEXT [--language LANG] [--translations LANGS] [--kind page|docs|blog|book] [--plan FILE] previews an ordinary Hugo leaf bundle through captured site-owned content mounts. The primary language falls back to the effective default. Selected peers must be distinct enabled languages. Shared filename and language-directory layouts follow actual Hugo mounts, including observed sites.matrix.languages selection rather than an assumed legacy lang field. Ambiguous, filtered or unsupported mappings require manual authoring. Existing bundles or sibling files owning that page are refused.

The primary index has draft: false. Selected peer indexes have draft: true. The title is a supplied literal, not translated text. No review record is created. Full quality analysis and isolated candidate validation precede the shared guarded plan. Every proposed new file must map to exactly one actual site-owned Hugo source page with actual rendered outputs, including translation drafts in the explicit analysis view. Link-only/no-output, ignored, hidden or build-never content cannot pass merely because the existing site renders without errors. Required identity is checked even when ordinary source-check groups are disabled. Saving --plan creates only a new plan file. Explicit plans apply FILE --site DIR revalidates and checks source bytes/modes, existence, fresh directories and later attachment conflicts before applying. Fresh-directory state is bound into the plan identity and checked before/after validation, between writes and at completion. Rollback preserves later editor attachments and reports recovery. It does not delete unrelated directory entries.

Editor settings and Markdown snippets belong to the site editor. editor and snippets are removed.

Initialization profiles

init DIR [--profile project|docs|blog|book] [--languages en|en,zh|all] composes one embedded MIT-licensed Starter archive. The default project retains the previous complete language projection byte-for-byte. The language selection is independent of the content profile. all means English, Chinese and French.

Explicit docs, blog, and book retain their corresponding archived content section and shared home, assets, examples, workflows and license. Native section front matter defines their documentation, blog or sequential book model and navigation. Each language’s site title/description comes from its archived section. Existing localized home cards/actions/CTA are projected to that section. Only their generated hugo.yaml and data/home YAML files are serialized. Retained content/license bytes stay unchanged. There are no four copied Starter trees or runtime template downloads.

Unknown profiles are policy refusals (1) before candidate validation or writes. Missing/failed required Hugo validation remains incomplete (2). New and empty-target, candidate-before-publication, exclusive creation and concurrent-edit recovery protections apply to every profile. Ordinary Hugo builds each generated site with provisioned dependencies. Archived workflows remain source examples. init does not generate or execute the checksum-bound R3 CI templates.

Bounded upgrade comparison

upgrade --to TAG now captures baseline and candidate views from the same original site inputs and returns a readable module diff with full mode changes. Its comparison records actual Hugo pages/outputs/language settings, emitted file hashes/sizes/modes, raw alias declarations and separately observed alias redirect files. It reports removed/added URLs, proven redirects, alias target/ byte changes and enabled language/output/search changes.

A previous URL is preserved only when an observed redirect at its exact old output file targets the corresponding actual candidate page. Unknown/relative custom alias identity remains required incomplete (2). Removed previously emitted routes or outputs are blocking findings (1). Both resolved theme versions must match the explicitly selected pins. Unknown/substituted pins, unknown/different normalized Hugo versions or environments, or unexpected other input changes remain incomplete. Comparison supports one HTTP(S) base origin/path. Multihost inputs stay incomplete. Manual review remains explicit optional unchecked coverage. Observed aliases that retarget a different unique Hugo page are blocking independently of same-page URL moves.

The v2 upgrade plan ID binds the selected module plan, copied source bytes/full modes/file inventory and normalized actual comparison. --expect-plan ID checks a fresh capture/comparison, not a previously saved successful build. Because emitted file hashes are bound, nondeterministic templates can require a refreshed preview even when source files appear unchanged. Guards are rechecked before returning a preview, before each write and after writes, including proven local dependency/workspace inputs read-only. Only selected module files are written. Rollback restores only unchanged files owned by the operation and preserves later editor bytes. Existing dirty target, replacement and vendor safeguards remain in force.

File preservation and release checks

Initialization embeds the complete Starter commit and preserves its license. The provenance records its hash and every projection: independent content/language selection, the exact public theme pin/checksums, and disabling Git metadata for a fresh directory. The default project retains prior bytes. Selected content profiles share the same archived source and license. Candidate validation precedes target writes. Exclusive creation refuses existing files. Rollback removes only unchanged files created by that invocation and preserves concurrent user edits with recovery evidence.

Upgrade owns only a single site’s selected go.mod and go.sum changes. It preserves unrelated dependencies and directives, refuses dirty target files for --write, checks the reviewed plan ID when provided, rechecks targets before writing, and records backups/recovery. Unrelated dirty source files do not block read-only diagnosis or justify overwriting them.

check --release disables GOWORK and HUGO_MODULE_WORKSPACE and removes the environment replacement for the subprocess. It preserves go.mod replacements, reports conflicting local OINK replacement policy, and keeps vendor evidence separate from the public requirement. Upgrade refuses an OINK replacement and refuses _vendor. Vendor refresh remains a separate explicit workflow. No module pin change is described as updating vendor bytes. If Hugo actually selects vendored OINK, --release reports required public-source verification as incomplete (exit 2). Matching version metadata is not proof that the vendor bytes match the public tag. Ordinary check still validates the actual vendor build.

Configured Hugo module replacements are also disabled only in the release snapshot. If Hugo changes module files in that snapshot during resolution or build, the CLI reports that dependency inputs need explicit preparation and review. It preserves the original bytes rather than silently accepting a build that depended on an unreviewed generated module-file change.

Checked builds and artifact identity

build --check --destination DIR --manifest FILE uses an isolated, production build that keeps warnings visible for review. Hugo renders once. The check engines inspect that output, then seal and export those same bytes. It never invokes a second renderer to create the publication tree. The source checkout remains unchanged. Only an outcome of 0 with complete or inapplicable required coverage can be sealed. Blocked or incomplete checks do not create a verified export.

This production view does not include the separate nonpublishable maintenance render. An explicit scoped translation policy whose required Hugo identities are unknown because publication excludes their sources returns 2. It does not infer missing translations from filenames or silently skip the scope. Standalone check and translations retain the full maintenance view.

The destination must be new or empty, with an existing parent. The local manifest must be a new file outside that tree. Export uses exclusive creation, preserves exact bytes and full regular-file modes regardless of umask, and rechecks source and destination against the manifest. Existing entries, symlinks and overlapping trees are refused. Failed partial exports remain unverified evidence and are preserved. Empty directories and directory modes are outside the published file inventory.

--marker is optional and off by default. It adds .well-known/oink-build.json with only oink.build-marker/v1 and the artifact ID. That file’s entry is excluded from artifact-ID calculation to avoid a circular hash, then its exact digest is included in the final inventory. An existing marker path is refused. The manifest is never copied into the public tree automatically.

The separately saved oink.artifact/v1 manifest records the source-input hash, known source Git revision and dirty state, actual resolved theme identity, CLI/Hugo versions, effective environment/base URL/release settings, required coverage, actual Hugo route contexts and each file’s relative path, size, full mode and SHA-256. Canonical URLs and HTML language values come from emitted HTML. Hugo language keys remain separate. Unknown Git state stays unknown. Original input bytes and modes are captured before temporary probe overlays or workspace/replacement path rebasing. The public manifest omits absolute local paths, arbitrary arguments, process logs and free-form coverage details. Hashes record file byte identity.

Managed builds accept only the boolean Hugo flags --minify, --gc, --ignoreCache and --noTimes after --, including =true/=false forms. Other passthrough flags are unsupported inputs. Ordinary build keeps its existing transparent passthrough behavior. Effective example/local addresses are warnings during ordinary diagnosis and errors for checked release builds. --release still requires separate evidence for actual public theme resolution.

Local and deployed verification

artifacts verify --artifact DIR --manifest FILE is read-only and offline. It compares the exact file set, bytes, sizes and full modes. Changed, missing, additional, unsafe or mode-changed files invalidate identity (1). Invalid manifests, unreadable inputs and unsupported or interrupted inspection return 2. Verify the export again immediately before upload. Later edits cannot inherit a previous successful result.

verify --site URL --manifest FILE --network explicitly authorizes HTTP reads. It checks every declared file and distinct actual Hugo route URL, including all language/subpath contexts, against the manifest’s bounded response size and decoded-byte digest. Recorded HTML canonical/language values and an enabled marker are checked when available. Shared URL/file requests may be coalesced without removing their recorded contexts. HTTP cannot verify local file-mode bits.

A wrong body, soft-404, wrong route, changed captured canonical/language value or wrong marker is a conclusive finding (1). Timeouts, authentication failures, rate limiting, server unavailability and an absent required marker leave work incomplete (2). Redirects outside the selected origin/base path are blocked. The command does not discover or send credentials. Static build checks do not perform this deployment check. Network permission for a build does not authorize a later verification request or an upload.

Retired CI generation

ci init is removed. Keep CI configuration in the site or Starter. Previously saved CI plans are rejected by plans apply.

Explicit workspace registry

R6 supported local scope accepted

The registry and optional-tool boundaries passed frozen owning/runtime, actual protocol, four-consumer parity/preservation and canonical source/render gates. A07 adapter and A15 workspace supported scope is accepted locally in the maintenance record.

A workspace is one explicitly supplied YAML registry, independently versioned as oink.workspace/v1. It contains only site names and directories:

schema_version: oink.workspace/v1
sites:
  - name: docs
    directory: ../docs-site
  - name: blog
    directory: ../blog-site

The registry must be a regular nonsymlink file containing exactly one YAML document with known fields, 1–64 entries and at most 256 KiB. Names match [A-Za-z][A-Za-z0-9_-]{0,63} and are case sensitive. Directories are literal relative paths from the registry’s actual parent, or absolute paths. Variables, globs, and sibling discovery are not evaluated. Explicit directory symlinks and operating-system aliases resolve to their canonical identity. Duplicate names, duplicate or overlapping actual roots, filesystem roots, dangling symlinks and nondirectory ancestors are rejected. Missing directories with a proven existing ancestor remain listed. Checking one returns that site’s 2 without preventing later selected sites from being checked.

workspace list|check [GROUP] --workspace FILE [--sites NAME,NAME] selects all registered sites when --sites is omitted. Explicit selections require exact, nonempty, distinct registered names and retain registry order, including when the names were supplied in another order. list needs no Hugo renderer. check reuses the single-site engine and each site’s own Hugo inputs and oink.policy/v1 policy. It never duplicates Hugo configuration in the registry.

The existing oink.result/v1 envelope contains data.registry, selected_sites, sites: [{name, path, result}], completed_sites, finding_sites and incomplete_sites. Each child is a full single-site result. Completed sites include exits 0 and 1. Finding sites are the 1 subset. The aggregate exit is 2 if any selected site is incomplete, otherwise 1 if any has blocking findings, otherwise 0. Human output includes each site’s result and findings. This aggregation does not infer completion for unselected sites.

Supported single-site commands accept --workspace FILE --site NAME, with one explicit registered name and no default site. init, artifacts and verify do not accept this selection. A saved plans apply FILE must bind to the selected canonical directory. Selecting another registered site returns 2 before source writes. There is no automatic multi-site apply or upgrade. Existing candidate validation and source/dependency byte and mode guards still apply. Registry listing/checking neither provisions missing sites nor installs tools, commits or writes consumer configuration.

Optional check adapters

Explicit tools entries in each site’s oink.yaml select already provisioned executables. These entries extend oink.policy/v1. They are not a second Hugo configuration or an installer. Each kind has enabled (default true), required (default false), command (default the kind’s name), config (a clean site-relative regular file when supplied) and timeout_seconds (default 60 seconds, with bounded nondefault values 1–300). Commands are one executable name or absolute path, not shell expressions.

Kind Owning check group Current supported protocol Configuration boundary
markdownlint style markdownlint-cli 0.49.1 Optional declarative JSON/YAML/TOML; no JS, JSONC, custom rules or extends
vale style Vale 3.24.0 Explicit INI plus captured styles from the supported declarative subset
lychee links lychee 0.24.2 Optional bounded request settings; explicit network consent

Unconfigured tools are not discovered. A tool outside the selected check group is visibly not_checked. A configured optional tool that is unavailable, unsupported or cannot complete leaves an omission. Required incompletion returns 2 and cannot be downgraded by rule severity, exclusions or a problem baseline. Required and disabled cannot be combined. Completed typed findings still follow policy. Blocking findings return 1. An unrecognized tool version or invalid protocol output does not count as a completed check.

data.adapters records each kind, requirement, status, typed diagnostics, adapter.KIND coverage, raw process evidence, omissions and provenance. Provenance includes the observed supported version, executable SHA-256, captured configuration/style paths with SHA-256 and full mode, and pinned public protocol sources. Tool logs stay in stderr and evidence. JSON stdout remains one result. Per-process time and output are bounded, and changed executables, captured configurations or tool-modified private inputs invalidate their evidence.

Prose tools receive private masked copies of proven site-owned Markdown. Front matter, BOM/CRLF and UTF-8 offsets, code, shortcodes, raw HTML, configured math and attributes retain their source boundaries. Code prose is outside source attribution. Markdown structure and fence/inline code boundaries remain available to markdownlint. Vale receives the prose-only mask. Findings touching excluded or synthetic mask text are not attributed to original source. Source locations are emitted only for proven original lines/ranges. Unsupported syntax and suppressed findings remain visible omissions. These adapters do not format or rewrite original content.

Markdownlint uses an unpredictable generated JSON pointer to isolate the captured rule object after upstream rc merging. Executable configs, custom rule loaders and recursive extends are refused. Vale uses an explicit captured INI, --no-global, and copied declarative styles. Sync, packages, actions, scripts, conversions and style pipelines are unsupported. Lychee accepts bounded timeout, max_retries and max_concurrency settings, plus the literal cache = false. Caching remains disabled, and cache = true is refused. Preprocessors and arbitrary command options are refused.

Offline is the default. Lychee is not invoked, including its version probe, unless --network is explicit. Optional coverage is not_checked. Required coverage is incomplete 2. It receives only observed external HTTP(S) references from actual Hugo output. Local links remain the native check’s responsibility. Definitive failed 4xx responses are policy findings, except 401, 403, 408, 425 and 429; those, 5xx, DNS/TLS failures and timeouts are inconclusive, returning 2 when required and an omission when optional. External fragments, browser behavior and remote content identity are not verified. Findings retain the rendered output file and DOM pointer. No Markdown line is invented from an external URL.

Child processes do not receive caller proxy-URL/credential settings or Node preload variables. Literal NO_PROXY/no_proxy host-list data may be forwarded for the qualified runtime. Tool preparation and any network operation remain separate explicit actions. No tool is installed by these commands.

Offline and compatibility boundary

Offline is the default for managed subprocesses. Dependency misses are incomplete work. --network explicitly enables network use for the current operation. It conflicts with --offline. Isolated checks may seed disposable caches from already provisioned local modules. Downloading into a disposable cache does not promise a persistent cache for the next invocation.

Only module download artifacts are seeded. Isolated resource caches start fresh. The CLI does not reuse a global GetRemote cache to promise offline remote-resource builds. Required resources must be available as local inputs, or that operation must explicitly enable network access.

The CLI does not download a Go toolchain, install packages, alter global configuration, or enable telemetry.

The current development and validation baseline is Hugo Extended 0.168.0; the version gate requires 0.168.0 or newer. Do not enable --panicOnWarning or HUGO_PANICONWARNING; warnings stay visible, including Hugo’s accepted upstream LibSass notice. Initialized sites use the CLI’s separately maintained Starter snapshot; theme upgrades follow the upgrade guide. Initialized sites retain ordinary Hugo inputs and need only their documented dependencies after removing the CLI.

Retired local Studio

studio is removed from the CLI. Use an ordinary editor and oink dev for a site preview. Read maintenance facts through inspect and structured reports. The dated R7 acceptance remains historical evidence for its identified inputs.

Retired management API

The CLI no longer serves a management API. Earlier Studio API acceptance does not describe the current executable.

Historical capture limits

Historical R7 limits belong to the dated acceptance record. Current command coverage and supported inputs are defined in this contract.

Retired general editing

edit and Studio editing are removed. Edit source with an ordinary editor, then run check. new, move, review records, and baseline plans retain candidate validation and byte/mode guards. Previously saved editing plans are rejected. The dated R8 record remains historical evidence.

Retired text and field editing

The CLI no longer owns general text or front matter editing forms.

Retired snippets and attachment editing

Write Markdown and add attachments with the site editor. The CLI no longer provides a snippet catalog or general attachment editing command.

Retired Studio editing

The CLI does not serve an editor or accept browser Apply requests.

Verification and remaining scope

Use make test for offline Go tests and vet. Use make test-hugo for actual Hugo integration and make test-tools for configured optional tools.

Local integration gate rechecked on 2026-10-14

make test (offline Go tests and vet) and make test-hugo passed on macOS arm64 with Go 1.27.1 and Hugo Extended 0.166.0. The cold-cache configuration failure is fixed: both JSON readers accept leading hugo: collection notices, retain raw evidence, and reject unexpected prefixes or malformed JSON. A deterministic regression forces the notice on every configuration call. Native-rule checks also passed against the audited public v1.2.0 sources. Optional tool adapters require their separate make test-tools gate.

The dated maintenance acceptance record preserves earlier R1–R8 and A18 evidence. Declared targets are macOS arm64 and Linux arm64/amd64. Darwin amd64 is experimental and unqualified. Windows is unsupported.

6 - Component refinement across four visual presets

Consistent component surfaces and controls, with three optional Markdown presentation variants.
Accepted in OINK 1.4.0

Shared component styling and three optional presentation variants ship in 1.4.0. The component contract owns their behavior; the comparison guide shows them together.

Context

Cards, disclosures, Tabs and code controls had accumulated different spacing, borders and feedback treatments. A shared refinement keeps familiar authoring syntax while making related components feel consistent. The dated review records implementation and acceptance evidence, including the original staged plan.

Accepted style rules

Use the existing page, content and floating surface tokens. Independent cards have their own boundaries; grouped lists share a frame and internal dividers. Nested code and tables should not accumulate redundant borders.

Keep labels and hit targets fixed during press feedback. Reserve space for localized copy feedback, show success only after copying succeeds, and preserve visible failures. Keyboard focus is immediate; touch controls have usable hit areas. Reduced motion keeps state changes clear without travel.

Paper and Slate retain rounded surfaces. Ink keeps square, flat geometry; Terminal keeps compact, flat geometry. Paper’s decorative heading tails are removed. Ink and Terminal remain opt-in experiments; component refinement does not promote them to stable presets.

Optional authoring variants

The default grid, steps and code blocks remain available. Authors select a variant only when it suits the content.

Divided card list

- [Installation](/docs/start/) — Set up a local site.
- [Configuration](/docs/customize/config/) — Configure the site.
{.cards .td-cards-list}

This produces a single-column group with internal dividers. The full shortcode accepts cards variant="list". Item order, links and descriptions are preserved.

Compact command block

```bash {class="td-code-command"}
hugo server
```

A marked one-line command becomes a compact strip with a dedicated copy control. Multiline, numbered or collapsed blocks warn and retain regular presentation. Literal source and copied text are preserved.

Compact steps

1. Prepare configuration.
1. Run the local preview.
1. Review the generated page.
{.steps .td-steps-compact}

The full shortcode accepts steps variant="compact". Smaller markers and spacing suit short procedures while retaining numbering, nesting and anchors. Unsupported shortcode variants warn and use the default presentation.

Scope and compatibility

The same style rules cover tables, Fields, badges, Landing actions and shell rows. Existing renderers, clipboard behavior and tokens remain the owners. There is no new JavaScript dependency, font download, global density setting or external Sass executable. Native Markdown, no-JavaScript reading, Print and machine-readable outputs retain their content.

A moving selection background was evaluated but deferred. OINK 1.4.0 keeps static selection feedback. Any later motion trial needs its own acceptance.

Validation and delivery

Focused theme checks cover components, content primitives, code blocks, reading, shell, presets and namespace boundaries. The real site’s component presentation and appearance suites cover EN/ZH, light/dark, desktop/mobile, keyboard, touch, reduced motion and printing. The three variants and shared styling ship in 1.4.0.

7 - Paper and Slate visual presets

Accepted phase-one visual identity and appearance controls, with separate reader style and mode state.
OINK 1.2.0

Paper and Slate ship in 1.2.0. Ink and Terminal are included as explicit opt-ins; their remaining design work is recorded below.

Decision

Paper is the default, with warm paper/ink colors, blue links, IBM Plex Sans, heading hairlines and framed tables. Slate retains the v1.1.0 palette, Inter/Chakra/Plex Mono roles and Landing grid/glow. This gives reading sites a quieter default while preserving an explicit compatibility choice. The cost is a visible default change: existing sites can set params.ui.preset: slate. The 1.2.0 release notes and upgrade guide call out this default change.

The reader menu is opt-in (preset_menu: false). The docs site enables it. One Appearance disclosure combines native Style and Light radio groups; mobile uses a modal dialog in the browser top layer. It is reachable by touch and keyboard without relying on hover. The cost is replacing the old one-click mode toggle with a selection panel; the t shortcut still toggles mode.

Style and mode use separate attributes and storage keys. Choosing the site default preset clears the style key. Hugo renders the default without JavaScript; an allowlisted inline script restores reader state before CSS. This prevents the common initial preset mismatch, while keeping blocked storage usable. Presets ship in one stylesheet, at the cost of additional CSS bytes.

brand separates the wordmark from display headings. Paper adds the local OFL IBM Plex Sans variable font, including normal/italic and the six supported small writing-system subsets. Font files download on use; system typography and explicit role overrides retain priority. Chinese uses the system stack. Phase 1 includes no serif face and no external font request.

Page task determines density: Landing keeps display scale, long articles keep their reading measure, and navigation/configuration tables remain compact. No global spacing increase, new shell, or geometry abstraction is introduced. Giscus and print follow the preset; API vendors and charts retain their current mode-only behavior. This keeps the first implementation bounded.

Later work

On 2026-10-24, the maintainer accepted removing Paper’s trailing heading hairlines because the decoration adds visual clutter. The OINK 1.4.0 implementation removes the line in both light and dark mode while retaining heading typography and anchors. This revision ships in OINK 1.4.0; the 1.2.0 decision above records the original appearance.

A subsequent October 5 experiment implements Ink and Terminal behind explicit configuration; see the experiment record. They are not stable defaults. preset_menu: true offers Paper/Slate and the site default; an explicit list can expose either experiment. The menu uses the same compact icon-and-name buttons for all four, without experiment badges. This gives reviewers actual theme output without changing ordinary menu choices. The cost is additional scoped CSS and a larger menu when experiments are enabled.

The experiment uses owned component rules for square/2 px geometry and compact desktop navigation instead of introducing a global density framework. It reuses existing local fonts, state handling and accessibility controls. Charts and API vendors stay mode-only; comment palettes and print follow the experiments. Remaining work is visual acceptance, wider device review and any decision to promote them into the stable set.

Evidence

On 2026-10-25, the maintainer authorized component refinement using the existing four presets. Shared surfaces, grouped rows, stable labels, and background-only press feedback reuse current tokens and CSS. Markdown remains the primary authoring path; the three local presentation variants are explicit opt-ins. Paper/Slate keep rounded surfaces, while Ink/Terminal retain flat, square/2px geometry. The moving selection trial is deferred: static states provide the needed feedback without a second geometry or runtime layer. These changes ship in OINK 1.4.0; the component contract owns their supported syntax and fallback behavior.

The architecture contract and shell contract own behavior. check-presets.py owns token parity, AA palette checks, the frozen Slate v1.1.0 palette and strict configuration output. Font, parameter, vendor, namespace, action and runtime checkers retain their existing ownership. The documentation site’s appearance.spec.mjs tests real output; the dated acceptance record distinguishes executed checks from remaining experiments.

8 - Expo image collections

Record the reasons for album bundles, shared appearance, three display modes, and the image viewer.
Available in OINK 1.3.0

Expo is included in OINK v1.3.0.

The Expo contract defines required behavior. The authoring guide explains how to create an album.

Context

Docs organizes explanations. Blog organizes posts. Book organizes chapters. Expo organizes image collections into topics and albums. Readers need to scan an album, select an image, and inspect its details.

The Graph experiment used a separate copy of an existing collection. It contained 7,658 originals in 149 albums. The images included mixed dimensions, long images, GIFs, captions, and existing citation anchors. This collection supplied the initial content and scale requirements.

Decisions

One bundle per album

An album is one Hugo leaf bundle: index.md and image files. Filenames provide default titles. Optional resources metadata adds descriptions, credits, order, explicit IDs, and paths to separate originals.

Model considered Effect on authoring
One directory and metadata file per image Many small files to manage for a large collection
One Markdown page per image Useful when each image needs an article, but adds a page model to every image
One bundle per album with optional resource metadata An album can start with image files and one page; metadata can be added later

Expo uses the third model. The album owns the URL and reading sequence. Each image has a fragment anchor. Authors use explicit IDs for lasting citations. They split large collections into albums themselves. This version has no resource pagination or separate image database.

Shared appearance and compact controls

Expo is a layout. It uses the existing Paper, Slate, Ink, and Terminal presets and their light/dark modes. Shared colors, type styles, navigation, and corner settings keep the album consistent with the rest of the site.

Three adjacent radio cells expose all display choices: Wall, Cards, and Seamless. The play/pause button and size slider follow them. Icons keep the toolbar compact. Localized names, tooltips, and focus indicators make the controls usable with keyboards and assistive technology.

Reader display choices persist across albums and appearance changes. Appearance controls stay in the navigation. The image toolbar supplies album actions, so the album body omits the article action menu. The gallery fence remains the component for image groups inside text pages.

Animation and image viewing

GIFs play by default. Pause and the system’s reduced-motion preference provide still previews. Readers can start playback explicitly. Lazy loading reduces initial requests, but large GIFs still transfer the original files. Authors must consider album size when they group animated images.

The viewer starts at original size and shrinks large images to fit. Expand to fit uses the smaller width or height ratio. This rule keeps the whole image visible. Manual zoom, mouse dragging, and WASD movement let readers inspect details. Q/E and H/L move through the album. J/K control zoom, R resets, and F expands to fit. These shortcuts apply inside the viewer so they do not also move the page.

Original-file and album-location links preserve access and citation. A native modal dialog supplies focus containment. Expo loads its own album runtime only where needed. Ordinary Image Zoom keeps its existing single-image behavior. Without JavaScript, readers can still use the image links and captions.

Stable geometry and shared outputs

A width-consuming scrollbar changes the grid width. A new width can change the row count and total height. Near the viewport boundary, these changes can make the scrollbar appear and disappear repeatedly. This feedback caused the reported flicker even when the viewer was closed.

Expo reserves scrollbar space and preserves the grid width during modal scroll locking. The regression test forces a width-consuming scrollbar and samples successive frames. A single screenshot cannot detect this failure.

One image resolver supplies HTML, Print, Markdown, LLMSFULL, RSS, and album covers. This keeps image order and metadata consistent across outputs. Static formats remain usable without viewer JavaScript. Changes to the resolver require checks for each affected output.

Validation and ownership

The theme repository owns the resolver, layouts, runtime, schema, and focused checks. The documentation site owns the bilingual examples, browser tests, and desktop/mobile visual review. Acceptance includes all four presets, light/dark mode, keyboard input, focus, animation, and static outputs.

The copied Graph collection supplies additional evidence at a larger scale. Its original acceptance checked 7,658 file hashes, image anchors, and the unchanged source collection. Personal image data, generated output, and screenshots remain outside the theme and documentation source repositories.

Use the commands in the Expo contract for current acceptance.

9 - Blog posts as a gallery

Keep articles as the content model while reusing Expo geometry for a fourth blog index view.
Accepted in OINK 1.4.0

This decision records the released gallery blog view and its compatibility boundaries.

The shell contract defines the behavior. The design blog explains the reading experience, and the authoring guide gives configuration.

Context

Some blog sections are most easily scanned by their covers. The existing row, card, and table views prioritize article information. Expo already supplies image-wall geometry, but its album resources and image viewer have a different content model and destination.

Decisions

Gallery is a fourth blog_index form. It consumes the same paginator slice and featured-image resolver as the other blog views. Articles retain their URLs and metadata; authors do not duplicate them in an album manifest.

Share Expo’s row geometry and control styling. Keep the blog runtime and reader preferences separate, because a blog cover opens an article rather than an image viewer. The wall, cards, and seamless arrangements are choices within the gallery, while the outer view switch selects among the four blog forms.

Contain each cover within bounded tile proportions. This preserves the image at the cost of some blank space for extreme aspect ratios. Narrow layouts use tighter bounds so captions retain a readable width. Touch captions stay below the images and contribute to row height; keyboard focus reveals desktop captions. Missing covers keep an article link, and a no-JavaScript grid keeps titles and descriptions visible.

Consequences

An enabled view switch publishes markup for all four forms. Hidden views use lazy images, but preparing their thumbnails still costs build time. Authors can disable switching to emit only their chosen form. This change adds no remote image service or new browser library.

Native blog section indexes own the automatic integration. Custom home and term templates must explicitly render the gallery and its controls. A site configuration setting does not replace custom templates.

Verification and ownership

Theme checks in bin/check-shell.py compare article order, pagination, external links, missing covers, and invalid configuration fallbacks. The configuration schema follows the theme defaults and resolver. Runtime tests verify the four-form cycle and saved preferences.

The documentation site’s tests/browser/blog-gallery.spec.mjs owns browser acceptance with synthetic, bilingual content. It covers layout changes, resizing, independent preferences, keyboard navigation, touch captions, failed images, no-JavaScript output, and gallery accessibility.

10 - Explicit table reading

Separate technical table layout from an optional corner action for reading in a larger viewport.
Accepted in OINK 1.4.0

This decision records the released .expand table-reader behavior.

The component contract defines the behavior. The table guide gives author syntax; the dated research retains the earlier comparisons.

Context

Most documentation tables fit ordinary reading. A few package, parameter, or compatibility tables benefit from more room. A toolbar above every table adds visual weight to an occasional task. The reviewed prototypes compared a corner expand action and a hover-revealed ellipsis menu.

Decision

Use .expand to opt individual Markdown tables into a native reading dialog. .wide controls intrinsic table sizing independently; {.wide .expand} combines both. Do not infer expansion from size, column count, or .wide, and do not add a site-wide switch.

A single expand action needs one click. Place it at the top-right corner, revealing it on desktop hover or keyboard focus and keeping it visible on touch devices. The visible icon stays small; its touch target is at least 44px. Do not add an above-table toolbar or a one-item ellipsis menu.

Move the original table and its scroll wrapper into one modal dialog; preserve text size, native semantics, links, selection, and authored order. Restore that same node, inline scroll offsets, page position, and entry focus on close. Numbered captions supply the dialog title without duplicating IDs. Restore the table synchronously before browser printing. Without JavaScript or dialog support, readers retain the original inline table.

Boundaries

This delivery has no sorting, filtering, TSV export, density/wrapping switches, new column-pinning controls, virtualization, separate reading route, or Fullscreen API. Existing .matrix semantics remain available. Only theme-rendered Markdown tables opt in; .fields warns and ignores .expand. Tables with external headers or ARIA references stay inline because the modal makes their external targets inert. Custom ancestor-dependent styles need review when a table moves to the dialog.

The dialog inherits existing preset and light/dark tokens. Paper is the reviewed entrance design; other presets receive compatibility checks rather than new visual variants. Mobile reading still uses horizontal scrolling when the data is wider than the viewport.

Ownership and validation

The theme owns table rendering, the capability-gated runtime, localization, and scoped SCSS. bin/check-content-primitives.py covers opt-in, invalid combinations, localization, and static outputs. The documentation site’s tests/browser/table-reader.spec.mjs owns keyboard, touch, links, selection, focus/scroll restoration, printing, failures, and accessibility checks. Runtime checks and both site Make suites remain delivery gates.

The original draft is retired from active proposals and retained in Git history. The research describes dated experiments, including features intentionally excluded here.

11 - Translation comparison

Compare a page with an existing same-origin translation in a two-pane reader that loads only when asked.
Accepted in OINK 1.5.0

This decision records the released params.ui.compare translation reader.

The shell contract defines the reader and its controls. The architecture contract defines the browser boundary. The multilingual guide gives site setup; the dated research retains the earlier source review.

Context

Translated documentation is often read and reviewed side by side. Without built-in support, readers had to open two browser tabs and scroll each one manually. Generating a dedicated layout or prebuilt language-pair pages at build time would multiply the output tree and duplicate content. Because OINK sites already publish each translation as a standard HTML page with aligned heading IDs, a lightweight reader can pair those existing pages directly in the browser.

Decision

A single boolean parameter, params.ui.compare (default false), enables comparison. Hugo lists only published, same-origin HTML translations of Docs, Book, and blog pages. Drafts, non-HTML output formats, external hosts, and the language-home navigation fallback never qualify. Neither do translations whose build policy writes no HTML (build.render: link or never, set directly or by cascade), nor blog archive pages after the first, which have no counterpart. Any language that sets compare: false under languages.<lang>.params.ui is excluded as both a host page and a comparison target. Authors do not need to add front matter, custom layouts, or extra output formats.

The reader loads on demand: from an icon button beside the page actions, via the B keyboard shortcut when keyboard navigation is enabled (pressing it again closes the reader), or through the Command Palette action compare_translations. It opens two existing HTML pages inside same-origin frames within a modal dialog. The current page stays on the reading-start side, so right-to-left host pages mirror the pane order. Across the UI, the feature uses a single name: Duo View, with the trigger labelled Open duo view (it shipped in 1.5.0 as Bilingual View; see Revisions).

The Sync Scroll switch matches shared visible heading IDs and interpolates smoothly between them. Partial matches use the available anchors; when two pages share no headings, the reader falls back to overall document progress. An orange exclamation mark beside the switch explains either case. Matched headings that cannot scroll to the reading line do not count as a mismatch. Duplicate or out-of-order heading IDs disable synchronization while leaving both panes independently scrollable. Clicking Close, pressing Escape or B, or navigating Back restores the host page’s scroll position and focus. Reloading an open reader or returning to its history entry reopens the view in place so a single Back step still closes it.

On viewports narrower than 900 CSS pixels, the reader displays one retained pane at a time beneath a compact toolbar row and a language switcher bar (which also holds the target-language menu). At 320 × 256 CSS pixels (roughly 400% zoom), at least 160 CSS pixels of vertical reading space remain visible.

Pane documents suppress shell navigation runtimes, search, comments, and theme-managed analytics. When params.ui.compare is enabled, the theme renders Google Analytics through its own pane-aware template so pane loads are not counted as separate page views; a site’s local override of Hugo’s google_analytics.html partial is not used. Custom scripts in head hooks can check window.OinkComparePane.

Boundaries

This release does not include cross-version diffing, manual page-pair maps, paragraph-by-paragraph row locking, text diffs, or cross-origin targets. Panes require frame-src 'self' and same-origin framing: X-Frame-Options: DENY or frame-ancestors 'none' blocks frame loading and falls back to a direct link. While open, the host page and its two panes exist as three live documents; nothing extra is fetched until the reader opens.

Ownership and validation

The theme owns discovery, the lazy entry and reader runtimes, the 32 interface catalogs, and scoped SCSS. bin/check-compare.py covers discovery, Docs, Book and blog pages, the per-language opt-out, keyboard hints, analytics, output isolation, and how every runtime behaves inside a pane. tests/js/compare-scroll.test.js covers scroll geometry. The documentation site’s test:compare suite owns sync, lifecycle, reload, narrow and zoomed layouts, right-to-left order, eight languages, failures, and accessibility.

Revisions

  • v1.5.1 (2026-11-06): The interface name changed from Bilingual View to Duo View (Chinese 双列视图). The reader sets any two pages side by side, including same-language script pairs such as Simplified and Traditional Chinese, so a short name for the two-pane layout fits better than one about two languages; each locale uses its own concise equivalent. The entry, Command Palette action, title and help panel follow; the parameter and action ID are unchanged. B now toggles between the page and the reader, and scroll keys work as soon as it opens. The last chosen target language and Sync setting are remembered in the browser, and a reload or back/forward restore also brings back the visible pane and both reading positions. Sync Scroll became a switch. Its warning became an orange exclamation mark without a badge, with a note on hover, focus or tap that distinguishes a partial match from overall-progress sync. A matched heading that merely cannot reach the reading line no longer reports a mismatch; when no shared heading can anchor the map at all, the note says that sync follows overall reading progress.

The proposal draft is retired from active proposals and retained in Git history.

12 - Unified diagram reading

Shared Mermaid and local PlantUML viewing, source export and demand loading.
Accepted in OINK 1.4.0

Shared diagram viewing, source export and demand loading ship in 1.4.0. Components, Architecture and browser printing own the behavior.

Context

Before this change, Mermaid had a pan/zoom dialog but loads its engine at page startup and renders a second SVG for the dialog. Local PlantUML loads both engines at startup and offers only horizontal scrolling. Both preserve authored source.

Scope

Share the existing dialog and styles, source viewing/copy, and standalone SVG download. Defer large engines and rendering until a diagram is within 320px of the viewport. Do not change pinned libraries, server-mode PlantUML, other diagram families, the CLI, or ordinary consumers’ Hugo-only build requirements.

Behavior and boundaries

One lightweight scheduler serializes both engines on the main thread. Each engine loads once. Hidden or zero-width containers wait until visible. Theme changes invalidate old results; the open viewer retains its reading position. The viewer reuses a rendered snapshot, supports touch pan/pinch, wheel and keyboard controls, fit, Escape, focus restoration and reduced motion. Source is available even after an error. Copy and export report failure, and downloads report initiation only.

PlantUML stays in Blob images; its SVG is never inserted into the live DOM. SVG exports embed their styling, remove active content and reject external resource dependencies. No includes, themes or optional libraries are downloaded. Browser printing shows a rendered diagram or readable source synchronously; it cannot wait for an asynchronous engine in beforeprint. Dedicated Print, Markdown and RSS retain their existing source fallback.

Compatibility

No configuration or build step is added. Local PlantUML remains opt-in; explicit endpoints retain the legacy renderer. Without IntersectionObserver, bounded scroll/resize checks perform the same visibility test. Source survives disabled JavaScript and blocked assets.

Implementation and acceptance

Extract shared scheduling and viewing from assets/js/mermaid.js; retain engine adapters and the existing dialog partial. Update focused output checkers, runtime tests, real EN/ZH documentation and browser tests. Verify multiple and wide diagrams, hidden tabs/disclosures, rapid themes, errors, blocked resources, source fidelity, standalone exports, touch, keyboard, accessibility and printing. Compare requests before/after.

Decision log

  • 2026-10-25: Initial bounded design. Main-thread serialization and Blob isolation are retained. Immediate browser printing uses source for unrendered figures. Local implementation and focused browser acceptance are complete; broader site validation is recorded with the delivery evidence. This behavior ships in OINK 1.4.0.

13 - Local search refinement

Mixed-language queries, technical identifiers, section results, and palette scope in OINK 1.4.0.
Accepted in OINK 1.4.0

Owner: OINK maintainers. Affected contract: Shell. This search behavior ships in OINK 1.4.0.

Evidence and scope

The previous CJK path required one contiguous query in one field. English uses Lunr, and both return page links without section context. Preserve the one local index per language, existing commands, input-method composition, exclusions, keyword weights, and positive page boosts. No dictionary, service, account, external executable, configuration key, or extra build step is introduced.

Accepted behavior

Split whitespace and Latin/CJK boundaries while preserving technical identifiers such as shared_buffers, pg_basebackup, --baseURL, and /pg/data. Match terms across indexed fields. Return all-term pages first, with contiguous phrases ahead of other matches; only when no page covers every term show partial matches with visible coverage. Apply the page boost within those tiers. Keep English stemming and bounded spelling fallback through the bundled Lunr runtime.

One result per page selects its best matching section and excerpt. Read actual rendered heading IDs, never reconstruct a slug. Preserve language and base paths. Store body text once, with UTF-8 byte offsets for section boundaries. Heading and summary scopes keep heading anchors but do not silently index full bodies.

Add a labeled native radio group inside the existing palette, offering all pages or the current top-level content root. Default to all pages; commands and actions remain available. Announce result counts and partial coverage. Preserve keyboard selection, focus trapping, and deferred search during IME composition.

Compatibility and checks

Existing page metadata and scope configuration remain valid. Sections are additive index metadata; the engine continues to accept old indexes without sections. Theme owners: check-search.py, search-engine/runtime tests, and palette checks. Site owners: bilingual real-content query expectations, root/subpath anchor checks, and browser keyboard, composition, scope, responsive, light/dark, and axe checks. Compare old/new results and latency on identical real corpora. Record page and section counts, tool versions, warmup/repeats, and raw/gzip bytes. Every language must remain within 2 MiB raw and 512 KiB gzip. Synthetic cases cover ambiguous identifiers and duplicate, Unicode, explicit, and special-character heading IDs.

Decisions and acceptance

2026-10-25: Implemented locally after the initial design. The Shell contract and Search/Command palette guides now own the behavior. Theme checks exercise all four index scopes, actual UTF-8 section offsets, multilingual/subpath IDs, legacy index compatibility, boosts, and root-aware dialog caching. The site owns tests/search/queries.json and scripts/check-search-corpus.mjs; its summary query gate runs in root and subpath integration builds.

On the frozen documentation source ab2747a (149 pages and 1,321 headings per language), the 43-query set includes two negative summary cases. Top-five expected-page hits are EN summary 7/7 → 7/7, ZH summary 2/7 → 7/7, EN content 10/10 → 10/10, and ZH content 6/17 → 17/17. These are curated regression expectations, not general relevance scores. 连接池 超时 has no full match in this corpus and deliberately checks labeled partial results; a synthetic owner case checks the full match.

Frozen summary indexes are 185,183/184,281 bytes raw and 39,529/43,208 bytes gzip (EN/ZH), within budget. Full-content diagnostic indexes are 1,640,294/1,516,283 bytes raw and 536,971/578,674 bytes gzip, over the gzip budget. The maintained site retains summary scope; enabling all historical research text is not a budget-compliant configuration. The implementation never silently truncates it.

Browser acceptance covers EN/ZH, 390/1440 px, light/dark, real anchor navigation, visible/announced partial states, native scope selection, Blog/Book roots, composition and command retention. The artifact directory for this local run is /Users/vonng/tmp/oink-search-20261025/; it contains exact commands, JSON timings, logs and screenshots. These dated measurements describe that corpus; 1.4.0 includes the accepted behavior.

2026-10-26: Fixed cross-output contamination during index reads, added multi-output owner coverage, and completed the failed-route accessibility and file-tree retries.

2026-10-26: Refined the palette after visual review. The two scope choices are visible as compact segments with native radio keyboard behavior and 44 px hit areas. Reduced the desktop panel and row spacing, softened the selected result, and combined live status and keyboard hints into one footer.

2026-10-26: Adversarial review corrected normalized excerpt/highlight offsets, distinguished heading IDs from data attributes and script strings, and scoped English spelling fallback to the selected root. Regressions cover compatibility characters, combining marks, shortcode headings, and literal HTML in result text.