Skip to content

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

Return to the regular view of this page.

Design and development

OINK’s contracts, accepted decisions, dated research, and active proposals in one bilingual section.
OINK 1.5.1 contract

The contracts in this section describe OINK v1.5.1. Theme development uses the sibling checkout; release acceptance verifies the published module with replacements and workspaces disabled.

This section explains how OINK works and why it has its present shape. It brings together current contracts, the reasoning behind accepted decisions, evidence from alternative designs, and ideas that remain proposals. The other guides on this site explain how to build and maintain a site with OINK.

Reading this section

Layer Meaning
Contracts Normative behavior that compatible implementations must preserve
Decisions Accepted rationale and boundaries that explain current behavior
Research Dated, non-normative evidence that may need to be refreshed
Proposals Draft PRDs and RFCs; publication here is not proof of implementation

Contract map

Contract Authority
Architecture Build, configuration, diagnostics, localization, featured images, output, security, accessibility, and performance
Components Component API, Book and release primitives, validation, and output degradation
Shell and navigation Navigation, search, blog presentation, actions, taxonomies, and page-end composition
Landing pages Landing data, the 22-section registry, runtime, accessibility, and outputs
Migration boundary Supported 0.4-to-current content and configuration migrations

Design records

Collection Contents
Decisions Accepted diagnostic, configuration, authoring, Expo, and CLI rationale
Research Goldmark probes, consumer evidence, CLI acceptance, and October theme reviews
Proposals Active PRDs for knowledge graphs, media convergence, visual presets, and the CLI roadmap

Create each new OINK PRD or RFC as an English and Chinese page pair under content/docs/design/proposals/. Do not create another repository-local plan/, plans/, or proposal/ tree. After acceptance, update the implementation, its checker, and the applicable contract, then record the accepted rationale under Decisions. Retire the draft from active use while preserving it in Git history and the changelog.

Expo contract

The Expo contract describes the image-album layout introduced in OINK 1.3.0. Its accepted decision records the content model and the revisions to the earlier Muse experiment. The authoring guide explains album setup and viewer controls. The contract, accepted decision, and authoring guide describe the same released content model and controls.

Authority and maintenance

This directory owns the English and Chinese design text for maintainers; the theme repository owns the executable facts. Within the theme, hugo.yaml defines published defaults, while each resolver and checker defines the input shapes it accepts. layouts/ and assets/ define rendered behavior, and check scripts with tests/goldens/ define validation. VENDOR.json records bundled versions, licenses, files, and checksums.

When public behavior changes, update the implementation, its checker, and both language versions of the applicable contract in the same delivery. Tests should check behavior and output without requiring exact prose.

1 - Architecture contract

Repository assembly, configuration, diagnostics, localization, output, performance, security, CSS, accessibility, and release-state boundaries.
OINK 1.5.1 contract

This contract describes OINK v1.5.1.

Hugo toolchain

Use OINK v1.5.1 and Hugo Extended 0.168.0 for maintained sites, development, CI, and release validation. Keep this toolchain pinned.

Do not enable --panicOnWarning or HUGO_PANICONWARNING. Warnings remain visible and are reviewed. The upstream LibSass deprecation warning is accepted; it does not make a successful build fail. Invalid-input tests verify their specific warning and safe fallback output directly.

OINK uses Hugo’s built-in LibSass for main and ReDoc styles. Ordinary consumers need no Dart Sass or other Sass executable. Project-variable and project-style SCSS hooks remain supported. Future upgrades must preserve this dependency boundary. Update requirements, checkers, CI pins, and both language contracts together; historical release and research records retain their original tools.

The module requires Go 1.27.3, also pinned for development and CI. Go resolves Hugo Modules and is not needed for a prepared classic theme copy.

Repository and assembly

The repository root is a complete Hugo Module theme. It is not a site or npm workspace. Hugo Extended compiles SCSS and templates. Committed browser runtimes and third-party assets need no network fetch during normal builds. Public bilingual documentation, examples, and browser tests belong to the sibling oink.pgsty.com repository. The theme keeps only narrow internal regression fixtures under tests/site/. It has no separate public example site.

Generated public/ and resources/ directories are never source. Vendored runtimes, font families, and Font Awesome glyph definitions are supported distributions. Do not remove them as dead code. VENDOR.json and bin/check-vendor.py verify their integrity. OINK includes the complete supported Font Awesome distribution because consumer content can use icons absent from theme templates.

The official compiled Font Awesome CSS is a stable, fingerprinted vendor stylesheet. It loads before fingerprinted main.css, which is compiled from theme and consumer SCSS. Site style changes therefore preserve the icon distribution’s fingerprint, while cascade order still lets sites override its styles. Capability styles, including KaTeX, DocSearch, Swagger, and Asciinema, stay separate and load only when used. Fingerprints permit immutable URLs. The deployment host controls their HTTP cache headers.

Hugo types docs, book, blog, and swagger select reading shells. params.ui.shell_types may add types. Landing uses layout: landing. There is no article type or second blog shell. The shell contract defines immersive pages as a blog presentation.

layouts/_partials/shell/config.html resolves shared shell settings. Layouts must render through content/render.html before scripts.html because render hooks and shortcodes register capability flags in the Page Store. Override the narrowest partial. Keep similar base templates separate when merging them would change Hugo lookup precedence.

Configuration and diagnostics

Theme policy uses params.ui.*. Integrations with multiple settings, such as comments.giscus, plantuml, and drawio, remain top-level. Boolean features use bare booleans unless they have multiple settings. Page overrides omit the ui. prefix. Thus params.ui.image_zoom becomes image_zoom, never a front matter ui map. hugo.yaml declares published defaults. The owning resolver and checker define optional configuration shapes or ranges.

For invalid input, warn with the value, allowed shape, and safe fallback. Then apply the fallback or omit the unsafe feature. Ordinary builds and previews remain usable. The theme never calls errorf. check-params.py enforces this rule. Do not add speculative validation for unreachable states.

There is no generic registry of renamed keys. If a transition needs a migration diagnostic, add a targeted warning to its resolver and a negative test that verifies the warning and fallback. Never read removed keys as a compatibility path.

Network-capable features require explicit configuration and remain disabled when that configuration is invalid. OINK 1.4.0 renders PlantUML locally when it is enabled without an endpoint; an explicit plantuml.svg_image_url keeps server mode. Draw.io requires drawio.drawio_server. Algolia requires appId, apiKey, and indexName. Incomplete configuration warns and sends no request. Draw.io loads only if rendered content has PNG or SVG candidates. It inspects each distinct image URL once. Diagram endpoints must be strings with an HTTP(S) URL containing a host or a same-site path. Unsupported schemes, protocol-relative URLs, backslashes, whitespace, and same-site references without paths warn and disable the integration before runtime selection.

Self-contained PlantUML in OINK 1.4.0

plantuml: true or plantuml.enable: true without an endpoint selects browser rendering. The two pinned local assets (@plantuml/core 1.2026.9 and Viz.js 3.24.0) load only on HTML pages with PlantUML fences. Normal builds and readers need no Java, Graphviz executable, npm installation, CDN or rendering service. A nonempty endpoint still selects server mode and retains its validation and svg behavior; invalid endpoints do not fall through to local mode. No optional libraries, themes, include files or external resources are downloaded by local rendering. Generated SVG is displayed as a Blob image, never inserted into the page DOM. Failed input or loading keeps readable source; dedicated Print, Markdown and RSS keep source without a runtime. This behavior is part of the v1.4.0 release.

Fixed in OINK 1.3.0

Editor URLs retain their query parameters and fragments when embedding options are added. Messages must come from the active editor frame and its configured origin; unrelated or malformed messages are ignored. Diagram data is sent only to that origin. Exports must be PNG or SVG data URLs.

Lazy diagram loading in OINK 1.4.0

The small Mermaid/local-PlantUML scheduler appears only on HTML pages using these diagrams. Large engines load as visible diagrams approach the viewport. Engines are shared, with serial main-thread rendering; no Worker, dependency or build step is added. Scroll/size checks replace IntersectionObserver when unavailable. Ordinary browser printing cannot wait for asynchronous rendering: completed diagrams show images and the remainder retain source. Dedicated outputs are unchanged.

Interface localization

Available since OINK 1.1

OINK 1.1.0 expands the native interface catalogs to the complete locale set below. Consumer-authored content still needs its own translations.

OINK ships native interface catalogs for the 31 locale filenames present in google/docsy@64f51c5, plus generic zh as the Simplified Chinese default:

ar az bg bn de en es et fa fi fr he hi hu it ja ko nl no oc pl pt-br ro ru
sr-cyrl sr-latn sv tr uk zh-cn zh-tw

These catalogs cover theme UI strings; sites translate their own content. New Docsy locales do not enter OINK automatically: they need a complete OINK catalog and the same review as existing locales.

i18n/en.yaml defines the message schema. Each of the 32 OINK bundles has exactly these keys and native interface text. An English value may remain only as a reviewed product name, punctuation token, conventional abbreviation, or word shared by the target language. There are no generated English fallback blocks. zh and zh-cn use Simplified Chinese. zh-tw uses Traditional Chinese.

The current Hugo baseline accepts locale: zh for the generic zh language alongside regional Chinese catalogs. A site may also select locale: zh-CN. Neither choice changes the i18n/zh.yaml filename.

Runtime placeholders such as %s, {count}, and {{ .Count }} may move for natural grammar. Their bytes must stay identical. Values are strings or Hugo plural-message maps. Plural maps use supported locale categories: zero, one, two, few, many, and other. other is required. Each form must be a string with the same placeholders. Catalogs contain no hidden bidirectional controls. Arabic, Persian, and Hebrew direction comes from consumer language configuration (direction: rtl), not injected translation characters. bin/check-i18n.py checks locales, schema, value shapes, placeholders, directional controls, and the small reviewed set of English-identical terms. Translate every new visible string in every bundle in the same change. Do not generate fallback text.

Hugo’s images is the single authoring API. params.images supplies only the site-wide social fallback.

Source Reader thumbnail Social card
Page images, or bundled **featured*, *feature*, {*cover*,*thumbnail*} yes yes
Section cascade.images yes yes
Site params.images no yes

images: [] clears explicit or cascaded values but does not disable bundle resource discovery. Only the first resolved image represents the page. Local processable rasters may be cropped. SVG, static, and remote resources remain valid without Hugo image operations.

featured-image-resolve.html defines source priority and relative or absolute URLs. Explicit page images take precedence over bundle resources. Bundle resources take precedence over inherited cascade images. This order also applies when explicit and inherited values are identical. For file-backed pages, authored presence is read from source front matter. Hugo parses YAML, TOML, or JSON. For generated pages without source files, resolved images count as explicit. List thumbnails, Open Graph/Twitter/schema helpers, author avatars, Pinterest media, and blog presentation all use this decision.

params.ui.featured_image applies only to blogs and defaults to none. Page front matter or cascades can override it. banner adds a figure above single-page titles. wash colors the header. hero fills the shell background on single pages and section indexes. Missing images and non-HTML outputs render no image.

Outputs and runtime

Every base template sets Page.Store.tdOutputFormat:

Output Contract
HTML Complete semantic content; local runtime only for used capabilities
Print Expanded content; no shell navigation, search, or zoom runtime; the shared action layer supports explicit print controls
Markdown / LLMS Source-shaped Markdown without td- component markup
LLMSFULL Opt-in per top-level section: one llms-full.txt per enabled section per language, that same Markdown concatenated in reading order
RSS Safe static summary or explicit omission
NAVJSON Opt-in per site: one navigation.json per language, serializing the navigation authority the sidebar and pager already read
BookManifest Opt-in ordered JSON handoff for EPUB/PDF packaging tools

Output formats run in their defined order. A render keeps its mutable format state stable for the whole output; summary helpers do not restore an earlier format value into an RSS render. Within Print, Hugo can render Book pages and overlapping aggregates in parallel. A cached coordinator for each page creates plain and Book variants in a fixed order. Each caller selects its required form. Plain Print keeps page-local headings and routed xref URLs. Book aggregates keep namespaced headings and in-document xrefs. Relative content links resolve against each source page’s HTML URL before its body moves into Print. This preserves language and deployment prefixes, query strings, and encoded paths in both single-page and aggregate output. Only actual href attributes are rewritten; matching text in title or other non-link attributes is preserved. Fragment-only links remain local for heading and footnote namespacing; canonical and external links keep their destinations. Heading fragments are percent-decoded once for namespace lookup, including Unicode and encoded ASCII. Literal plus signs remain plus signs; malformed escapes remain unchanged. HTML entities in IDs and attributes are decoded separately. The path, query, and external origin are never changed by fragment normalization. Rendered Markdown headings inside Tabs and other Markdown shortcodes receive the same namespace, even when Hugo omits them from Page.Fragments. Their rendered heading IDs own the identity, preserving Chinese text, literal plus signs, and percent sequences without deriving IDs from escaped self-link URLs.

Configured RSS output on a Landing page generates a static feed through the shared RSS renderer. An advertised alternate output must have a generated file; omitting interactive Landing components does not omit the feed itself.

Print is a browser-readable document before it is sent to paper. On screen, wide tables stay inside labelled, keyboard-focusable scroll regions without widening the page. Print-media CSS expands these regions for printing. This requires no table runtime; RSS tables remain non-focusable static content.

Consumers opt into custom outputs. OINK does not force expensive Book aggregates. HTML loads shared action and core layers, plus stable first-party capability chunks selected by page flags. Templated capabilities publish at most one chunk per language. Flags select script tags and never create bundles for feature combinations. Print keeps the action layer and only runtimes needed by rendered print features. Large third-party UMD files stay separate. Unused feature runtimes remain absent.

A top-level section enables LLMSFULL by listing it in its _index front matter outputs. The theme never adds it to site outputs. One renderer creates per-page Markdown and the bundle. The bundle concatenates the same semantic Markdown, without td- component markup, in sidebar and pager reading order. Enabling it below the top level warns and emits nothing. Builds remain usable; the warning and absence of the disabled output are checked directly.

Site outputs.home enables NAVJSON. It publishes one navigation.json per language at the language root. It uses the sidebar and pager authority: explicit data/docs_nav.json when present, or the weighted content tree otherwise. Array order is the contract. weight is never serialized. The output is notAlternative. The manually maintained schema/nav.v1.schema.json versions the format. Edit it with its templates and checker. It is outside the generated configuration schema drift gate. Both outputs default off. Sites that enable neither build byte-identically. bin/check-agent-indexes.py owns their checks.

BookManifest is disabled unless a Book root explicitly lists it in outputs. It references existing per-page Markdown and records derived page order, headings, numbered targets, and xrefs. The theme guesses no publication metadata.

The theme repository provides bin/book-epub.py and bin/book-pdf.py for explicit publication steps. bin/check-book-epub.py and bin/check-book-pdf.py validate their artifacts. The EPUB packager combines BookManifest with whole-Book Print HTML and accepts consumer metadata separately. The PDF runner serves Print output at a temporary loopback address. It invokes an explicit Chrome/Chromium binary with script-src 'none' CSP. It produces A4 pages with CSS page numbers. The PDF server also applies a CSP sandbox, rejects meta-refresh navigation, and refuses symlinks outside the build tree. Without network opt-in, image and media requests allow only the loopback origin and data URLs. This includes requests from CSS or SVG. Both tools refuse missing resources and resources outside the build tree. Network resources and output replacement each need a separate explicit flag. Network opt-in permits only passive HTTP(S) media. Remote scripts and local-file schemes remain invalid. Relative EPUB metadata assets resolve from the metadata file’s directory, not the working directory. Ordinary Hugo builds run no publication steps. PDF remains derived from Print, rather than a separate template output.

Performance rules:

  • Do not walk .Site.Pages for every page if a site-level resource or partialCached result can perform the work.
  • Render .Content once. Read Page Store flags only after rendering it.
  • Emit correct markup. Do not scan the DOM to repair it.
  • Group browser work by resource URL, not DOM instance.
  • Keep ordinary outputs opt-in when their aggregate cost is material.
  • Emit no Speculation Rules by default. First, a named production consumer must measure Sec-Purpose: prefetch requests, useful navigations, bytes, and CSP impact. Use a reversible moderate experiment.
  • Validate reachable author input. Do not validate hypothetical internal states.

bin/measure-baseline.py measures build time, output weight, bundle count, and shortcode density.

Single-page Print emits the page description once. Section Print carries mathematics capability from every included descendant to the aggregate root, so a formula-free index still loads local KaTeX styles when a child needs them. Formula-free Print documents do not load those styles.

Trust, CSS, and accessibility

Authors may enable Goldmark unsafe. Configuration and component parameters are not raw HTML. The shared attribute policy uses an allowlist, validates class tokens, and passes data-* and aria-*. It warns and removes style, srcdoc, on*, reserved attributes, and unknown attributes. URL helpers reject dangerous schemes and protocol-relative URLs where local or explicit absolute URLs are required. Promised remote URLs remain supported. They are never fetched at build time.

Fixed in OINK 1.3.0

Image and Gallery URLs are HTML-attribute escaped after URL validation, including full-size Zoom sources. Quotes and ampersands remain part of the URL; they cannot introduce attributes or be decoded as HTML entities.

Theme output uses td- classes, data-td-* attributes, and --td-* custom properties. Author markers such as .steps, .cards, .full-width, .wide, and .expand remain unprefixed. CSS supports RTL, print, forced colors, reduced motion, long tokens, and narrow viewports. Theme decorative icons have aria-hidden. Only pages with task lists or raw authored Font Awesome elements load the authored accessibility repair.

Reading-container focus distinguishes pointer input from keyboard navigation. A pointer-focused main region, table viewport, or code pre does not gain an outline merely when another key is pressed. Tab, blur, or new non-pointer focus clears that exception. Controls keep their focus styles. Scrollable containers keep tabindex. The skip-link destination shows a local outline around its title instead of the whole article. Forced colors retain keyboard focus indication. No global focus-outline reset is used.

Font roles are ui, body, heading, code, display, meta, brand, and print. They use --td-*-font-family properties. ui is the primary face, with body resolving through it and heading through body, so one assignment changes interface text, prose, and headings together. params.ui.typography accepts technical or system. Both compile into one stylesheet and need no runtime. Legacy Bootstrap/Docsy Sass variables still initialize these roles.

params.ui.fonts configures the same roles without mounted SCSS or an added stylesheet. It names faces without loading them, so readers must have the family or the site must declare it through its own @font-face. This key remains outside the network contract. Values must use plain font-family syntax. The emitted :root block is reconstructed from matched parts. Unknown roles or unsafe values warn and are individually removed. The block follows the stylesheet, allowing authored faces to override presets at equal specificity. Shells inherit site faces and define none of their own. Book numbers and captions use the prose face, not a technical face.

Accent roles are separate. Accent text, including links, external URLs, and inline code, uses the Bootstrap link family and --bs-code-color. Theme colors never redeclare these properties. Inline code follows the visual preset: Slate keeps the crimson pair; Paper uses ink text on a quiet chip. Accent backgrounds include selected rows, gray pointer-hover navigation backgrounds, hover washes, outline pills, rails, dots, chip hovers, and hovered card borders. They also include share-button hover fills, selections, and focus rings. These use --td-accent, --td-accent-rgb, and --td-accent-hover, which default to the link family. These are the only properties emitted by params.ui.theme_color. Shell text uses them too: active outline anchors and Book chapter headings under pointer or keyboard focus use the section color, not link blue. theme_color and theme_color_dark accept #rgb/#rrggbb. Page front matter and section cascades override site values. Unconfigured sites emit nothing. Unparseable values warn and keep the default palette. Resolved colors below 4.5:1 against the theme canvas warn with a suppressible ID but are still emitted. This check uses the site default preset canvas and is advisory. Only parse failures remove colors. The light color is required. theme_color_dark without valid theme_color warns and is ignored. A page therefore receives color in both modes or neither. If dark color is omitted, the theme lightens toward white in 4% steps until it reaches 4.5:1 on the dark canvas. Every emitted byte is formatted from parsed integer channels, never author text. One resolver supplies page colors to both the head block and sidebar root switcher.

Visual presets

OINK 1.2.0 defaults to Paper. params.ui.preset accepts paper, slate, and the explicit experimental presets ink, terminal. Invalid and reserved names (folio, canvas) warn and fall back to paper. params.ui.preset_menu defaults to false; true offers Paper, Slate and the site default. A list selects available choices, including experiments. A list must include the site default; missing it warns and adds it. There is no page-level preset override.

Hugo renders data-td-preset and data-td-site-preset on every document root, including 404 and print output. With reader choice enabled, an inline head script validates td-preset before CSS loads. Selecting the default removes that storage key. Invalid saved values are removed; blocked storage leaves in-page controls usable and shows a non-persistence note. The storage event synchronizes tabs. td-preset-change carries {preset, previous, stored}. Mode remains independent: data-bs-theme, td-color-theme, and td-theme-change retain their meaning. The browser chrome color follows the resolved mode and preset. Without JavaScript, the site default light palette renders; appearance controls require JavaScript.

All four presets compile into one stylesheet. Slate retains the v1.1.0 base palette selectors and values. Paper changes palette and selected component rules without changing shell columns, breakpoints, or global spacing. Dark Paper redeclares every light palette token, including nested dark islands. Font roles have equal selector specificity: preset, then typography: system, then head-emitted params.ui.fonts. Site _styles_project.scss remains last. brand controls the wordmark independently from display headings. Paper uses local IBM Plex Sans; Slate keeps Inter; both retain Chakra Petch for the wordmark and IBM Plex Mono for code. System typography requests no bundled text face unless the site explicitly overrides a role. No external font is introduced. Ink uses Inter throughout, with red markers, underlined prose links, square geometry and no shadows. Terminal uses mono chrome/headings, Plex Sans prose, teal links, amber accents, 2 px corners and no shadows. Its navigation density changes only on desktop; prose measure and mobile targets remain unchanged. CSS heading marks have empty accessible alternatives and are omitted in unsupported browsers. Explicit fonts.ui still supplies the main face unless a valid fonts.body overrides it. See the experiment record.

Paper section headings in OINK 1.4.0

Paper no longer draws a decorative line to the right of content h2 headings, in either light or dark mode. Heading typography, spacing, anchors, and normal wrapping are preserved. Site-authored heading borders remain supported.

Giscus auto palettes follow both dimensions; explicit Giscus theme or light/dark stylesheet overrides remain authoritative. Print uses a light preset palette on white paper even when the screen is dark. Mermaid and ECharts continue to follow mode only; API widgets retain vendor palettes. See the accepted decision and local acceptance record.

Translation reader runtime

The sole setting is the boolean params.ui.compare, default false; a language may override it. Invalid values warn and leave it off. Hugo derives candidates from actual translation pages whose language also enables comparison, and emits a small descriptor. The entry chunk loads the reader on demand; the reader uses two same-origin HTML frames. No language combinations or new content outputs are generated. The retained host makes three live documents. Per-viewer preferences (last target and Sync) live in localStorage under td-compare-reader, read and written inside try/catch; the restorable session (target, Sync, visible pane, semantic bookmarks) lives in history.state.oinkCompareSession on the reader entry only.

oink_compare_pane=1 activates the internal pane state only in a frame owned by an open reader. Visiting that URL at top level leaves the normal page intact. window.OinkComparePane is available before head hooks for custom scripts. Pane state suppresses shell runtimes and shortcuts, search initialization, comments and theme-managed analytics, while keeping content runtimes and styles. bin/check-compare.py classifies every browser runtime as suppressed in panes, running in panes, or host-only, so a new runtime must declare its pane behavior. With comparison on, production builds render Google Analytics through the theme’s pane-aware template instead of Hugo’s embedded partial; a site override of google_analytics.html therefore does not apply. Frames isolate document IDs; same-origin content remains trusted site content. Panes need frame-src 'self' and same-origin framing. Normal canonical links remain the page identity. Print and machine outputs contain no comparison controls or comparison runtime.

A pane is ready when its bootstrap reports DOMContentLoaded, not when every image or embed has loaded; a slow resource never holds back or discards a readable pane. An invalid document fails at its load event or the 15-second document timeout. The iframe’s initial about:blank load is ignored, but a document still blank at timeout fails. Browser geometry is measured at readiness and invalidated on resize, the frame load event, font/image readiness and disclosure/component layout changes (including td:tab-shown). User input assigns the active pane; programmatic follower scrolls cannot take ownership. Animation frames coalesce updates. Continuous owner scrolling is mirrored instantly per frame, because restarting an eased scroll on every frame stalls the follower; a single discrete jump eases when motion is allowed, and reduced-motion or bookmark restoration uses instant positioning. Closing or replacing a pane aborts its listeners, observers and load timeout. Native dialog inertness contains host focus; child keyboard handling preserves nested component dialogs. The reader’s history entry survives a reload or a back/forward restore. The entry runtime binds restoration to that entry’s token and verifies it again after loading the reader; leaving the entry cancels the pending restore. Reopening preserves the token and does not write history. History traversal finishes processing an explicit close or queued user reopen before automatic restoration runs. Moving the language menu across the narrow breakpoint preserves its focused control and open state after updating pane visibility and inertness.

Release states

Keep local validation, module tagging, consumer pin updates, and site deployment distinct during release workflows.

v1.5.1 review corrections

The v1.5.1 release retains Hugo Extended 0.168.0 and Go 1.27.3. Validation reports must identify the actual toolchain and local module source.

Feeds sort by descending date before applying services.rss.limit, and undated items omit pubDate. RSS summaries and page feeds can share a page Store within the RSS pass. Summary rendering keeps that Store in RSS format state instead of restoring stale HTML state, and preserves manual summary dividers.

Focus indicators use the current preset’s opaque link color. Navbar controls and clipped code/FAQ containers retain visible keyboard focus. Forced colors expose current navigation entries and the footer wordmark. Heading and field self-links remain keyboard-reachable; print links retain their underlines. The local Bootstrap RTL artifact supplies directional rules without replacing the theme’s font roles. Prose list spacing does not apply to component lists.

The configuration schema accepts translation_notice as false or a nonempty language-code string; the owning resolver checks that the language exists. Pagination and breadcrumb labels are translated in all 32 locales. Thumbnail alternative text uses the page title without an English prefix.

2 - Component contract

The maintainer contract for OINK authoring primitives, validation, Book and release behavior, and output degradation.
OINK 1.5.1 contract

This contract describes OINK v1.5.1.

The reader-facing Components section provides tutorials and complete examples. This page defines the API and behavior used by those guides.

Authoring model

Use ordinary Markdown when one block with attributes can express the component. Use shortcodes for compound bodies or information that Markdown cannot represent. There is no parallel component registry. Native forms require:

markup:
  goldmark:
    renderer: { unsafe: true }
    parser:
      wrapStandAloneImageWithinParagraph: false
      attribute: { block: true }

Only {{%/* steps */%}} uses percent delimiters because its body belongs to the page outline. Other shortcodes use angle delimiters. Compound bodies use content/render-block.html with a unique ID scope. Shortcode and component captions, labels, titles, and names are plain text. Put Markdown in bodies. Landing narrative fields have their own contract. Icons use one Font Awesome class pair. Components expose safe classes and attributes. They do not expose arbitrary colors or inline styles.

Public API

OINK has 29 shortcodes:

  • core: tabs, tab, steps, cards, card, fields, field, include, kbd, badge, param, comment, contributors, asciinema;
  • Book: fig, tbl, eq, eg, xref, book-toc, book-figures, book-tables, book-equations, book-examples;
  • release: release-card, release-assets, download;
  • OpenAPI: swagger, redoc.
Component Native form Shortcode form HTML runtime
Callout > [!TYPE], fold, {icon=} none none
Tabs adjacent fences/tables with {tab= group= value=} tabs / tab tabs on used pages
Steps ordered list + {.steps} steps none
Cards link list + {.cards} cards / card none
Fields table + {.fields} fields / field none
FileTree filetree data fence none divider only with comments
Gallery gallery data fence none shared Image Zoom when eligible
Image Markdown image + block attributes none Image Zoom when eligible
Table attributes, caption, number, or tabs tbl for compound Book tables tabs when tabbed; reader with .expand
Book target image/table/passthrough/fence + {num=} fig, tbl, eq, eg none
Release assets checksums data fence release-assets copy in HTML
Math and chemistry passthrough, math, chem fences eq none; build-time rendering and local styles
Diagram/data mermaid, plantuml, markmap, echarts, infographic fences none selected local runtime only
Unified diagram reading in OINK 1.4.0

Mermaid and local PlantUML share pan/zoom, fit, source viewing/copy and standalone SVG download. Engines load and render only for measurable diagrams within 320px of the viewport. Each engine loads once; both render serially on the main thread. Hidden content waits until revealed, and obsolete theme results are discarded. The viewer reuses rendered results, retains reading position, and supports touch, keyboard, focus restoration and reduced motion. PlantUML retains Blob-image isolation: its SVG markup never enters the live DOM. Source is escaped exactly once, preserving arrows, quotes, ampersands and Chinese. Errors keep source without blocking subsequent diagrams. Copy/export failures show feedback; downloads report initiation only. Exports embed styling and reject external resource dependencies. Ordinary browser printing keeps light Mermaid and PlantUML pictures; dark Mermaid and unfinished diagrams use black-on-white wrapped source, ready without asynchronous print-time rendering. Source disclosures return to their reading state after printing; rendered results and preferences are preserved. Dedicated Print, Markdown and RSS retain source fallback. See Mermaid and PlantUML. Explicit server mode retains its existing behavior.

Optional component presentation

OINK 1.4.0 supports the following opt-in presentation variants. See the presentation examples.

Component Native modifier Full form
Divided card list {.cards .td-cards-list} cards variant="list"
Compact steps {.steps .td-steps-compact} steps variant="compact", with percent delimiters
Command strip A one-line fence with {class="td-code-command"} Existing code renderer; no new shortcode

Unrecognized variant values warn and fall back to the default layout. A command strip with multiple lines, line numbers (including site defaults), or collapse warns and uses the regular block, preserving every source line. Existing copy and wrap policies still apply. No new runtime or component registry is introduced.

Native and full cards share surface and title rules. Only cards with links receive hover emphasis; secondary body links remain operable above a stretched title link. Tabs have transparent individual backgrounds at rest, a subtle hover fill on hover-capable devices, and a thin underline plus link color for selection. Labels keep the same weight and position between states; keyboard focus remains a distinct outline. Native disclosures retain an independently operable summary. Copy controls preserve their target geometry and existing success/error semantics. Coarse-pointer copy and tab controls have at least 44px height.

Preset colors and font roles remain authoritative. Ink/Terminal keep flat surfaces and square/2px geometry. Print, RSS, Markdown, and LLMS keep the content and their existing output semantics; presentation adds no hidden content or extra controls to static output.

Field names use unboxed, emphasized monospace text in all four presets, including Terminal, for both Markdown tables and full shortcodes.

Validation

Invalid author input follows the architecture contract. Warn, then use the documented safe fallback or omit the component. Do not combine named and positional forms. Book target IDs match [A-Za-z][A-Za-z0-9_.:-]*. Book numbers match [0-9A-Za-z.-]+. Classes use token validation. Hooks and shortcodes share one page target registry so collisions cannot produce duplicate output IDs.

URLs use content/url.html. Raw backslashes are invalid because browsers can interpret them as URL separators. Images resolve through page resources, section resources, global assets, then static or explicit remote URLs. Local rasters include intrinsic dimensions. SVG, static, and remote sources remain valid but cannot use Hugo image operations. Resource metadata alt must be a string. Invalid values warn and are ignored, preserving authored alt text.

Empty tabs warn and emit no container in HTML, Print, Markdown, or RSS. An xref without a usable target or with a missing target page preserves its text without a link. If fig supplies both caption and title, the warning and all outputs prefer caption. Generic attributes on block mathematics do not enable Book numbering. Without num, id and caption warn and are ignored; the formula stays unnumbered.

Component behavior

Callouts and tabs

Callout types are note, tip, important, warning, caution, success, danger, question, example, quote, and details. - makes the callout initially collapsed. + makes it expanded. Unknown types render as plain blockquotes, with their markers preserved and no JS.

Adjacent tabs group only when consecutive and of the same block kind. group enables the hash #<group>-<value> and storage td-tabs:v1:<group>. Ungrouped tabs use neither. In OINK 1.4.0, an initial fragment or hashchange targeting a panel or a heading within it opens all ancestor panels from outside in before scrolling to the target. Hash selection takes priority over saved preferences and synchronizes named peers, but does not overwrite storage. Only explicit reader selection persists; ordinary headings outside tabs retain native navigation. HTML exposes all panels before JS. Print expands them. Markdown keeps authored source. RSS provides the rendered text summary. Grouped tab IDs and local links remain unchanged in HTML and single-page Print. Repeated groups and nested tab containers keep unique IDs within each page. Multi-page section and whole-Book Print prefix generated tab container and panel IDs with the source page namespace and update their local links. Reusing a group across chapters must not send a tab link to another chapter. Cross-page links to ordinary HTML keep their destination. Fragment rewriting accepts normal HTML attribute syntax and preserves text inside other attributes. The full form supports arbitrary Markdown. tab.label is required. value is required exactly when the parent has group. Orphan tab shortcodes warn and render nothing.

Steps, cards, fields, and tables

Native steps accept ordinary block content. Use shortcodes only when steps must contain percent-delimited containers. Native cards use link lists. The full form adds bodies, badges, icons, and images. Native fields use the first column for names, the last for descriptions, and middle columns for metadata through meta= or headings. The full form accepts block descriptions. Use card and field only within their parents.

Field anchors use field-<name>, with lowercase punctuation runs replaced by hyphens. Thus params.ui.typography becomes field-params-ui-typography. Duplicate anchors get positional suffixes.

The table hook owns responsive wrapping and captions. Captions have balanced inset spacing inside the frame, aligned with cell text; an available corner action reserves space at the end of the inline caption. .matrix makes the first column row headers; .full-width widens the outer wrapper to the article width. On screens, .wide opts technical tables into intrinsic sizing inside that scrollable wrapper, preserving identifiers with overflow-wrap: break-word and word-break: normal. Body cells have a soft max-width: 40ch bound so prose wraps. Ordinary tables retain their existing layout. The modifier has no effect on .fields, which renders a definition list, or on static and print output. .fields cannot combine with matrix, full-width, numbering, or tabs; numbering and tabs are also mutually exclusive.

.wide in OINK 1.4.0

The short author marker retains the technical-table layout introduced in 1.3.1 and compatibility with existing markup. It composes with .matrix and .full-width; Markdown preserves the authored marker.

Table reading

.expand in OINK 1.4.0

Explicit opt-in for theme-rendered Markdown tables, independent of .wide.

Only .expand tables receive an HTML reader frame and load table-reader.js. The runtime adds a direct top-right corner action, revealed on hover or keyboard focus and visible on touch and in forced colors. It adds no above-table toolbar, global setting, automatic size detection, or whole-table click handler. .fields .expand warns and ignores expansion; layout markers, captions, numbering, and tabs otherwise compose normally. Goldmark supports {.wide .expand} and {class="wide expand"} with block attributes enabled and no intervening blank line.

One native modal moves the original table and scroll wrapper, keeping IDs, links, selection, text size, row order, and native table semantics. Its title receives initial focus; Tab stays inside; Escape and Close restore the original nodes, inline/page scroll positions, and entry focus. Coordinated closes suppress focus return. Plain captions remain native; numbered captions name the dialog and any otherwise unnamed table while open. Single-row headers stick inside the viewport; .matrix retains its existing row headers and pinned first column. There are no sorting, filtering, density, export, or virtualization controls.

Missing JavaScript, blocked assets, or unsupported dialogs leave readable inline content with no dead entry. Tables with references outside their movable subtree stay inline; same-page links to outside targets restore the table before navigation. Before browser printing, restoration is synchronous. Dedicated Print, RSS, Markdown, and LLMS keep their existing content boundaries without reader UI/runtime. The accepted decision records the rationale.

The Markdown image hook is the ordinary image API. Inline images stay inline. Block images become figures with caption or num. Only the native form supports image processing. The full fig source form is a numbered container and deliberately excludes command/options. For processed numbered images, use native block images with num. Allowed image attributes are id, num, caption, width, height, link, command, and options, plus shared safe attributes. command and options must appear together. They use Hugo Fit, Resize, Fill, or Crop on processable local resources. Plain linked images use Markdown syntax. The link attribute therefore requires a caption or number. Linked and decorative images do not load Zoom.

Zoom triggers keep image alt text and the localized preview action in their ARIA accessible name. They insert no helper text into articles. Plain-text or rich-HTML copying must not add preview instructions, even if the editor removes theme styles. Authored images and captions remain intact. When Draw.io and Image Zoom share an image, Edit and Zoom remain separate sibling buttons. The editor control supports keyboards and stays visible on touch devices and in forced-colors mode. The Draw.io editor opens in a modal dialog with a localized host Close button. The button, backdrop, editor exit message, and Escape while focus is in the host dialog dismiss it, release its message listener, and restore focus to Edit. Cross-origin iframe keystrokes belong to the editor and cannot bubble to the host; users can leave the editor’s Tab sequence to reach the host Close button. Opening another editor starts a fresh session.

Gallery accepts one Markdown image per line with optional description, link, and class. FileTree accepts indentation, - name, optional /, comments, and validated icon/tone/open/type attributes. FileTree fence wrap accepts true or false, defaults to false, and changes only screen comment layout: true wraps comments, including unbroken tokens, while rows grow from their existing minimum height. Filenames retain ellipsis. Missing or false values preserve compact desktop/tablet rows; mobile stacking, divider controls, directory folding, and expanded Print output keep their existing behavior. Invalid values warn and fall back to false. Markdown preserves explicit wrap values and tree source; Print renders expanded static figures and trees.

All code highlighting uses Chroma. Common fence attributes include title, copy, wrap, collapse, label, id, line options, tabs, and Book num/caption. Copy returns authored source. Mermaid palettes follow light/dark mode, independently of visual preset. The default dark edge-label background is #404040 for AA contrast with its label text; explicit params.mermaid.themeVariables values retain priority.

ECharts uses declarative JSON/YAML. Callbacks use $fn:<name> from window.OinkEchartsFunctions. Embedded scripts are never executed.

In OINK 1.4.0, Infographic SVGs scale with their container width, including orientation and shell layout changes, without repeated DSL rendering. Initially hidden containers wait until measurable. Fence height and full keep their existing meanings. Transparent Infographic output receives a white canvas; an explicit DSL background sets the canvas instead. Site light/dark changes leave authored light, dark, hand-drawn, palettes, and SVG styles intact. The default dark text therefore remains readable without recoloring author content. Authors remain responsible for contrast when explicitly choosing transparent backgrounds or custom text colors.

Markmap node text on screens follows the article text color (--bs-body-color) via --markmap-text-color, dynamically adapting to light/dark mode changes, style presets, and restored user preferences to maintain contrast. Printing retains Markmap’s default dark text on the white canvas. This mapping is scoped to article content across both the wrapper and generated SVG, and can still be overridden by site CSS of equal specificity or SVG inline tokens. (Added in OINK 1.3.1.)

In OINK 1.4.0, Markmap fits on first measurable display and container resize, including hidden panels when revealed. Reader pan/zoom suspends automatic fitting so layout changes preserve their view. The keyboard-accessible Fit to window button restores the whole map and resumes automatic fitting. Layout fits do not animate; reduced motion also disables node transitions. The control is omitted from print. Source normalization removes surrounding blank lines and common indentation before parsing, preserving YAML options and outline levels.

Mathematics uses Hugo’s build-time KaTeX output and local CSS, without a browser mathematics runtime. HTML and Print use the vendored stylesheet and preserve MathML and authored TeX. Validate mathematics with the current Hugo baseline defined in the architecture contract. Markmap uses the matching vendored KaTeX runtime. In OINK 1.4.0, numbered equations reserve readable formula space based on the available column width, including columns narrowed by a sidebar or TOC. Captions move below the formula when they do not fit beside it; long words wrap. Number-only captions, MathML, and TeX remain available. Print gives the formula the full reading width and places the caption below it. Long captions must neither squeeze the formula to zero nor widen the page.

Swagger and Redoc accept HTTP(S) specification URLs or paths rooted under static/. Neither resolves page resources. Redoc handles paths with or without leading slashes identically and joins local paths to baseURL. Only HTML is interactive. Print, Markdown, and RSS provide static specification links.

Book

The book type extends the docs shell and follows the content tree or data/docs_nav.json. book_number, book_part, book_kind, and book_status are presentation metadata. They do not change Hugo publication state.

Numbered kinds are fig, tbl, eq, and eg. Their default ID is <kind>-<num>. eg requires a caption. eq without num is an unnumbered display formula. xref names exactly one kind with optional page/anchor, or an anchor with explicit text. Numbered examples have one framed body and caption.

Footnotes belong to the page document. Native numbered tables and fences keep them there. Shortcode bodies are separate Goldmark documents, so footnote references in tbl, eg, fig, card, tab, field, or include warn and remain literal. The check ignores text that has code syntax.

book-toc follows navigation order at depth 1–3. Each of the four book-* indexes collects one target kind. Single-page Print keeps ordinary heading, footnote, and tab IDs exactly as regular HTML renders them. Multi-page section and whole-Book Print rewrite cross-page links and namespace page-local headings, footnotes, and generated tab IDs to prevent collisions. Local heading links match after one URL-fragment decoding step, so ordinary Markdown links to Unicode headings retain their target in an aggregate. Explicit target IDs remain intact. Consumers opt into these potentially expensive aggregate outputs. Consumer-authored raw HTML anchors and custom shortcode IDs remain global by default. Add the boolean data-td-print-local attribute to an element with an id to declare a page-local anchor. An aggregate namespaces that ID and its same-page links; ordinary HTML and single-page Print retain the original ID. This lets legacy aliases and custom shortcode headings keep their existing deep links while remaining unique across aggregated chapters. Unmarked authored IDs must remain unique within their aggregate.

Release and download

Release front matter uses one release_url matching https://github.com/<owner>/<repo>/releases/tag/<tag>. The URL supplies owner, project, and tag. The page supplies the date. No remote release state is fetched. Removed release, release_products, and release_group_by_product warn with their replacements. They provide no compatibility path. The section index lists every page. It uses parsed project tag when available, otherwise the page title. For layout: releases, HTML keeps this release index; section Print aggregates the full release bodies with chapter-local IDs, in both development and production builds.

Checksums accept canonical lines or one source resource, never both. Filenames cannot be paths. HTML adds local copying. Static outputs show complete hashes.

Downloads use data/download/<key>.yaml. Channels are rolling or pinned. Only pinned URLs and commands interpolate ${version} and ${tag}. Before publication, rolling channels remain usable, while pinned channels show pending. Markdown renders the complete channel list. RSS omits the component.

Switching tabs remeasures collapsible code blocks in the newly visible panel. Their expand and collapse controls remain usable after fonts settle and when ResizeObserver is unavailable.

Verification

The architecture contract defines shared output rules. Component-specific exceptions appear above. Markdown and RSS set no browser runtime flags. Print keeps only flags required by rendered print features. Source checks cover parameters, hook policy, runtime isolation, and migration. Output checks compare HTML, print, Markdown, RSS, and LLMS goldens. Browser tests cover interactive features. See the migration contract for migration rules.

v1.5.1 review corrections

The following corrections shipped in v1.5.1 and are part of the current consumer contract.

  • Named-parameter shortcodes reject positional arguments with warnings and continue the ordinary build. Invalid input checks require a successful build and verify the safe output, rather than accepting either exit status.
  • Invalid or missing Book numbers retain unnumbered readable content, without empty fig-, tbl-, eg-, or eq- targets or figure-index registration.
  • Generated IDs include the complete shortcode ancestry. Independently rendered Markdown bodies namespace generated code, chart, FileTree, and field IDs along with their references; authored code IDs remain intact.
  • RSS renders static HTML for Book figures, tables, equations, examples, links, contributors, specification links, recordings, and checksum tables. It does not expose their Markdown source or browser controls. Release assets retain their documented RSS omission. The RSS check uses the ordinary section feed.
  • Copy feedback uses aria-disabled with an operation guard, preserving keyboard focus while preventing duplicate clipboard writes.

3 - Shell and navigation contract

Navigation authorities, immersive blog presentation, search, actions, taxonomies, indexes, and page-end composition.
OINK 1.5.1 contract

This contract describes OINK v1.5.1.

Authorities and navigation

Concern Authority
Global navigation Hugo menus.main
Docs / Book sidebar and pager content tree or data/docs_nav.json
Root switcher resolved top-level content roots
Discovery per-language local search index
Page and Palette actions shared action registry

No feature adds another menu or page tree. One menu child level is interactive. Deeper levels warn and flatten below linked group headings. External links use target="_blank" rel="noopener noreferrer". Internal links retain language and deployment subpaths.

Desktop and drawer navbar views use the same tree. Every dropdown has one moderate-width column of icon and title rows. The mega panel and its columns menu parameter are retired. Configured columns warns and keeps one column. Menu descriptions remain configuration data only. The link tree stays centered when space allows. At phone widths it reserves the brand and utility controls’ widths before centering, so a longer menu cannot overlap the search control. It uses text links from lg and icon links below lg. Between lg and md, the end edge keeps search, version, language, theme, and GitHub controls without a menu button. Below md, appearance stays beside search and the drawer entry; version, language, and GitHub move to the footer dock. Home and explicit Landing pages add a drawer control beside search, opening the complete labeled tree. Shell pages with sidebars use the sidebar drawer control in that position. Explicit Landing layouts use only the Landing drawer, including pages whose content type is Book or Docs. A page never renders both drawer controls. The navbar loads its drawer runtime even when a site supplies a custom homepage or Landing body without the theme’s section renderer. No drawer button appears from md upward. The stock 404 page has no reading sidebar and never advertises its drawer, even when a root cascade assigns it a Docs or Book type. Adding a custom type to shell_types recognizes its shell capabilities; it does not create a sidebar in a custom template. Full-width custom pages without a sidebar set sidebar_enabled: false. Language links target the page translation or the language home. Links stay relative for languages sharing a host/base path. They become absolute only for language-specific baseURLs. hreflang stays absolute and lists only actual translations. It never includes the switcher’s language-home fallback. Paginated blog indexes have their own canonical URLs; later pages omit cross-language alternates because translated archives can have different page boundaries. navbar_autohide applies only to fine pointers from 768px. It never applies at touch or drawer widths. The hidden bar keeps its reserved space, and a pinned bar occupies exactly that space, including its rule. Revealing fades the bar in place without covering resting content. Hero pages use their overlay navbar instead of this policy. The homepage shares their soft boundary: a short background wash below the bar replaces the bottom rule and scrolled shadow.

Sidebar and pager share the navigation root and order. manual_link, build.render: link, dividers, hidden nodes, and placeholders keep their documented behavior. sidebar_icon_policy accepts all, the default, groups, or none. Icons use one Font Awesome class pair. Invalid policies follow the shared warning and fallback contract. At sidebar_cache_limit, both walkers may reuse neutral markup only for the same language, root, and effective settings that affect output. The markup stays visible without JavaScript. The normal shell runtime adds the active path. Book pages with sidebar_headings remain page-specific and bypass the shared tree cache.

Root candidates are linkable, non-divider top-level sections, followed by sections with sidebar_root_for: self. Candidates are deduplicated by URL. Both sources honor sidebar_root_menu: false. Absent or true values preserve inclusion. The current resolved root is appended even if excluded from global choices. Zero entries render no control. One entry renders a static link. Every URL keeps language and deployment prefixes. Dividers and sections with build.render: never cannot be switcher links.

A sidebar_divider leaf keeps its static heading. Divider sections keep children in both sidebar walkers. Their label is not a link. When folding is enabled, they have a real disclosure button. Dividers never become pager targets. Children keep their positions. Use build.render: never to omit the divider section’s outputs without hiding descendants. Breadcrumbs show its label without a link. Search omits it. Navigation JSON promotes its children. Print keeps child documents. Book TOCs keep the group label and child links, but omit headings from the unpublished group body. toc_hide still hides the whole subtree. It is not a grouping option. Explicit navigation keys are independent of language and deployment paths. Rendered links retain both prefixes. The sidebar, pager, and navigation JSON select explicit sections by the resolved page identity. A node belongs to a root when it is that root, a content descendant, or a Docs/Book page that resolves to the same sidebar root. This lets a manual keep files at the content root while the Docs section owns its navigation. The selected node’s children define its navigation hierarchy; they need not be physical content descendants. Custom url values do not change ownership. A tree for Docs does not replace a separate Book root, or vice versa; a nested sidebar root selects its own branch. Roots absent from the explicit tree use the content tree. Only section-root Docs/Book navigation evaluates the explicit tree. Home-root navigation and other shells ignore it, including its warnings. An explicitly empty sections array warns and falls back only where that tree applies. Uncached explicit sidebars mark the current page and expand its authored navigation ancestors from the resolved page identity, even when a node omits url or the page has a custom URL. Listed physical ancestors still expand when the current page is absent from the manifest. Legacy URL and active-path hints remain supported. Both authorities remove toc_hide subtrees. Navigation JSON keeps manual_link_relref as an internal link to its resolved destination, not a page identity.

Book headings and responsive outlines

params.ui.sidebar_headings defaults to false. Book pages show the page tree in the left sidebar and the page outline in the right rail. Set sidebar_headings: true (h2 only) or 2, 3, 4 (deepest heading level) to add headings below the active Book row. Page front matter overrides a section cascade or site setting; explicit false disables an inherited opt-in. This setting does not disable the right outline or its relocation below xl.

Fixed in OINK 1.3.0

The documentation Book no longer opts into sidebar headings. When enabled, the branch follows the parent row’s navigation depth, reserves its icon and chapter-number columns, and adds one indent. Deeper headings indent again; the same logical spacing applies in right-to-left layouts.

From 1200px, the fixed right rail uses 20% of viewport width, clamped to 286–420px. The flow rail uses 22%, clamped to 340–440px, and still honors --td-shell-toc-flow-w. The reserved column and visible panel share one width. Responsive widths follow the viewport immediately, without width transitions: shrinking the window must not make the article rebound between drag steps. Long labels wrap inside the rail; widening it can bring them onto one line. Below 1200px, outline groups move to the left sidebar when enabled; below 768px, they live in its mobile drawer. Pages with sidebar_enabled: false keep the rail hidden below 1200px. Browser zoom follows these CSS breakpoints. Collapsing the right rail releases its full width at once at every desktop size; the panel retains its slide and fade.

Sidebar runtime

Fixed in OINK 1.3.0

With sidebar_menu_foldable: true, each branch controls the visibility of its children. sidebar_menu_compact must not permanently hide leaf entries inside an expanded branch. This applies to cached and per-page trees in both Docs and Book. Non-foldable trees retain compact filtering. Sites still using OINK 1.2.0 can set sidebar_menu_compact: false while keeping folding enabled until they adopt this fix.

Available since OINK 1.1

OINK 1.1.0 provides this disclosure API and explicit hidden-content isolation. Version 1.0.0 does not provide the API.

window.OinkSidebar controls registered tree disclosures and movable TOC, backlink, and taxonomy groups, regardless of their current DOM parent. setExpanded(id, boolean, {source}) returns true for valid targets. It returns false for unknown IDs or non-boolean values. getState(id) returns a new {id, expanded} snapshot or null. IDs are existing aria-controls region IDs. The API cannot change arbitrary elements outside registered OINK groups.

Sources are user, active-path, responsive, and api, the default. Each writer sets aria-expanded, td-is-open, the localized label, and region inert state before emitting one document event. The event is oink:sidebar-disclosure with detail: {id, expanded, source}. Repeated writes of the same state emit no event. API restoration keeps current-path ancestors expanded. Explicit user actions can still collapse them. Before isolating a closing region that contains focus, return focus to its toggle.

ready is a Promise that resolves to the API after initial hydration and responsive placement. isReady and oink:sidebar-ready also expose completion to late consumers. Sites own optional persistence. Await readiness, read storage inside try/catch, then restore valid region IDs through the setter. OINK owns whole-column collapse, width, and scroll persistence. It does not define a version or locale schema for reader-selected branches.

Desktop collapse and closed mobile drawers make panel content inert and mark the panel aria-hidden. Focus leaves before isolation. Opening clears isolation before focus enters. The panel remains the 16px pointer sensor. The external restore control remains active. Hover, Escape, backdrop dismissal, breakpoint cleanup, and scroll unlocking keep their existing behavior. No-JavaScript fallbacks omit these runtime attributes.

Whole-column TOC collapse also isolates hidden panels. If the collapsing control has focus, move focus to the visible floating restore button. Restoring the column returns focus to its visible column control. When the aside moves into the mobile sidebar, clear former column isolation before the drawer controls interaction. The drawer’s Tab trap includes only rendered, non-inert controls. It excludes hidden and collapsed descendants.

Immersive blog presentation

There is no article type or second shell. Four independent keys enable immersive reading on the ordinary blog shell. Set them on pages or section cascades. Repeat values on the section index when it also needs them:

featured_image: hero
toc_style: flow
toc_taxonomies: false
sidebar_enabled: false

Blog shells omit breadcrumbs by default because articles are standalone pieces. The recipe therefore needs no breadcrumb key. breadcrumb remains an ordinary key that pages or cascades may enable or disable on any shell.

hero uses the shared featured image as a decorative full-width background on single pages and section indexes. Without an image, it renders the normal opening. banner and wash remain single-page modes. The navbar overlays a hero with a contrast scrim and scrolls with it.

toc_style accepts fixed or flow. Flow places a wider rail beside the article and fixes its position only after scrolling. Its resting position aligns with the article info line, or the description if no info line exists. docs-shell.js measures this offset because title wrapping is unpredictable. Without JavaScript, the rail starts at the article’s start. toc_taxonomies: false removes term clouds. Rails with neither TOC nor clouds render nothing. notoc remains the page-level TOC opt-out. These switches do not change bylines, tags, series, pager order, feeds, or page-end composition. The rail disappears below the xl breakpoint.

When scrolling down and the footer enters the viewport, the fixed TOC rail (fixed) shares the visible-footer offset (--td-shell-footer-offset) so its scrollable area ends neatly above the footer, keeping the lowest headings and taxonomy links accessible by wheel and keyboard. Footer resizing and content reflow, including tabs, blog view switches and loaded media, update this boundary without requiring a scroll event. This clearance applies even when the sidebar is disabled (sidebar_enabled: false). With no footer the offset is zero, while toc_style: flow relies on its own sticky boundary. Mobile drawer placement and print visibility are unchanged. (Added in OINK 1.3.1.)

Search, actions, and runtime

params.offline_search enables a local index per language. When enabled, it also builds under hugo server by default. Use offline_search_on_serve: false for large editing cycles. HTML search appears on Home, shell pages, and Landing pages with landing_search enabled. Other non-shell pages and Print omit the dialog, Lunr, and Palette.

Search metadata uses search_keywords, search_boost, default 1, and search_exclude. The index includes URL, title, taxonomies, excerpt, headings, description, body/summary, root, section, type, keywords, boost, breadcrumb, and icon. The fixture budget is 2 MiB raw / 512 KiB gzip. Sites may return extra strings from hooks/search-keywords-extra.html. Keywords affect matching and ranking. CJK matches found only through keywords display the description or excerpt, not the keyword list. Body matches keep surrounding text as context.

Local search in OINK 1.4.0

Queries normalize case/Unicode width and split whitespace and CJK/Latin boundaries, up to 24 unique terms, preserving identifier punctuation. A CJK run is a literal substring; no dictionary or remote dependency is added. Literal field matches and English Lunr stemming cover terms across fields; typo fallback applies only to ASCII words of at least five characters (one edit, or two from eight characters). All-term pages suppress partial results. Otherwise coverage is shown and sorted first. A contiguous whole phrase leads within equal coverage; the positive page boost multiplies the strongest-field sum within those tiers. Repeated occurrences of a term in its strongest field add a bonus below 20%, which orders pages within that field without letting them outrank a stronger field; a single occurrence scores the plain field weight. Title/URL break remaining ties. The global result limit precedes existing root grouping and menu group order.

Optional sections entries carry actual rendered id and title; content scope also carries UTF-8 byte start offsets into the single stored body. Read IDs from rendered content, including h1/h6 and shortcodes, instead of reconstructing them from titles or the configured TOC. Index reads temporarily select HTML and restore the previous output context, so RSS/Print traversal cannot poison HTML content. Reduced scopes omit body offsets. Old indexes without sections remain usable. Return one result per page with its best matching section, encoded fragment and nearby text; metadata-only matches may target the page. Preserve language/subpath URLs, exclusions, and scope-specific content. Normalized matches retain the original text in excerpts and highlights. Heading extraction distinguishes id from data-id and ignores script/style content.

The labeled native radio group shows all roots and the page’s FirstSection root as two adjacent scope options, using the index’s existing root authority. Each option has a 44 px hit area and a visible focus ring. Tab visits the selected option; arrow keys change scope, and Tab/Shift+Tab stay within the dialog. Filter before ranking/limiting; another root’s match cannot suppress spelling fallback within the selected root. The default is all roots; the choice lasts only on the loaded page. Scope affects pages only and is hidden in command/choice mode. Counts and partial coverage are visible and live-announced in one footer, alongside desktop keyboard hints. Mobile hides only the hints. Composition suspends delayed and index-load renders as well as Enter activation. No new configuration authority or build step exists. The owning theme search checker and the site’s real-corpus/browser tests cover these additions; the maintained summary indexes keep the 2 MiB / 512 KiB budgets.

Built-in action IDs are compare_translations, copy_markdown, copy_link, open_chatgpt, open_claude, view_markdown, view_history, edit_page, create_child_page, create_issue, create_project_issue, print_section, print, switch_preset, switch_theme, switch_language, switch_version, and open_github. Outside the share bar, copy_link appears only in the Palette. Site commands under languages.<lang>.params.ui.command_palette.commands may open safe URLs or invoke built-in IDs. They never inject JavaScript. The legacy clipboard fallback restores previous focus and selection, including selection direction. It does not reclaim focus if another control acquired it during copying.

In OINK 1.4.0, breadcrumbs and page actions wrap onto separate rows when the reading column or enlarged text requires it. Long unbroken path labels wrap without clipping; all breadcrumb links stay available. The action menu is bounded by the viewport and retains keyboard focus and dismissal behavior at 200% text size, including a 320px viewport.

Fixed in OINK 1.3.0

The page-action disclosure closes when keyboard focus leaves its containing controls, including Tab and Shift+Tab. Moving between its controls keeps it open; dismissal leaves focus at the reader’s new destination. ArrowDown on its closed toggle opens the menu and focuses the first action immediately.

Edit, history, and create-child actions require repository-relative source files. Normalize physical filenames and the site working directory to / separators before containment checks. path_base_for_github_subdir matches this normalized path. For local content, it matches relative to the working directory. For external mounts, it matches the absolute path. A string regex removes matches. A {from, to} map may replace them. External sources need an explicit match. After mapping and cleanup, empty paths, ., absolute paths, drive-qualified paths, and paths starting with a .. segment suppress these three actions. Docs and project issue actions remain available under their existing repository settings. Windows mappings must match /, not \. Normalization preserves filename case.

The Palette has empty, text-search, and > command modes. Quick links come from navigation. It provides no history, semantic search, personalization, or remote fallback. Queries stay in the browser. No default telemetry is sent.

OinkSurfaceCoordinator coordinates the Palette, Appearance, Draw.io, Expo viewer, drawer, root, language, and version menus. Each surface controls focus restoration and Escape. Already closed Appearance menus do not restore focus when the coordinator closes them. Keyboard navigation ignores editable controls and modals. The desktop nonmodal Appearance panel permits search shortcuts; its mobile modal sheet and other open dialogs, including fixed-position ARIA dialogs, retain keyboard ownership. Inside the mobile drawer, Escape closes the root switcher first and returns focus to its trigger. A subsequent Escape closes the drawer. Moving focus outside the root switcher dismisses its popover. /, \, f, and c open search or commands. j/k move between headings. q/e move between pages. h changes presentation. l/y, t, and r open language, theme, and root choices. Sidebar WASD/Arrow navigation uses real focus without changing Tab order. Non-link divider buttons participate in tree navigation. From a child, Left/a focuses its parent group. A second press collapses it. Right/d opens closed groups or enters the first visible child of open groups. Previous and next page navigation includes only links, never group buttons.

The outline uses one heading model and computed scroll-padding-top to derive the cursor and visible-heading range. Its SVG line and dot share animated values, preventing drift. Valid URL fragments are decoded. Malformed percent sequences use the literal heading ID. This applies when indexing links and selecting requested headings near the page end. No speculative DOM repair pass is allowed. The normal shell runtime always owns this tracking. params.ui.scroll_spy and page scroll_spy remain quiet compatibility no-ops throughout 1.x. They emit no separate runtime and may be removed only in a future breaking release.

Search-tail extensions

Available since OINK 1.1

This API is included in OINK 1.1.0 and absent from version 1.0.0.

Trusted site JavaScript may call OinkCommandPalette.registerSearchTail({id, rows, activate}). YAML and the action manifest remain data-only. The bundle loads only when local search is enabled. Registration requires a unique ID matching [A-Za-z0-9][A-Za-z0-9_-]* and two functions. Invalid or duplicate registrations throw. The returned unregister function is idempotent. It cannot remove later registrations that reuse the ID. Live changes schedule one owned render. Removal cancels the provider’s pending action.

rows(context) returns descriptors synchronously. Context is a frozen {query, locale, phase, pageResultCount} snapshot. Query is trimmed. Locale is the HTML language tag. Phase is results, empty, or error. Count includes only local page results after the limit. Providers run only for settled, nonempty text searches. They never run in empty, command, choice, or loading states. Rows appear after native results and actions in the localized Actions group, in registration order. Native empty/error messages and input-triggered index retries remain available.

Each descriptor requires a unique per-provider id with the same ID syntax and a nonempty string title. Optional description, icon, and disabledReason values are strings. available is boolean and defaults to true. OINK copies and freezes these fields. Display strings render as text. Invalid descriptors, duplicate IDs, asynchronous returns, or thrown callbacks discard that provider for the render. Other providers remain unaffected. Callback counts are not guaranteed.

activate(row, context) runs only through ordinary row activation. It receives the copied descriptor and original context, with an AbortSignal and handoff() function. While activation is pending, all other row activations are blocked, including entry into native choice menus. Synchronous throws and rejected promises clear pending state, keep the Palette open, and announce the localized action-failed message. Fulfillment values are ignored. Success closes the Palette without taking focus from another surface. Closing, reopening, changing the rendered query, or unregistering cancels pending work. Late settlement cannot modify newer sessions.

Before opening another coordinated surface, call context.handoff(). It closes the Palette without returning focus or aborting the activation. The consumer then owns the new surface’s focus and error interface. Later Palette sessions or unregistration can still cancel unfinished work. Successful completion does not abort handed-off operations. OINK sets no timeout.

rows() must remain pure. This trusted-code contract is not a sandbox. Default queries remain local. No remote provider or telemetry is bundled. Sites own extension network behavior and provider consent.

Desktop nonmodal Appearance permits search shortcuts; mobile modal Appearance and every other open dialog retain keyboard ownership. In the mobile drawer, Escape dismisses the focused root switcher first and returns focus to its toggle; a second Escape closes the drawer. Focus leaving the switcher dismisses it. Search opened from the Landing drawer returns focus to the visible menu toggle. Choosing a visual preset in the Palette keeps it open for the next action.

Share

params.ui.share defaults to empty and accepts any ordered subset of 16 targets: x, bluesky, mastodon, facebook, linkedin, reddit, hackernews, telegram, whatsapp, line, pinterest, weibo, chatgpt, claude, email, and copy. Page lists replace inherited lists. share: false disables the share bar for that page. Unknown entries warn and are removed. Only regular pages display the bar. Print, Markdown, and RSS omit it.

Targets are plain intent links containing the page permalink/title, plus a local copy_link button. Pinterest media uses the shared featured-image resolver. ChatGPT and Claude receive build-time permalink prompts independently of page-menu assistant actions. Discord has no public intent target and is deliberately absent.

The bar loads no platform SDK, iframe, script, stylesheet, counter, or campaign parameter. It sends no request until a reader activates a link. It displays one accessible labeled glyph row. share/items.html resolves targets. share/bar.html renders them.

Annotation

annotation-items.html resolves page annotation descriptors. page-meta-lastmod.html renders them. Inline annotation links are underlined so readers can identify them without relying on color, including muted last-modified and upstream attribution lines. You may override either partial narrowly. Lines appear in this order:

Line Condition
Last modified Lastmod is set
Upstream front matter upstream_link is non-empty
Translation configured authoritative language has a translation and this page has authored text

upstream_link is per-page and can be inherited through cascades. upstream_link: "" disables it. Other facts resolve from site params → data/upstreams[upstream_source] → front matter: upstream_name, upstream_copyright, upstream_license, upstream_notice, optional upstream_ref, and upstream_modified. A link requires the first four facts. Invalid or incomplete attribution warns and emits no legal notice. Unsupported URLs are refused.

upstream_modified changes the credit verb and links commit history within the existing attribution sentence. The notice page includes complete license and warranty text. params.ui.translation_notice enables translation notices. The page key translation_notice can cascade. Notices skip generated pages and pages without bodies. Natively authored pages can use translation_notice: false to disable them.

Authors and series

Blog article heads show title, info line, term badges, byline, then series strip. The description starts the body below them. article-info.html always shows the date. With reading_time enabled, it also shows word count and minutes. Front matter upstream_link supplies the same per-page fact used by annotation. It adds a localized original-source link, validated by the shared URL policy. Term rows contain badge sequences. The taxonomy name appears on the group label, not as a visible prefix. Inactive badges use pale neutral backgrounds, muted text, and the taxonomy’s term glyph. Linked badges use the current section’s accent background, border, and text on hover or focus. taxonomy-icon.html defines taxonomy and term glyph pairs: folder-open/folder, tags/tag, cubes/cube, users/user-pen, book-bookmark/book for series, and generic shapes. params.ui.taxonomy_icons overrides a pair with one string for both uses, or a taxonomy/term map. Invalid values warn and keep built-ins. Right-rail clouds show the whole-taxonomy glyph only in their heading; repeating it on chips would add noise beside an already announced taxonomy. Their chips therefore contain only text and counts. Standalone taxonomy directory cards show one term glyph. Bylines show only portraits, names, and one-line profile bios. They have no label or date. List rows, cards, and term archives share a metadata line: date, localized author-and-section phrase, then word count and minutes. The same reading_time switch controls these last two values. A wrapping badge line follows, with terms from every taxonomy in alphabetical taxonomy order. Each badge has its term glyph. Cards omit authors because the metadata sentence already names them.

Authors activate only through taxonomies: {author: authors}. Profile term pages define display names, summaries, bodies, and featured-image avatars. Missing profiles use link titles, initials, and archives. authors-resolve.html keeps front matter order for article heads, list rows, and one RSS dc:creator per author. Legacy author stays unchanged when authors is absent. When both exist, authors takes precedence without warning. Custom author-taxonomy plurals remain ordinary taxonomies.

Series activate only through taxonomies: {series: series}. Term pages own the introductions without adding a parameter, data file, cover model, or runtime. Pages use series: [name] with optional series_weight. series-pages.html puts weighted members first, ordered by weight. Unweighted members follow in ascending date order, with Path tie-breaks. The strip and term page share this order. The first named series gets one HTML/print strip. The panel uses translucency and background blur because an opaque surface would obscure the featured image behind the band in hero articles. On plain articles, the tint resolves to the page background, allowing one treatment to serve both.

The summary covers the full bar and trailing caret, while the series name and taxonomy icon remain a sibling link over a hidden width reservation. This keeps nested interactive controls out of the summary. Opening adds a thin rule below the bar and displays reading order in an adaptive grid on the same surface, preserving DOM order.

Each member link aligns its ordinal at the end of a fixed square track so titles keep one edge at every list length. Equal cells stay in one column when narrow and add columns only while titles retain a readable width, allowing desktop panels to use their width without stretching one selected row across the panel. Hover and current-position states reuse the two backgrounds from sidebar navigation; current members also have filled ordinals and heavier titles, so color is not the only cue. Print expands the list in one column. Singleton series and non-HTML outputs omit the strip. Numbering, cross-references, and aggregate outputs remain Book features.

Default article taxonomy chips omit reserved authors and series because dedicated features already show them. Explicit params.taxonomy.page_header restores either.

Blog indexes and page composition

Blog section indexes use params.ui.blog_index. list, the default, cards, and gallery show one flat sequence, newest first, with shared blog_index_size pagination and no year headings. table shows date/title/tag rows; without a layout switch, it lists the complete section without pagination. With switching enabled, it uses the same page as the other layouts. Cards use shared lead images, localized date/author/section metadata, tags, and three-line summaries.

Taxonomy pages such as /tags/ and /authors/, and their term pages, share shell/taxonomy-head.html. Taxonomy heads show a whole-taxonomy glyph in a tinted tile, the localized name, and term count. Term heads show the term title and page count from ui_taxonomy_pages, using the locale’s CLDR plural form. If no breadcrumb appears, a label above the title names and links the taxonomy, since enabled breadcrumbs already provide this context. Generated taxonomy breadcrumbs use the head’s localized label, not Hugo’s plural title. Below the head, shell/taxonomy-cards.html lays out one-line term cards. They use the rail cloud’s order: most-used first, with alphabetical ties. auto-fill creates equal columns, preventing short taxonomies from stretching two cards across the page. Each card contains the term glyph, term, and page count. The whole card is linked. Author cards instead lead with the byline’s small portrait, using the same avatar partial. Cards include no description or newest page because the title and count already identify the term; another line only blurs the grid. There is no filter-chip row or “All” chip because the section root is already in the sidebar and navbar. Term pages stay row lists. Author profiles keep their own head.

Taxonomy and term rails start with shell/taxonomy-switcher.html. Each declared taxonomy has one row with its whole-taxonomy glyph, localized name, and term count, linking to its index. The current taxonomy uses the selected background. The switcher connects taxonomy pages because cloud chips link to terms and cloud headings only collapse. Sites with one taxonomy show no switcher. The switcher and clouds share the toc_taxonomies switch. Taxonomy pages scope clouds to the whole site (taxonomy-root.html returns no root for this page kind) and omit their own cloud because its terms already appear in the cards. Term pages keep section scope and all clouds.

params.ui.blog_index_toggle renders all four forms for the current paginator slice and lets readers cycle between them: list, cards, table, then gallery. The fourth form is included in OINK 1.4.0. The configured form controls initial display. Hidden forms load no images. Stored reader preferences apply only to indexes that publish all four forms. Sections without toggles publish one form and always show it. Front matter or cascades override site mode per section. Tables published without toggles remain complete, unpaginated archives.

blog_index: gallery presents each post as a linked cover. It uses the shared featured-image resolver, the same date order and blog_index_size paginator as rows and cards, and preserves manual_link. It does not change the content type to Expo. Clicking a cover navigates to the article; no image viewer opens.

params.ui.blog_gallery accepts mode (wall, cards, or seamless, default wall) and size (integer CSS pixels, 160–360, default 240). A page or cascade blog_gallery block replaces the site block. Missing or invalid fields use their built-in defaults; invalid values warn. The gallery toolbar changes mode and size independently of Expo albums, using td-blog-gallery-mode and td-blog-gallery-size storage keys. The outer view retains td-blog-index.

Wall uses Expo’s justified row geometry with 6px gaps; Seamless removes the gaps. Cards uses columns filled from the shortest column. Covers keep their proportions within bounded tile ratios and are contained rather than cropped. Below 500px of gallery width, Wall and Seamless bound tile ratios more tightly to keep the caption columns readable, including for very tall images. Processable covers larger than 960px receive a preview within a 960 × 960 box; GIF previews are still images. No build-time remote fetch is introduced.

Wall and Seamless reveal titles and descriptions on hover or keyboard focus. Without hover, captions remain below images, and row spacing includes their height. Cards always shows captions. Covers without images retain a linked, named placeholder; failed images receive the same fallback after enhancement. The title names the link and the cover is decorative. Hidden forms use lazy images. Reappearing forms, resized sidebars, fonts, and late image dimensions trigger layout without overlapping items. Without JavaScript, a responsive grid keeps links and captions visible and hides the inactive controls.

params.logo always supplies the brand mark. params.wordmark, or the site title, supplies text hidden at compact widths. Docs, Book, Blog, and Swagger share one shell model. Page-end order is Share, Feedback, Annotation, Pager, Comments. Docs/Book pagers follow sidebar preorder. Blog pagers use weight, then reverse date. pager: false disables the pager. Static outputs omit pager controls.

Every rendered footer has an icon-only utility dock at the end of its bottom line. Dock order is version, language, theme, then keyboard help. Menus open upward. The version control never shows the current branch or release label. The fat footer’s collapse chevron follows the dock. Below lg, copyright, center content, and dock become three centered full-width rows, with the dock last. These global controls do not appear in sidebar footers. footer_style: none removes the whole bottom line.

There is no archive shell, arbitrary-depth flyout, second navigation authority, query upload, or browser compatibility shim for removed configuration. Feedback sends only docs_feedback through an existing gtag and stores the selection locally. It does not replace Giscus.

An explicit params.ui.quick_links: [] disables quick links instead of restoring the defaults. Invalid sidebar_root_link_self values warn and keep the documented true fallback. Taxonomy and term pages use the shared page_width validator.

Translation comparison

params.ui.compare: true adds an icon-only Open duo view entry, whose glyph differs from every shell control’s, beside the page actions and a localized Duo View action (compare_translations) in the Command Palette on Docs, Book, and blog pages that have an actual HTML translation on the same origin. The reader title, its Sync Scroll switch, close icon and sync notes use the same catalog. The entry exposes its label as its tooltip and accessible name. When keyboard navigation is enabled, B toggles the reader: it opens it from the page and closes it from the toolbar or either pane, under the page shortcut’s guards (no modifier, composition or editable target). The entry and Close declare aria-keyshortcuts, and the help panel lists the shortcut under the view’s name only on pages with a real target. The default is false. This is one site setting; there is no page-pair data, new layout, or output format. A language that sets it to false offers no entry and is never a target. Navigation’s language-home fallback is never a comparison target, nor is a translation whose build policy writes no HTML (build.render: link or never, including cascaded policy). Blog archive pages after the first offer no entry, palette action or shortcut, because they have no counterpart.

The reader fills the viewport with two ordinary pages. The current page is fixed on the reading-start side, so a right-to-left host mirrors the pane order. The target selector uses existing language order and the same icon, rounded trigger, floating menu style and selected and hover option states as the site’s language bar. Its menu supports pointer and keyboard selection. Only the selected sibling is loaded, and replacing it preserves the synchronization preference. Each pane keeps its language, direction, footnotes and content components.

Below 900 CSS pixels, one toolbar row and one switcher row show one retained pane at a time. The title truncates while Sync Scroll and Close stay at the end. The switcher row holds the language buttons and, with more than one target, an icon-only target-language menu, so pane headings are not repeated. A single target is a plain label in the pane heading and the switcher, never a one-option menu. Short viewports tighten both rows: at 320 × 256 CSS pixels (400% zoom) at least 160 pixels of text remain. Forced-colors mode marks the selected pane with a border. Crossing the breakpoint moves the language menu while preserving its keyboard focus, open state and selected pane.

Shared visible heading IDs determine linked scrolling, using interpolation between matched headings. Unmatched headings are skipped. Sync Scroll is a labelled switch (role="switch"): while panes load it keeps the reader’s preference and is disabled, and it reads off when sync is unavailable or a pane fails. A partial match anchors the estimate between matching headings; with no common headings the reader falls back to a bounded beginning-to-end document-progress estimate. In either case an orange exclamation mark beside the switch, without a badge, names the case in a note shown on hover, keyboard focus or tap; Escape dismisses a visible note before it closes the reader. Matching and usable geometry are separate facts: a matched heading that cannot scroll to the reading line adds no anchor without counting as a mismatch, so it never raises the partial-match note. When no shared heading can anchor the map at all, the note says that sync follows overall reading progress. Duplicate or reordered matches are ambiguous, so the switch is disabled and the note explains why; the two panes remain independently readable. While the owner scrolls continuously (trackpad, momentum, a held key), the follower tracks it instantly on every frame; a single discrete jump eases when motion is allowed. Reduced motion and bookmark restoration always position instantly. Turning off Sync Scroll restores independent scrolling; synchronized scrolling aligns sections by heading anchors rather than locking individual paragraph rows. Opening resumes the current passage after reflow. Focus starts on the dialog title so the view is announced; until the reader Tabs into a pane, PageUp, PageDown, Space, the arrow keys, Home and End pressed there scroll the reading pane (the visible one below 900 pixels) and sync follows. Closing, Escape, B or Back restores host scroll and returns focus to the element that had it when the reader opened, such as the reading link where B was pressed, falling back to the entry when that element is gone or hidden. Only an open language menu or a visible sync note consumes Escape before the reader does. A reload, or a back/forward restore, onto the reader’s history entry reopens the reader without adding a record, so one Back closes it and Forward can reopen it. That restore brings back the selected target, Sync Scroll, the visible pane and both reading positions, which the reader keeps on its own history entry once scrolling settles. The last explicitly chosen target language and Sync setting are also remembered in this browser for later openings; without storage the first target and Sync on apply. Back also cancels a reload restore whose reader script is still loading. A pane-local modal consumes Escape before the outer reader does. Fragment links stay in the pane without adding history and, like a native fragment jump, reveal the hidden tab panels that contain their target; another document exits comparison; external links open outside it. A localized loading note covers a pane until its article is readable. The iframe’s initial about:blank load is ignored while the target request is pending; a document still blank at the 15-second timeout is treated as failed. A page that cannot be loaded shows a localized Retry button and a direct link; choosing the same language again also retries it.

The accepted decision records the rationale and boundaries. bin/check-compare.py, the theme’s scroll geometry tests, and the site’s test:compare browser suite own verification. The dedicated eight-language fixture is synthetic evidence, not a downstream adoption claim.

Verification

bin/check-navigation-contract.py, bin/check-shell.py, JS tests, output goldens, and consumer browser tests verify these contracts. They cover navigation, language/subpath links, blog variants, page-end order, keyboard behavior, accessibility, and responsive layout.

Appearance control

The navbar and footer dock share one click/keyboard disclosure. The Landing mobile drawer also provides a labeled Appearance row. The panel offers native Style radios when preset_menu allows a choice and native Light/Dark/System radios when dark_mode.show_menu is enabled. Selection is immediate and keeps the panel open. Enter, Space, or ArrowDown opens it; arrow keys select within a group; Tab moves between groups; Escape closes and returns focus. Sun/moon trigger icons show the resolved current state: sun for light and moon for dark, including changes while following the system.

The English group labels are Style and Light. Style options are independent buttons in a two-column grid, with a colored page, layers, pen-nib or terminal icon and the preset name. There are no Aa previews or experiment badges. The site default is identified in its tooltip and accessible name; selecting it clears the saved preset. A tinted background and border show selection, and keyboard focus has a separate outline.

Desktop uses a non-modal dialog anchored to the trigger; outside press or focus leaving closes it. Below 768 px and inside the Landing drawer, showModal() opens a bottom sheet in the browser top layer with a close button and 44 px option targets. Closing the sheet preserves the underlying drawer. The surface coordinator closes unrelated popovers before opening. The t shortcut still toggles light/dark through switch_theme; switch_preset is the separate command-palette choice.

Fixed in OINK 1.3.0

A queued close event from an earlier appearance dialog must not clear the expanded state of a newly reopened dialog.

The Ink and Terminal experimental presets require explicit configuration; preset_menu: true continues to offer Paper/Slate plus the site default. Both reuse the same state, keyboard, command-palette and bottom-sheet mechanisms. Terminal compacts desktop navigation rows, while prose and mobile touch targets retain their sizes.

Expo albums

The new type: expo reuses this shell and adds image-album presentation. The Expo contract owns its content model, controls, and outputs.

Local component surfaces

OINK 1.4.0 aligns search/command rows, sidebar corners, and Appearance controls with the component geometry. Selected and hovered rows remain distinct, keyboard focus remains immediate, and preference storage, navigation, and palette selection are unchanged. No moving-highlight runtime is added.

v1.5.1 review corrections

These corrections shipped in v1.5.1 and are part of the current consumer contract.

  • Invalid manual_link_relref values warn and use the page permalink. Sidebar, section index, and navigation JSON share resolution, including deployment subpaths. Missing references must not stop an ordinary build.
  • Navigation JSON IDs and section-index lookup keys remove the deployment prefix before the language prefix. Explicit section order and cross-language identity remain stable with or without a directory for the default language. Published links retain both prefixes.
  • Version menus and commands share URL resolution. Page links remove the current deployment prefix before joining the target version URL, retaining the language path without duplicating the old version directory.
  • Blog indexes own their pagination: localized navigation contains ordinary links with aria-current, and head prev/next point to list pages. The article-sequence pager is omitted on blog lists. Archive pagination and its head links apply only to HTML. Print emits one complete section aggregate, without repeating it for each HTML archive page.
  • All navbar-only pages, including immersive blog articles, expose the mobile site drawer. Language, version, and repository links remain reachable there. Closed sidebar drawers cast no shadow into the viewport.
  • The groups icon policy includes the navigation root, top-level entries, and entries with children in both tree walkers. Deeper leaves omit icons.
  • A rail with no TOC, taxonomy output, or backlinks renders no empty panel or controls. Taxonomy-only rails retain collapse/expand controls labelled as sidebar actions, rather than TOC actions. Book TOCs suppress the browser’s list counter alongside authored numbering.
  • Escape dismisses language, version, and utility hover menus and returns focus to the trigger without reopening the menu. Copy, feedback, comparison loading, and Expo boundary controls preserve the focused element.

4 - Landing contract

The maintainer contract for landing data, the built-in section registry, language resolution, runtime, accessibility, and outputs.
OINK 1.5.1 contract

This contract describes OINK v1.5.1.

The architecture and component contracts define shared rules. The migration contract defines migration rules.

Shell and data

Any regular page may use layout: landing. It renders the navbar, a full-width content area, and footer without docs sidebars or TOC rails. The homepage can still use data/home/<lang>.yaml with the same renderer.

Non-home pages resolve sections in this order: inline front matter, data/landing/<key>/<lang>.yaml, exact-language entries in data/landing/<key>.yaml, then English or unsuffixed local data. Landing never fetches mutable facts. Commit or generate stars, prices, screenshots, and avatars before Hugo runs.

params.ui.landing_search defaults to true. It enables the existing local Palette only when offline_search is enabled. params.ui.github_stars and params.ui.alt_site are optional local interface facts.

Section registry

The registry has exactly 22 built-ins:

  • hero, metrics, capabilities, principles, cards, logo-wall, gallery, testimonials, contributors, faq, markdown, cta;
  • pricing, pricing-compare, command-box, steps, timeline, code-plate, preview, case-study, download, bar-chart.

An entry is a type string or a map with type, key, id, enabled, inline data, or an explicit local partial. Authors provide unique IDs. OINK converts them to anchor-safe values. Unknown types warn and use safe fallbacks. They never disappear silently. landing/ partials define built-ins. Removed home/ partial names are not an API.

preview displays Markdown source beside its RenderString output using site hooks. The content registers the same runtimes as docs content. The source pane uses Chroma and a file name, defaulting to page.md. Markdown output uses a four-backtick markdown fence. RSS omits it. Pane labels use theme i18n.

hero.align accepts start or center. Center alignment supports only text. Combining center alignment with an image warns, falls back to start, and preserves the image. download uses the shortcode’s data/download/<key>.yaml schema. It adds no second channel, version, publication, or interpolation model.

Language, runtime, and accessibility

Narrative files may be language-specific. Shared fact fields resolve <field>_<exact language>, with - converted to _, then <field>_<primary language>, then the unsuffixed field. camelCase aliases are not accepted. Narrative fields use site hooks to render inline or block Markdown. Values reused as accessible names become plain text. Section text is site data. Only theme controls use OINK i18n.

Each built-in Markdown render has a stable section, item, and field scope. Repeated bodies and marquee copies therefore get distinct generated code IDs, including their copy controls, titles, viewports, and line links. The scope does not depend on render order or output order. Explicit code IDs remain unchanged; repeating one in the assembled Landing output warns and keeps the page available. Custom partials that reuse the Markdown helpers should pass a distinct stable scope for each rendered position.

Block Markdown bodies use the shared .td-content component scope and register the runtimes their rendered content needs. Code folding, tables, images, and other content primitives retain their normal styles inside a Landing section. This scope belongs to the body, not the surrounding marketing headings or grid.

Interactive HTML sets hasLanding, which conditionally adds only landing.js. The runtime uses OinkSurfaceCoordinator for reveal, count-up, copy, compact-menu, and theme-image enhancements. Server output stays complete without JavaScript or if the Landing script fails to load. Reveal candidates are initially visible; only an installed observer may mark one as pending entrance animation. The server renders metrics with configured number formatting, prefixes, and suffixes, and the count-up’s final frame uses the same display.

Landing code plates accept keyboard focus in interactive HTML, including capabilities code visuals and code-plate line lists. Readers can tab to long lines and scroll them with arrow keys without relying on a browser’s implicit scroll-container focus behavior. Static Print output adds no focus target to these line-based renderers.

Marquee duplication uses only CSS. The duplicate is aria-hidden and inert. A localized checkbox preserves pause state without JS. Reduced motion disables animation. Forced colors preserve controls. Theme images follow the shared theme event. The navbar mega panel and columns menu parameter are retired. Menus with columns warn and keep one column. Compact menus use real links and buttons, trap no focus, and do not duplicate the desktop tree.

Outputs and compatibility

Output Contract
HTML Full static sections plus progressive enhancement
Print Static grids and content; controls removed
Markdown Headings, prose, lists, tables, and code without theme classes
RSS Valid RSS document when configured; Landing sections omitted

Non-HTML outputs set no Landing flag and load no Landing runtime. An enabled RSS output uses the shared feed renderer and matches the feed URL advertised in the HTML head. Section and home feeds keep ordinary child-page summaries; an explicitly enabled regular-page feed may have an empty channel. Omitting Landing sections never means emitting an empty file or advertising a missing feed. Root-relative links and assets honor deployment subpaths. Normal builds download no images.

Removed 0.4 forms belong to the migration toolkit, not parallel Landing implementations. OINK adds no pricing-period toggle, remote-fact API, hotspot editor, visual builder, or second registry. Existing homepage data and explicit custom section partials remain valid.

Visual presets

Paper removes the hero grid and glow, uses warm shadows, Plex Sans display headings, and a link-colored primary action. Slate retains its technical grid, glow, Chakra Petch headings, and original primary-action colors. Shared section geometry and density remain unchanged. The mobile drawer includes the shared Appearance sheet; see the shell contract.

The explicit Ink/Terminal experiments also remove the grid, glow and shadows. Ink uses heavy Inter headings, square cards and a red primary action. Terminal uses mono headings, 2 px corners and an amber primary action with a static cursor-shaped decoration. Neither adds animation or changes section columns.

Local action refinement

In OINK 1.4.0, button press feedback moves only the background; labels and hit targets stay fixed. Command-box copy labels reserve space for both idle and localized success text. The existing clipboard promise still controls success, and the copy action, live status, data model, and static-output boundary are unchanged.

v1.5.1 review corrections

These corrections shipped in v1.5.1.

HTML and text outputs share validation of record arrays for items, actions, and pricing tiers. Malformed records warn and are skipped. Missing optional pricing features and invalid comparison cells do not stop Markdown builds.

Landing links use the shared content URL policy before language and deployment prefixes are applied. Fragment-only and query-only links remain on the current page. Unsupported schemes warn and lose their link target. HTML and Markdown follow the same link semantics.

Only the first marquee row is exposed to assistive technology; repeated rows and duplicate groups are inert and hidden from the accessibility tree. Landing sections keep their fluid padding without legacy default-page section padding overriding it. FAQ focus indicators remain inside the clipped summary.

5 - Expo layout contract

Define album resources, display modes, image viewing, shared appearance, and static outputs.
OINK 1.5.1 contract

This contract describes OINK v1.5.1.

This page defines required behavior. Use Expo albums to create content. Read the design decision for the reasons behind this model.

Content and navigation

type: expo selects the album layout. A section can apply it to descendants through cascade. One album is a Hugo leaf bundle with index.md and an images/ directory. Image metadata belongs in the album’s resources front matter. Separate content files for each image are not required.

Section pages list child topics and albums. The shared navigation tree supports nested sections, the current language, and the mobile drawer. Expo uses the full available page width and has no right-hand outline. An explicit page-level page_width overrides the width. The top navbar follows the shared site and page settings. Expo does not disable it by default. As with Book, an album without a sidebar_root_for ancestor uses its top-level section, not the home tree, as the sidebar and root-switcher root.

Configuration

expo/config.html resolves the configuration in this order:

  1. Use the page’s expo block, including a block supplied by Hugo cascade.
  2. If the page has no block, use params.ui.expo from the site.
  3. Validate each field. Use its built-in default when the field is absent or invalid.

A page block replaces the whole site block. The resolver does not merge fields from those two blocks.

Field Allowed value Built-in default
images A string pattern for bundled image resources images/*
mode wall, cards, or seamless wall
size Integer from 160 to 360, in CSS pixels 240

Invalid configuration produces a warning and uses a fallback. The size is a layout target; it does not set both dimensions of each tile.

Image resources

expo/items.html selects images and resolves metadata for all outputs. It uses Hugo resource metadata and the shared media resolver. Non-image resources are excluded. An optional params.original must name an image in the same bundle. The build does not fetch remote album images.

Value Rule
Title Use the resource title; otherwise derive it from the filename
Alternative text Use params.alt; fall back to the title when it is empty or absent
Caption and credit Read params.caption and params.byline as plain text
Image order Sort by numeric params.weight, lowest first; the default is zero
Equal weights Keep the resource collection’s name order
Explicit ID Start with an ASCII letter or digit; subsequent characters can also be _ or -
Image anchor Prefix the ID with img-; without an ID, use a hash of the resource name

IDs must be unique within the album. An ID may be a string or a YAML integer. Invalid or duplicate IDs produce a warning and use a filename hash; if that hash is also occupied, the fallback appends the first unused numeric suffix. Renaming a file changes its fallback anchor. Keep an explicit ID and the album URL unchanged when a citation must remain valid. expo.images must be a nonempty resource glob, and params.original must name a bundled image even when its value is false or empty.

Processable images larger than 960 pixels receive previews within a 960 × 960 pixel box. GIFs also receive still previews for pause and reduced motion. The animated source remains available. Original files remain unchanged.

Album cards use the first sorted image as the cover. A section without its own images uses the first available image from its descendant albums. Cover frames use a 4:3 ratio and can crop the preview. Authors divide large collections into albums; Expo does not paginate image resources automatically.

Layout and controls

Mode Geometry and captions
Wall Rows of tiles with 6 CSS pixel gaps; captions appear on hover or focus on devices that support hover
Cards Columns filled from the shortest column; captions stay visible
Seamless The Wall calculation with zero tile gaps; the same caption behavior

Tile proportions are bounded for very wide or tall images. Each tile contains the complete image, which can leave space inside the tile. On devices without hover, captions remain visible below the images.

The toolbar has a three-cell radio group on one background. A play/pause button and a horizontal size slider follow it. Small and large image icons mark the slider ends. All controls share a vertical center. Albums without GIFs retain a disabled play button. Each icon control has a localized name, a tooltip where applicable, and visible keyboard focus. Cards and album covers use the preset’s radius token; Wall and Seamless tiles stay square. A focused tile shows a two-tone inset ring above its caption.

Appearance controls stay in the shared navigation. The album body has no appearance picker or article action menu. Without JavaScript, image links and captions remain visible.

Reader preferences and appearance

The browser stores the selected mode and size in td-expo-mode and td-expo-size. Only valid values take effect. A valid stored choice overrides the author default. It applies across albums and reloads on the same origin. Invalid or unavailable storage leaves the author defaults in effect.

Display mode and size are independent of appearance. Paper, Slate, Ink, and Terminal use the shared colors, type styles, and corner settings in light and dark mode. A preset change recalculates the grid after typography changes. It preserves the reader’s display mode and size.

GIFs play by default in the grid and viewer. The play/pause control changes animation for the current album and its viewer. The setting is not stored across page loads. prefers-reduced-motion: reduce starts with still previews. The reader can select Play. A change to the system preference updates playback. The first four tiles load eagerly; later grid images use lazy loading.

Layout stability

Expo reserves document scrollbar space when scrollbars consume layout width. An album near the viewport height must reach a stable layout. A scrollbar must not repeatedly appear and disappear as the grid recalculates its height. Opening or closing the viewer must preserve the underlying grid’s usable width.

Viewer behavior

The viewer uses a native modal dialog. Its image area excludes the toolbar and caption area. Let W and H be the original image dimensions. Let A and B be the available image-area width and height, in CSS pixels.

Action Scale
Open or reset min(1, A/W, B/H)
Expand to fit min(A/W, B/H)
Zoom in Current scale multiplied by 1.25, within the zoom limit
Zoom out Current scale divided by 1.25, within the zoom limit

The smaller ratio is the limiting edge. Both automatic sizing actions contain the whole image and have no image-area scrollbars. Reset keeps a small image at 100%. Expand can enlarge it. Expand does not use the browser Fullscreen API. Only manual zoom can exceed the image area and enable scrolling.

The percentage uses source pixels as CSS pixels. Zoom preserves the viewed center. Reset centers the image. Changing images resets size and position. Previous and Next stop at the album boundaries. A boundary key leaves the current scale and position unchanged.

Pointer and keyboard input

Hold the primary mouse button and drag to move an enlarged image. The image follows the pointer and stops at its bounds. Only overflowing axes can move. Touch input on an enlarged image retains native scrolling. Releasing or canceling the pointer, changing images, resetting, or leaving the window ends the drag. When the image fits the image area, a horizontal swipe of at least 48 CSS pixels changes images; pinches and a zoomed page do not.

Double-click or double-tap alternates between the initial size and a closer look. A shrunk original opens at 100% with the point under the pointer kept in place; an original already at 100% expands to fit. From any other size it returns to the initial size.

Viewer shortcuts apply inside the open dialog. They ignore text input, input method composition, and Ctrl/Command/Alt combinations. Page-level single-key navigation pauses while the dialog is open. keyboard_nav controls that page runtime; it does not disable Expo’s viewer runtime.

Key Action
W / A / S / D Move the enlarged image up / left / down / right, 80 CSS pixels per press
Q or H Previous image
E or L Next image
J or − Zoom out
K or + Zoom in
R or 0 Reset size and position
F Expand to fit and center
Escape Close the viewer

Left and Right arrow keys change images when no horizontal scrolling is needed. Otherwise, they retain native scrolling. Button tooltips show the applicable keys. In right-to-left languages the album order mirrors: the arrow key toward the start opens the previous image, swipes follow the same direction, and the previous and next icons mirror.

Open original links to the original file in a new tab. Locate in album closes the viewer, updates the URL fragment, scrolls to the current image, and focuses its trigger. Closing normally returns focus to the link that opened the viewer. The native dialog contains focus and prevents underlying page interaction. The underlying page cannot scroll while the viewer is open. The viewer registers with OinkSurfaceCoordinator: opening it closes other floating surfaces, and closeOthers() or closeAll() can close it. A handoff keeps focus in the newly opened surface.

While an original loads, the viewer shows the grid preview at the final size; a failed original keeps that preview. After an image loads, the viewer requests one neighbouring image on each side.

Expo loads its viewer and layout runtime only on HTML albums with images. Ordinary Image Zoom retains its single-image behavior and does not wrap Expo links again. Without JavaScript or dialog support, those links open the originals.

When changing images, clear the previous decoded image while the next original loads, and show the new grid preview at the final size. A failed original keeps that preview. Album prose and image headings remain separate Markdown blocks.

Other outputs

All outputs use the same image resolver. Enable each format through the normal OINK output configuration.

Output Image content
Print Still previews, titles, captions, credits, and original links; no Expo runtime
Markdown and LLMSFULL Original-image links and metadata
LLMS Album pages in the existing index
RSS Static image descriptions
Browser print Expanded album content with controls hidden

Authors translate album content and resource metadata. Image controls use the shared interface catalogs. The existing gallery fence remains an inline component with its own contract.

Acceptance and release boundary

Run the focused theme checks from the theme checkout:

python3 bin/check-expo.py
node --test tests/js/expo-geometry.test.js
python3 bin/generate-config-schema.py --check

Run site acceptance from the sibling documentation checkout:

make check
make browser

The bilingual examples are the integration and visual review surface. tests/browser/expo.spec.mjs checks interaction and accessibility. expo-stability.spec.mjs samples consecutive frames near the viewport-height boundary. It forces width-consuming scrollbars independently of host settings.

For the additional Chromium, Firefox, and WebKit checks, install the matching Playwright browsers and run from the documentation checkout:

HUGO_MODULE_REPLACEMENTS="github.com/pgsty/oink -> $(cd ../oink && pwd)" \
  npm run test:expo:engines

The separate Graph copy supplies additional large-collection evidence.

6 - OINK migration boundary

Supported source, configuration, and validation boundaries for OINK migration, including the 1.5.1 upgrade.
OINK 1.5.1 contract

This contract describes OINK v1.5.1.

This page defines the maintainer migration toolkit and configuration boundaries. See Upgrade for the reader-facing upgrade guide.

Toolkit scope

bin/migrations/oink06.py scans and automatically rewrites only Markdown in a site’s content directory, including supported YAML front matter. It does not rewrite Hugo configuration, data, layouts, assets, modules, or generated output. It reports TOML/JSON front matter and ambiguous Markdown with source positions for manual review.

Dry-run is the default. Completed migrations are idempotent:

python3 bin/migrations/oink06.py report --sites <dir>... --md report.md --json report.json
python3 bin/migrations/oink06.py migrate --site <dir>
python3 bin/migrations/oink06.py migrate --site <dir> --write
python3 bin/migrations/oink06.py check --site <dir>

Code-fence contents are not rewritten, including fences starting on the same line as ordered or unordered list markers, with optional blockquotes. An extra literal quote prefix within a code example does not close the fence. book_figures.py keeps narrow TPME, DDIA v1/v2, and pg-internal profiles. It is not a generic parser.

Before deleting existing output, bin/measure-baseline.py and bin/sites/build-all.py reject snapshot destinations that overlap protected locations. These locations include input sites, the running tools checkout, the selected theme checkout, and other snapshots. The check includes --keep destinations through symlink aliases and alternate --theme checkouts.

Updating consumer repositories

After publishing a theme release, inventory maintained consumer checkouts and update their exact pins. bin/update-consumers.py scans primary project directories under supplied roots and their site/ directories. It does not recurse into archives, generated sites, caches, or theme fixtures.

The tool ships with OINK 1.2.0. Run it from the theme checkout to inventory consumers and upgrade them to the published tag.

python3 bin/update-consumers.py v1.5.1 --roots ~/www ~/pgsty
python3 bin/update-consumers.py v1.5.1 --roots ~/www ~/pgsty --write --check --check-appearance

The first command only reports adoption. The second updates go.mod and OINK’s go.sum entries, verifies the exact module graph, and builds selected sites with fatal warnings. It disables GOWORK, Hugo’s module workspace, and environment module replacements. Logs and original module files go to a temporary report directory or the explicit --report-dir. Failed updates restore module files. Failed builds keep the new pin for diagnosis and return failure. Unreadable roots or malformed consumer modules become failed entries. Inventory continues through other sites and exits nonzero. Explicitly selected missing or non-consumer directories also fail visibly.

Linked worktrees, hidden copies, and non-default branches are skipped. Review every skipped or blocked entry. An explicit project root resolves to its site/ directory when that directory contains the Hugo site and the root is not itself a Hugo configuration or OINK consumer. An unrelated Go application’s root go.mod does not prevent this resolution. An actual root consumer takes precedence. --sites <path>... selects a reviewed site explicitly, including checkouts with existing module edits and source directories without Git. Source-only directories are skipped during automatic discovery until selected explicitly; they receive the same file backups and build checks. Classic themes/oink consumers are listed for separate maintenance: update a clean Git submodule to the published tag, or back up and replace a verified upstream source copy. Preserve offline builds and site-level overrides, then run the owning site checks. The module updater does not rewrite classic theme directories. Manually resolve OINK replacements in go.mod. Review vendored themes separately before --refresh-vendor, which backs up and regenerates _vendor/. Changing a module pin alone does not update vendored themes. Hugo’s resolved module graph determines whether OINK actually uses vendor output. A retained snapshot bypassed by ignoreVendorPaths is preserved and does not block a published-module upgrade.

To offer all four styles with Paper as the site default, set the site configuration explicitly:

params:
  ui:
    preset: paper
    preset_menu: [paper, slate, ink, terminal]

preset_menu: true offers the stable styles and the site default; the explicit list also opts into Ink and Terminal. These settings persist across later pin upgrades. Review sites with a custom shell separately: configuration alone does not add appearance controls to templates that bypass OINK’s shell.

The maintainer checkout also supports --check-appearance together with --check. It checks the fresh rendered home pages, including localized entries, for Paper as the default and all four style controls. Sites that disable Home are checked at their documentation entries; redirect aliases are omitted. Browser interaction and each site’s owning checks remain separate.

Preserve unrelated work. Update current theme-version references in site READMEs and configuration. Run each site’s owning checks and visual review. The tool updates module pins and runs build checks without editing content or committing.

0.4 content to current forms

Removed form Current form Toolkit key
alert, details, pageinfo, raw disclosure > [!TYPE] callout callout
tabpane, legacy tab, code-group, code-tab adjacent {tab=} blocks or tabs / tab tabs
FileTree shortcodes or {.filetree} list filetree fence filetree
Gallery shortcodes or {.gallery} list gallery fence gallery
ECharts / infographic shortcode same-named data fence datafence
Docsy card families .cards list or cards / card cards
imgproc, image Markdown image + attributes image
readfile include include
fence filename= title= fencetitle
badge outline= remove outline badge
leaf example, book-figures kind= eg, explicit book-* index eg
percent-delimited fields angle-delimited fields / field fieldsdelim
Docsy _param placeholders and card header= highlights Font Awesome / badge / param or callout param_placeholders
unsupported legacy shortcodes manual review with source position reportonly

Configuration and front matter

Make these configuration changes manually. The toolkit may report matching front matter keys but never edits site configuration.

Old Current
offlineSearch* offline_search*
disable_click2copy_chroma ui.code_copy (inverted)
content_width `reading_width: slim
github_url github_repo
ui.no_left_sidebar ui.sidebar_enabled (inverted)
breadcrumb aliases ui.breadcrumb
ui.scrollSpy No behavioral replacement; ui.scroll_spy remains a quiet 1.x compatibility no-op
ui.showLightDarkModeMenu ui.dark_mode.show_menu
ui.readingtime ui.reading_time
ui.ul_show ui.sidebar_expand_levels
ui.docs_root ui.docs_sidebar_root
ui.pager ui.pager_types
{ enable: bool } annotation/zoom/keyboard/reading maps bare booleans
ui.typography.preset ui.typography
print.disable_toc print.toc (inverted)

Prism, rss_sections, and algolia_docsearch are removed. Chroma is the only highlighter. Algolia configuration uses search.algolia. Page overrides omit ui.. Legacy hide_feedback, hide_readingtime, exclude_search, content_width, camelCase manual links, and nested front matter ui maps are reported with replacements.

0.5 to 0.6

  • Replace upstream_attribution with upstream_link plus upstream_name, upstream_copyright, upstream_license, and upstream_notice; rename downstream_modified to upstream_modified.
  • Replace the release map with one GitHub release_url; remove release_products and release_group_by_product from release indexes.
  • Blog and default dates now default to ISO 2006-01-02; retain explicit time_format_blog or time_format_default for prose dates.

Removed names warn and use the documented safe fallback or render nothing, allowing ordinary previews to continue. blog_index_toggle, featured_image: hero, toc_style, and toc_taxonomies are additional opt-ins. They add no content type. Immersive reading remains on the ordinary blog shell.

Prerequisites and validation

Enable Goldmark unsafe rendering, block attributes, and standalone block images as specified in the component contract. Enable passthrough explicitly for \(...\), \[...\], or $$...$$. Hugo does not merge theme markup configuration.

Run the smallest source and output checks for the changed contract with pinned Hugo Extended 0.168.0. For runtime changes, also run JS tests. Run production root and subpath builds. For maintained sites, inspect representative EN/ZH Docs and Blog routes at desktop and narrow widths.

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

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

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

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

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

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

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

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

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

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

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

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

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

8 - Design research

Dated experiments and consumer evidence that inform OINK design decisions.
Dated research records

Research records capture measurements, inputs, and tool versions from specific studies. Current behavior is defined by the Design contracts and validated on Hugo Extended 0.168.0 per the toolchain contract.

Publish research in the Design tree only when another maintainer can inspect its method, understand its scope, and repeat the applicable check. Keep raw agent transcripts, temporary build logs, and local absolute paths out of research records.

Research map

Record Evidence
Goldmark block attributes Render-hook visibility and CommonMark container limits on the historical Hugo versions recorded in the study
Consumer and migration evidence A dated corpus survey plus deterministic Book migration results
Comprehensive review, 2026-08-26 Implementation, configuration, output, security, test, performance, and doc audit
Community issue and PR review, 2026-09-19 Reproductions, PR acceptance advice, and remedies for sidebar, focus, and search feedback
OINK 1.1 release review, 2026-09-20 Five runtime repairs, documentation readiness, validation evidence and publication boundaries
CLI acceptance snapshot, 2026-09-29 Executed Starter, real-site, offline, upgrade, and reproducible-archive checks for the local CLI candidate
Visual preset acceptance, 2026-10-05 Paper/Slate local implementation, actual output and bounded browser evidence
Ink and Terminal experiment, 2026-10-05 Explicit experimental presets, design tradeoffs and real-site verification
OINK 1.2 pre-release review, 2026-10-05 Final local candidate checks, cleanup, local resources, compatibility and publication boundaries
CLI maintenance acceptance, 2026-10-03 Historical R1–R8 and A18 source-bound runtime and archive evidence
Theme review, 2026-10-13 Reproduced output and interaction defects, repairs, and local validation scope
Component refinement, 2026-10-25 Final component acceptance, 409 Chromium tests, targeted three-engine visual review, CSS/JS size comparison, and separate gallery baseline failures
Document comparison, 2026-10-29 Dated source review behind the translation comparison decision; historical, not the released contract
Review repairs, 2026-11-06 Reproduced v1.5.0 defects, bounded development repairs, validation and remaining work
OINK 1.5.1 readiness, 2026-11-06 Three repaired candidate regressions, owning checks, browser acceptance, publication evidence and release gates

Publication rules

A research record states its date, inputs, applicable versions, method, result, and known limits, with changing counts labeled as snapshots. External framework comparisons should be refreshed from primary sources before publication and focus on conclusions that affect OINK.

When a result becomes an accepted product choice, link it from an accepted decision. If it proposes behavior that does not exist, move the design question to Proposals.

8.1 - Goldmark block-attribute evidence

Repeatable probes of lists, images, tables, passthrough blocks, fences, callouts, and nested containers on Hugo 0.160.1 and 0.164.0.
Verified snapshot

These probes produced identical relevant output bytes on Hugo Extended 0.160.1 and 0.164.0. They explain OINK’s native component forms. The current component contract defines required behavior.

Method

The probe used a minimal Hugo site without OINK templates, with render hooks printing their context fields and .Attributes as visible markers. The site enabled Goldmark block attributes and passthrough delimiters for inline and block math, allowed unsafe rendering to inspect raw HTML, and set wrapStandAloneImageWithinParagraph: false.

Each source shape was rendered with the minimum supported Hugo and the then current Hugo version, comparing relevant output byte for byte to record Goldmark’s structural behavior.

Findings

Source shape Hook result Design consequence
Ordered list with paragraphs, fences, callouts, nested lists, and {.steps} The class attaches to the outer <ol> and rich list-item blocks survive A Markdown list is the native Steps form
Heading inside a list item The heading remains inside <li> and enters .TableOfContents Native Steps can carry navigable headings
Nested list with {.filetree} The class attaches to the outer <ul> FileTree needs no outer wrapper to preserve hierarchy
Standalone image plus {#id num= caption= .class} render-image receives IsBlock=true and all attributes A Book figure can have a native image form
Inline image inside a paragraph IsBlock=false; the image receives no block attributes Inline images cannot use the block-figure contract
Block math plus {#id num=} render-passthrough receives block type and attributes A numbered equation can use the native passthrough form
Table plus {.fields #id num= caption=} render-table receives the class and named attributes Field tables, matrix markers, captions, and Book numbering can share one hook
Fenced code plus {#id num= caption=} The code-block hook receives the attributes A numbered example can be the fence itself
Callout plus {icon= tab=} The blockquote hook receives callout metadata and attributes Folding, inline title markup, icon, and tab metadata can coexist
Attribute line separated from its block by a blank line The attribute silently disappears Source checks must reject orphan attribute lines
Adjacent tables with tab= Each table hook receives its own tab label Adjacent-block tabs can extend beyond code fences

Container boundary

Hugo’s % shortcode delimiter renders .Inner as Markdown. Its template must put a blank line before and after the inner Markdown. Without both blank lines, Hugo may treat a following list as literal HTML-block content instead of Markdown.

A multi-line % container inside a CommonMark list item has another limitation: its generated HTML lacks list-content indentation, so the list closes before the container and restarts after it. OINK therefore keeps a full Steps form for steps that must contain another full container. Ordinary rich blocks, fences, and < shortcodes do not have this limitation.

In the applicable collector shape, nested % shortcodes receive inner HTML that is already rendered. If a collector requires the child’s original Markdown, it uses < delimiters and renders the captured body through the shared scoped block renderer.

Attribute ownership

Each hook enforces an explicit attribute allowlist, rejects style and inline on* handlers, and validates URL-bearing values through the shared URL policy. A hook retains a site class only where downstream CSS is an established extension mechanism.

The experiment showed that gallery images inside list items can be block images, but the image hook still does not receive their parent list’s marker. A runtime therefore relies on a theme-emitted marker or a structural fallback.

Limits and verification

These results cover Hugo 0.160.1 and 0.164.0 with the stated Goldmark settings. Before updating this snapshot for a minimum-version change, rerun the focused component, Book, table, gallery, and Markdown-output checks.

8.2 - OINK 1.3.2 and Hugo 0.168 consumer inventory

Local inventory of 37 maintained OINK sites using v1.3.2 and Hugo Extended 0.168.0, with visible warnings and separate publication evidence.

This dated inventory records local checkouts under ~/pgsty and ~/www. The current build policy is owned by the architecture contract and diagnostics decision.

Baseline

OINK v1.3.2 was published on 2026-10-18 at 13:37 UTC. Its tag resolves to bd2e856e6e2f7027a9189af009701f5b8cf562cf. All maintained sites use this release and Hugo Extended 0.168.0. CI, local checks, preview, and deployment commands omit the warning-fatal flag; HUGO_PANICONWARNING must also remain unset. Warnings stay visible for review. The upstream LibSass deprecation notice is accepted. No external Sass compiler is required, and older Hugo versions are no longer development targets.

The observed local tools were Hugo 0.168.0+extended+withdeploy on macOS arm64 and Go 1.27.2. Module verification disabled environment replacements and both Go and Hugo workspaces. Classic consumers were compared with the release’s runtime sources. All 37 builds preserved Paper and the explicit four-preset reader menu.

Sites

Paths are relative to the home directory. Every row uses OINK v1.3.2 and Hugo Extended 0.168.0. “Module” means the resolved public module; “copy” and “submodule” identify classic themes/oink consumers.

Checkout Theme source Local production build
pgsty/barn.pgsty.com module Passed
pgsty/boar.pgsty.com module Passed
pgsty/caps.vonng.com module Passed
pgsty/cloudexit.org module Passed
pgsty/exp.pgsty.com module Passed
pgsty/oink-starter module Passed
pgsty/oink.pgsty.com module Passed
pgsty/pgetcd.pgsty.com module Passed
pgsty/pgext module Passed
pgsty/pgredis.pgsty.com module Passed
pgsty/pgsilo.pgsty.com module Passed
pgsty/pgsty.com module Passed with local report data; see below
pgsty/pgsty.pro module Passed
pgsty/pig.pgsty.com module Passed
pgsty/pigsty.cc module Passed
pgsty/pigsty.io module Passed
pgsty/repo.pgsty.com module Passed
pgsty/silo.pgsty.com module Passed
pgsty/sow.pgsty.com module Passed
pgsty/wok.pgsty.com module Passed
www/aiempire module Passed
www/ca.vonng.com submodule Passed
www/ddia module Passed
www/dharma module Passed
www/doc.pg.center module Passed
www/fzb/site copy Passed
www/lzj module Passed
www/muse.vonng.com copy Passed
www/pg-internal module Passed
www/pg36g module Passed
www/pgweekly module Passed
www/piglet.run module Passed
www/sg.vonng.com submodule Passed
www/tpme module Passed
www/us.vonng.com submodule Passed
www/vonng.com module Passed
www/zj module Passed

Boundaries

  • pgsty.com could not fetch its separately published report manifest: the remote request returned an unexpected EOF or timed out. Its build passed with the existing local report dataset and HUGO_REPOORT_USE_LOCAL=1.
  • sow.pgsty.com was checked on its existing publication-review branch. Non-Git and source-copy consumers were validated in place.
  • pgsilo/work/silo-docs is a frozen delivery baseline, as its owning repository documents. It is excluded from maintained-site upgrades.
  • This inventory records local source, module-resolution, build, and rendered-menu verification against the published v1.3.2 tag.

8.3 - Ink and Terminal experiment, 2026-10-05

Explicit experimental presets in real theme output, their design tradeoffs, checks and remaining work.
Local experiment record

Ink and Terminal compile into the theme stylesheet and use the Appearance control. They remain explicitly enabled experiments, pending design acceptance.

Inputs and method

This extends the Paper/Slate implementation on the October 5 working trees. Tools: Hugo Extended 0.166.0, Go 1.27.1, Node 26.9.0, and Playwright 1.62.1 on macOS ARM64. The documentation site’s local sibling-theme build is the integration surface; its published pin remains v1.1.0.

The same Home, configuration, callout, and tab content is compared across four presets, EN/ZH, 390/1440 px, and light/dark mode. Checks inspect real rendered fonts, overflow, appearance controls, and local font requests. Further component checks cover code, parameter fields, Blog, Book, API, Mermaid, ECharts, search, and print. API vendor DOM is excluded from axe under the site’s existing policy.

Design choices

Choice Improvement Cost / limit
Ink: black/white canvas, Inter, red markers, underlined prose links, strong heading rules Clear hierarchy and link affordance with little decoration Heavier headings and repeated rules need long-page editorial review
Terminal: mono controls/headings, sans prose/tables, teal links and amber emphasis A recognizable technical interface while retaining paragraph readability Long Latin navigation labels wrap sooner; CJK uses platform fallback faces
Square Ink geometry, 2 px Terminal geometry, no component shadows Visibly different surfaces using the same content and layout Scoped component rules add CSS; no global spacing/radius token layer
Compact Terminal desktop navigation only More useful navigation rows without shrinking article text Density is fixed per preset
Existing local fonts and state handling No new font files, external font service, framework or persistence mechanism All preset CSS remains in one stylesheet
Explicit experimental menu entries Reviewers can switch immediately without changing ordinary menu choices Four cards make the enabled menu taller

Ink uses #ffffff / #0b0b0b canvases, #141414 / #ededed text, and #c8102e / #ff5c4d accent. Terminal uses #f4f5f2 / #0c0f0e canvases, #1d211f / #d3dbd6 text, #0a6560 / #4cc9bd links, and #935400 / #f0a73a accent. Site/section accent overrides still win. Terminal’s heading markers use empty accessible alternatives; unsupported engines omit them. Its hero cursor is a static shape, with no typing, blinking, scanlines, or glow.

Try it

params:
  ui:
    preset: paper
    preset_menu: [paper, slate, ink, terminal]
    dark_mode: true

The local docs site enables this list. Select Ink or Terminal in Appearance, then choose light, dark, or system independently. Following the October 5 menu revision, all four options use icon-and-name buttons without experiment badges. A site may set either as preset without enabling reader choice. preset_menu: true remains Paper/Slate plus the site default. Selecting the site’s default preset clears the saved preset. Font overrides, system typography, and pre-CSS initialization use the same contracts as Paper/Slate.

Verification

Executed check Result and scope
check-presets.py AA text/link/accent contrast on three surfaces, light/dark token parity, advisory canvas luminance, frozen Slate v1.1.0 palette; seven strict builds and 28 document roots
Theme checks Parameters, font roles, 32 catalogs with 205 keys, generated schemas, component/output contracts, runtime isolation and namespace passed; 52 existing output goldens unchanged
Runtime tests 49 Node tests passed
make check 57 non-browser tests passed; EN/ZH coverage 142/142, Markdown, rendered content and internal links checked
Standard browser suites Eight suites passed 170 tests; the appearance suite passed all 49 after fixing the default-Terminal build issue below (219 checks total across the initial run and focused rerun)
Appearance coverage Four presets × EN/ZH × 390/1440 px × light/dark on Home, configuration, callouts and tabs; local font requests and menu axe checks; state, keyboard, print and Giscus asset checks; four experiment/mode checks over 11 page types plus search, and shared Mermaid contrast
Font/configuration builds Actual docs site rebuilt with Terminal as default: system fonts with/without explicit overrides, plus explicit technical-font overrides; all three passed
Browser engines Six checks passed on Chromium, Firefox and WebKit at 390/1440 px, including pre-CSS state, keyboard selection through Ink/Terminal, persistence and focus return; desktop Chromium also used 4× CPU throttling
Visual review 96 actual-output viewport captures; representative Home, Docs and mobile menu images inspected. The local comparison gallery selects content, language, size and mode without injecting styles

The standard sitemap axe pass used 15 routes: EN/ZH Home, configuration, callouts, tabs, and OpenAPI; English search, Mermaid, ECharts, Blog, and /book/04-design/. The existing responsive axe matrix also ran. Standard browser checks used the 4173 fixture server; the engine gate used the sibling-theme dev server at port 1313. No external font request was observed in the appearance matrix.

The first default-Terminal font build found an omitted entry in the advisory canvas-luminance map, causing false accent-contrast warnings. Both experimental canvases now participate, with checker assertions and authored-accent fixtures. Only the affected appearance suite was rerun after this correction. The added research index entry and updated proposal description were reviewed before refreshing the corresponding two changes in the LLMS golden.

The experiment exposed two new styling faults: the global underline suppression hid Ink’s links, and Terminal’s selected search row retained dim summary text. Both received scoped fixes. A separate inherited Mermaid dark-label pair (#cccccc on #585858, 4.43:1) reproduced in Paper and Slate. The shared mode-only default label background is now #404040; authored Mermaid values retain priority.

Remaining work

Before stable promotion, review the look on real Windows and Android devices, including CJK fallback faces, underlines, mono heading wraps, and long parameter tables. Manual screen-reader speech and first-paint filmstrips remain unverified.

Mermaid/ECharts keep mode-only palettes, API widgets keep vendor styling, and Giscus coverage checks generated palette assets. The decision to promote Ink/Terminal or redesign chart palettes remains open.

8.4 - OINK 1.2 pre-release review, 2026-10-05

Local 1.2.0 candidate review, cleanup, compatibility, resource provenance and publication checks, with release boundaries.
Local candidate review

This review covers the October 5 working trees prior to tagging v1.2.0. The public theme tag and the documentation site’s consumer pin were still v1.1.0 at review time.

Scope and inputs

The theme starts at a1979a4 and the documentation site at ed2d0e3. The reviewed working trees also contain the CJK keyword-summary, literal-percent outline, and repository-source-path fixes, the site’s existing English editorial changes, and the cleanup below. The separate optional CLI is outside this theme release.

Most checks used Hugo Extended 0.166.0, Go 1.27.1, Node 26.9.0, and Playwright 1.62.1 on macOS ARM64. Official, checksum-verified Hugo Extended 0.160.1 and 0.165.0 binaries were used for selected compatibility checks.

Review findings and cleanup

Finding Correction Impact
The 1.2 release draft omitted the new default and appearance controls Update both release drafts and upgrade guidance with Paper, the Slate compatibility setting, independent persistence, current-state icons and experimental preset selection Readers can identify the visible upgrade change before adoption
Current proposal, decision, experiment and source comments still described preview letters, experimental badges, a separate Default card or an undecided release target Align current descriptions with compact icon/name buttons, site-default reset and 1.2 release preparation; preserve dated test evidence Guidance agrees with the accepted interface while keeping historical results intact
A working-tree ignore rule hid all site tests/ except two files Remove that broad rule; retain existing generated-output exclusions New regression tests remain visible to Git
Development previews do not expose production-only analytics Inspect strict production output and distinguish core local resources from explicitly configured services The local-first boundary is verified against production output

These cleanup findings required no runtime change. Earlier working-tree runtime fixes are covered by their owning checks and the final integration run.

Executed verification

The local candidate passed the following technical pre-release checks. No release-blocking theme defect was found within this scope. Counts are dated snapshots of this working-tree review.

Check Result and scope
Preset checker Passed: seven warning-strict configuration builds, 28 document roots, light/dark token parity, AA text/link/accent checks on three surfaces and the frozen Slate v1.1.0 base palette
Runtime tests 49 Node tests passed, including current-state icons, search summaries, outline tracking, clipboard and dialog focus
Theme regression and tooling checks 40 checker/tool commands passed, including 90 migration tests, snapshot/consumer safety and current output goldens; the PDF browser case was then rerun with an explicit browser, with all three isolation tests passing
Documentation checks Final make check: 57 tests passed; 143/143 bilingual files, 1,197 source headings, 228 rendered content pages and internal links checked; only the new research index entry and changed release title/description required reviewed Markdown-golden updates
Standard browser suites One complete make browser run passed all 219 checks across nine suites, including the full 372-route sitemap axe scan; no failed, flaky or skipped cases
Documentation follow-up A fresh build passed a separate axe scan of 14 updated EN/ZH routes, including this new report pair
Browser engines Six appearance checks passed on Chromium, Firefox and WebKit at 390/1440 px; pre-CSS restoration, keyboard selection, persistence and focus return; desktop Chromium also used 4× CPU throttling
Visual spot checks Current-output captures inspected for the Chinese mobile Paper menu, English desktop dark Paper menu and Chinese Terminal reading on mobile/desktop; two-column icon/name options, current-state icons and reading layout confirmed
Hugo compatibility floor 0.160.1 passed preset and reading/math checkers plus a strict minified production build of the actual documentation site
CI Hugo version 0.165.0 passed a strict minified production build of the actual site, Hugo Module/include/static/print checks, system typography, legacy Sass font overrides and expected rejection of invalid typography
Production resources 28 page visits across four presets and seven routes; core fonts and scripts served from the site’s origin; configured external services recorded separately
Production output security Passed on 921 files in the final strict production build with the documented third-party integration policy
Book publication Root and subpath EPUBs passed the theme checker and EPUBCheck 5.3.0 with zero errors/warnings; both PDFs passed the 23-page, five-chapter structure checks; the root PDF script-isolation probe passed
Published consumer pin Existing v1.1.0 resolved and passed the site’s release-pin check with environment replacements and both workspaces disabled

The full sitemap scan follows the site’s existing axe policy: OINK-maintained surfaces are checked, Giscus requests are blocked, and Swagger UI/Redoc vendor DOM is excluded. Responsive checks cover 360, 768, 820, 1024, 1200, and 1440 px in English/Chinese and light/dark mode.

Appearance checks use the same Home, configuration, callout, and tab content in four presets, both languages, 390/1440 px, and light/dark mode. They also cover search, code, tables, input/focus states, Blog, Book, API, diagrams, and print. Ink and Terminal remain explicitly selected experiments.

Publication used local Pandoc 3.11, Java 26, and Chrome headless-shell 151.0.7922.34. The first attempt with the full Chrome for Testing application timed out on this Mac. Selecting headless-shell explicitly, as CI does, produced the verified PDFs. CI pins Pandoc 3.10 and Java 21 on Linux.

Local-first resource boundary

IBM Plex Sans, Inter, IBM Plex Mono, Chakra Petch, icons, KaTeX fonts, and core browser libraries are bundled locally. Preset switching introduces no runtime font-service or CDN-script dependency. System typography and explicit font-role overrides retain their documented precedence.

The production audit loaded Home, Chinese configuration, math, Mermaid, Markmap, ECharts, and OpenAPI under each preset, then switched dark/light mode. The production base origin was preserved while built files were served locally. Request tracing recorded and blocked off-origin requests; local fonts and diagrams still loaded without uncaught JavaScript or local HTTP errors.

Two configured services requested external scripts: Giscus and Google Analytics. Giscus is an optional comments integration; its OINK palette files are local. This documentation site configures an analytics ID, so production output includes Google Tag Manager’s script. Neither service is required by the new presets. Authored remote media and explicitly selected diagram services retain their opt-in boundaries.

Repeating the checks

Run owning theme checks before the real-site checks. These commands use the sibling theme through the documented Make targets:

python3 bin/check-presets.py
node --test 'tests/js/**/*.test.js'
make -C ../oink.pgsty.com check
env -u A11Y_PATHS -u PLAYWRIGHT_BASE_URL make -C ../oink.pgsty.com browser

The full theme checker set and publication commands are defined in .github/workflows/ci.yml. Run all owning checkers with fresh fixtures, including parameters/schema, vendored assets/fonts, navigation/search/actions, components, output/namespace/goldens, migrations, snapshot protection, consumer tooling, and PDF isolation. The engine suite is npm run test:appearance:engines in the site repository.

For compatibility checks, put the selected Hugo binary on PATH, disable inherited Go/Hugo workspaces, and identify the sibling replacement explicitly. Build the real site with --environment production --minify --printPathWarnings --panicOnWarning into a separate output directory. For published-pin checks, disable the replacement as well.

Remaining release steps and limits

Local technical pre-release acceptance passed. Completing the release requires assembling reviewed changes into commits, running CI on those commits, publishing the tag and module archive, updating downstream pins, and verifying the hosted deployment.

Real Windows/Android font rendering, manual screen-reader speech, and first-paint filmstrips remain unverified. Windows source-path behavior was checked through deterministic fixtures. Ink/Terminal design follow-up remains in the experiment record.

8.5 - Visual preset acceptance, 2026-10-05

Local Paper and Slate verification, real theme output, and bounded browser evidence.
Local verification record

This record covers sibling-checkout theme output for the Paper and Slate presets prior to tagging v1.2.0.

Inputs

Theme and documentation working trees on 2026-10-05; Hugo Extended 0.166.0, Go 1.27.1, Node 26.9.0, and Playwright 1.62.1 on macOS ARM64. The ordinary browser suite uses Chromium; the additional engine gate uses Chromium, Firefox, and WebKit. The site pinned v1.1.0 at the time of this run; make check, make browser, and make dev select the local sibling theme.

Executed checks

Evidence Result and scope
check-presets.py Paper light/dark token parity and AA text/link/code/copper contrast; frozen v1.1.0 Slate base palette; four strict configuration builds and 16 HTML roots including 404 and print
Existing theme checkers Parameters, font roles, vendor inventory, 32 locale catalogs, actions, shell, output, namespace, Landing and runtime isolation passed; generated schemas match their sources
check-goldens.py 52 surfaces passed after reviewing and updating the 34 HTML/print expectations affected by root attributes, prepaint colors, the menu and its action/runtime; other output formats were unchanged
Strict site build Real sibling-theme EN/ZH site built with --panicOnWarning; translations, rendered Markdown and internal links passed
node --test 'tests/js/**/*.test.js' 49 runtime tests passed
appearance.spec.mjs 25 tests passed: Paper/Slate × EN/ZH × 390/1440 px × light/dark on Home, configuration, callouts and tabs; menu axe checks; keyboard, persistence, default reset, language navigation, cross-tab sync, blocked storage, invalid values, no JS, print, command palette, reading-anchor/breakpoint handling and generated comment stylesheets
appearance-engines.spec.mjs Six checks passed: Chromium, Firefox and WebKit at 390/1440 px; stored state and browser chrome color restored before CSS, native keyboard selection, focus return and language navigation. Desktop Chromium also used 4× CPU throttling
Font requests All observed fonts were local. Paper requested no Inter; Slate requested no Plex Sans. Two real-site overlay builds proved system typography requests no bundled text face and explicit font roles override both presets
make check Complete non-browser suite passed: 57 tests, 141/141 translated pages and the existing Markdown/rendered-content/internal-link checks
make browser 197 tests passed across all nine standard suites; sitemap axe scan scoped to the 15 routes below
Visual inspection Actual Paper desktop Home, mobile long-form Docs, English/Chinese light/dark Appearance panels and Slate dark Home reviewed from browser test captures

The browser suite’s sitemap axe pass is scoped with A11Y_PATHS to 15 representative routes: EN/ZH Home, configuration, callouts, tabs, and OpenAPI; English search, Mermaid, ECharts, Blog, and a Book chapter. The existing responsive axe matrix runs in addition. Cross-origin Giscus and vendor API widget DOM retain the suite’s established exclusions.

The integration run found and fixed Paper dark highlighted-line gutter contrast and smooth-scroll interference with reading-anchor restoration. Theme-color checks now assert both presets: Paper’s opaque warm selection surface and Slate’s existing translucent selection surface.

Limits and next checks

Manual screen-reader speech and visual filmstrip/paint traces remain unverified. The blocked-stylesheet and throttled-CPU assertions verify initialization order. Slate comparison freezes base palette values and verifies rendered font behavior.

Mermaid/ECharts retain mode-only palettes. Ink and Terminal remain research; serif display headings, full geometry/density tokens, and preset-colored charts remain future work.

8.6 - Consumer and migration evidence

A dated consumer corpus survey that informed OINK shells, authoring primitives, and deterministic Book migration rules.
Dated corpus snapshot

These counts describe repositories inspected in August 2026 to inform OINK’s shell, component, and Book migration design.

Corpus

The authoring survey scanned the content/ trees of eleven OINK consumer sites and found 5,325 Markdown files, of which 5,293 had YAML front matter. The survey included single-language English and Chinese references, bilingual product sites, release archives, custom landing pages, and separate Book consumers.

The survey measured source Markdown, counting shortcode calls, fenced-code attributes, callouts, table markers, raw HTML, front-matter keys, content types, and site-local layouts. A later Book-focused survey added five long-form consumers.

Findings that changed the design

Evidence Resulting choice
Content ranged from nearly plain Markdown to pages with many nested components Native Markdown is the default form; a full form survives only for a named capability gap
Documentation, Blog, Landing, releases, and books repeatedly reimplemented navigation or cards locally Extend the shared shell, registry, and primitive rather than adding a parallel system
Site-specific table classes were common, while canonical Field-table headings were rare Hook attributes use an allowlist but preserve documented site-class extension points; Fields cannot be inferred from arbitrary two-column tables
Book sites carried private figure, table, equation, example, and cross-reference conventions Numbered primitives and migration profiles need deterministic classification, stable IDs, and rendered-target verification
Sites mixed single-language, peer-file bilingual, and generated-language content Language authority and generation boundaries must be explicit; a migration never treats an untracked generated tree as source
Rich HTML pages still needed print, Markdown, feeds, and agent output Every component declares its output degradation before its interactive HTML is accepted

The evidence also ruled out several additions: documentation sites did not require a second Landing system, Book sites did not need a new cover component, and a serial archive did not require a new shell type. Remote API collection belongs in site-side CI, outside a Hugo theme built for local rendering.

Block and table evidence

A focused survey of eleven sites plus Book consumers found 11,484 pipe tables, but only eleven matched the strict Field-table heading vocabulary. Roughly 874 were reference-style tables and about 1,300 were compatibility matrices. OINK therefore uses explicit .fields and .matrix markers rather than inferring these components from table shape.

The same survey found eighteen Steps blocks in the eleven-site corpus, all using the full form with headings and rich content. Platform probes showed that a native ordered list could contain most of that content, but not another full % container inside a list item. OINK keeps both forms because their technical capabilities differ.

Deterministic Book migration

Three dated dry-run profiles checked whether migration rules accounted for every recognized source without inventing meaning:

Profile snapshot Classified result Manual boundary
DDIA v2 106 figures, 3 tables, 22 code examples, and all 304 relevant links accounted for One caption link flattened to visible text; no unaccounted skip
DDIA v1 90 numbered figures and 203 matching references 14 decorative or unnumbered images deliberately left alone
TPME 31 figures, 10 tables, 44 numbered references, and 1,018 generic stable references No skipped recognized item
Private Book profile 119 figures, 5 tables, and 136 numbered references 3 ambiguous images retained for manual review

Each profile first ran without writes, and writes began only after reviewers understood its ambiguous inputs. A second run produced zero changes. Each profile built with warnings fatal and passed rendered kind/number/anchor checks. The public migration toolkit and current profile boundaries are documented in Writing a book and the migration contract.

Publication adoption snapshot

An isolated 2026-08-24 check tested the released generic Book publication path with two consumers:

Consumer Generic publication evidence Downstream status
DDIA 23 ordered pages, 131 typed targets, and 292 resolved cross-references; EPUBCheck, internal, and PDF checks passed At this snapshot it still retained a semantic preprocessor pending independent acceptance of the new gate
TPME 18 ordered pages, 41 typed targets, and 1,062 resolved cross-references; the same generic checks passed A second consumer confirmed portability; it created no upstream migration gate

These results record downstream adoption of the generic publication pipeline.

Limits

Repeating this survey requires a fresh repository list and a new dated snapshot. This public record omits local filesystem paths, uncommitted content, private repository names, and generated build artifacts.

8.7 - OINK comprehensive review, 2026-08-26

Evidence-based review of post-v0.7.0 implementation, configuration, outputs, security, tests, performance, bilingual contracts, and the real integration site.
Historical review snapshot (2026-08-26)

This page records the 2026-08-26 audit of github.com/pgsty/oink and its integration site. OINK 0.7.1 subsequently fixed code findings F01–F06 (see the 0.7.1 release notes). Current behavior is defined by the Design contracts.

Review verdict

OINK’s main-line quality was substantially higher than that of a typical Hugo theme: the default path built successfully, bilingual coverage was strong, and component tests were broad. The project treated output and trust boundaries seriously. The real site showed no general breakage on desktop, mobile, light/dark modes, or primary accessibility paths. Theme and site worktrees were clean. Their latest remote checks succeeded, and every locally rerun first-party suite passed.

While those checks passed, this review found 4 P1, 9 P2, and 5 P3 findings, where some early or peripheral features fell short of OINK’s modern contract. The gates preserved selected positive scenarios very well, but did not systematically cover configuration combinations, static-output behavior, or the semantic accuracy of public documentation.

Before the next release tag, at minimum:

  1. Disable Swagger UI’s default online validator. Verify no implicit outbound requests with a non-localhost browser test.
  2. Apply common type, range, URL, and CSS-value validation to all public configuration and Landing data.
  3. Redesign Swagger, Redoc, and Asciinema behavior in static outputs and their runtime gates.
  4. Repair generated schemas. Update public configuration and front matter references to match behavior.

Baseline and method

Review baseline

Item Snapshot
Theme repository clean main at fe439fdb1d7c2df745088c9bfcbb8c350403ee63, equal to origin/main
Current stable tag v0.7.0 at cbb6f4e0bfe47e17ba7aa41d04b8651c943cf858
Documentation site clean main at fd5fcde, publicly pinned to github.com/pgsty/oink v0.7.0
Local tools Hugo Extended 0.164.0, Python 3.14.6, Node 26.4.0, npm 11.17.0
Remote CI theme HEAD GitHub Actions run 32792753866 succeeded

Validation executed

  • All 31 theme checkers passed.
  • All 85 migration unit tests passed.
  • All 38 theme browser-runtime unit tests passed.
  • All 40 HTML/Print/Markdown/RSS/LLMS golden surfaces passed.
  • The strict tests/site Hugo build passed.
  • The real bilingual site’s npm test passed: 121/121 page pairs, 886 heading IDs, 24,860 internal links, and 3,172 fragments.
  • The full real-site Playwright suite passed: sitemap-wide axe, 29 accessibility cases, and 45 responsive/navigation cases. It also passed 16 keyboard, 10 content-component, 18 code-block, 4 PRD5, and 5 theme-color cases.
  • Extra visual review at 320 CSS px covered EN Home, ZH configuration, ZH Book, and OpenAPI/Redoc, with no page-level horizontal overflow.
  • npm audit found no advisory among the site’s 79 npm dependencies. An OSV Query API batch for 26 exact VENDOR.json versions found no known advisory.
  • measure-baseline.py assets --fixture-site passed its isolated strict build.

Severity

Level Meaning
P1 Breaks a core product, security/privacy, or ordinary-editing invariant; fix before the next tag
P2 Material behavior, contract, or compatibility defect; fix soon with a behavior gate
P3 Maintainability, performance, process, or documentation-governance debt

Finding summary

ID Level Finding Default-site impact
F01 P1 Swagger UI enables its online validator on production URLs Pages using swagger only
F02 P1 Invalid configuration can crash ordinary Hugo or silently emit bad output Depends on authored configuration
F03 P1 Swagger/Redoc/Asciinema violate static-output and runtime-isolation contracts Pages using those shortcodes
F04 P1 Landing sends unvalidated data to safeCSS and lets other bad values pass silently Related Landing fields
F05 P2 Custom page-action and archived-version URLs bypass the shared URL policy Sites configuring those options
F06 P2 Generated JSON Schemas contain wrong defaults, types, descriptions, and candidate keys Authors using editor schemas
F07 P2 The supposedly complete configuration/front-matter references lag v0.7 behavior All maintainers and consumers
F08 P2 Design contracts and proposal lifecycle present conflicting authorities Maintainers
F09 P2 OpenAPI accessibility defects are excluded while Redoc is presented as an alternative OpenAPI readers
F10 P2 Strict-CSP guidance omits theme-owned inline script and style Strict-CSP consumers
F11 P2 No browser support baseline; automation is Chromium-only Firefox, Safari, RTL, forced-color users
F12 P2 Output-security and rendered-Markdown gates have systematic blind spots Consumers relying on those verdicts
F13 P2 Real cross-repository candidate integration is manual and non-atomic Every public behavior change
F14 P3 Checker duplication and source-string coupling are high Maintainers and isolated worktrees
F15 P3 Baseline CSS and fonts remain the main first-visit payload Every HTML page
F16 P3 Vendor integrity is strong, but vulnerability/SBOM and CI supply-chain gates are manual Release maintainers
F17 P3 Changelog, implemented proposals, and behaviorless metadata reduce signal Maintainers and upgraders
F18 P3 The Print isHTML FIXME no longer explains the real dependency Print-template maintainers

Detailed findings

F01 — Swagger UI implicitly contacts the online validator (P1)

layouts/_shortcodes/swagger.html initializes SwaggerUIBundle without validatorUrl: null. Vendored swagger-ui-bundle.js defaults to https://validator.swagger.io/validator. It suppresses the badge only when specification URLs contain localhost or 127.0.0.1. On deployed hosts, it creates an online-validator badge whose request includes the specification URL.

This violates the promises of disabled-by-default theme network features, local same-origin specifications, and local-first operation, and can disclose internal hostnames or specification URLs on intranet deployments. The localhost exemption explains why every local browser test missed the request.

Set validatorUrl: null explicitly. Any future online validator should require an explicit opt-in URL, use the shared URL policy, and have privacy/CSP integration documentation. Test a production-like, non-localhost origin while intercepting every request. Require same-origin specifications to fetch only first-party resources.

F02 — Invalid configuration does not consistently warn and fall back (P1)

ui-param.html says callers validate types. Some callers do not. Minimal builds produced these results:

Input Actual result
ui.blog_index_size: nope ordinary build fails because .Paginate requires a positive integer
ui.sidebar_expand_levels: nope ordinary build fails in add
ui.sidebar_menu_truncate: nope ordinary build fails while first casts the value
offline_search_summary_length: nope ordinary build fails while truncate casts the value
ui.sidebar_width_min: "1; color: red" warning-free build emits --td-shell-sidebar-min: ZgotmplZpx
ui.sidebar_width_min: -50 warning-free build emits -50px
blog_index_columns: 2.5 / section_index_columns: 2.5 warning-free build feeds 2.5 to CSS repeat()
ui.sidebar_item_overflow: clip warning-free build silently behaves as ellipsis
ui.sidebar_menu_foldable: definitely the non-boolean string is truthy and enables folding
ui.blog_index_size: 0 Hugo default silently converts it back to 12

Landing marquee.rows/capabilities.columns and Asciinema numeric parameters also call int/float directly. Other invalid types, including print.toc and offline_search_max_results, silently change behavior.

This directly contradicts the Diagnostics decision: ordinary hugo server can become unusable, while some invalid input passes strict publishing gates without warnings. Add shared validators for integers, positive integers, ranges, paired ranges, and grid counts. Normalize values before arithmetic or output. For every public key, test valid site and page cases, invalid ordinary cases with warnings/fallbacks, and invalid strict cases with failures. Domain resolvers should enforce cross-field rules such as min <= max, pager size >= 1, and integer grid counts.

F03 — OpenAPI and Asciinema remain HTML-only islands (P1)

Architecture and Components require Markdown/LLMS without theme markup, static Print, and safe static RSS or explicit omission. The observed behavior conflicts with these requirements:

  • Redoc emits <style>, <div class="td-redoc">, and <redoc spec-url=...> into generated .md.
  • Swagger puts an executable inline initializer in its shortcode.
  • Asciinema .md contains the complete td-asciinema tree and JSON script.
  • Asciinema Print loads about 185 KB of player JS/CSS and prints only an incidental frame.
  • Swagger/Redoc leave empty Print containers and can select 1–2 MB runtimes.
  • These shortcodes are absent from the Markdown/RSS/Print golden matrix.

The result is theme HTML in agent output, empty shells for paper/EPUB readers, useless runtime in Print, and a strict-CSP violation from Swagger. Reader-facing guides describe these defects as output behavior, conflicting with normative contracts.

Make all three branch on tdOutputFormat. Provide full behavior in interactive HTML. For Print/Markdown/RSS, provide a titled static link with the specification or cast address, or explicitly omit the component. Only interactive HTML should set capability flags. Move Swagger initialization to a stable chunk and Redoc styles to a stylesheet. Add four-output goldens and assertions that unwanted runtimes are absent.

F04 — Landing CSS, URL, and numeric inputs do not share one trust boundary (P1)

hero.html validates title_size, but concatenates media.ratio and media.max_width unchanged before marking the full string safeCSS. This input:

sections:
  - type: hero
    data:
      title: Probe
      image: /icons/logo.svg
      media:
        ratio: "1fr; background-image: url(https://example.invalid/x)"
        max_width: "240px; color: red"

passes a strict build without warnings and emits:

style="--td-hero-columns: 1fr; background-image: url(https://example.invalid/x);
       --td-hero-media-max: 240px; color: red;"

Landing accepts inline sections in page front matter, so authors can supply these values directly. Other sections handle columns, rules, dimensions, styles, icons, and URLs inconsistently. A javascript: URL often becomes #ZgotmplZ without warnings. Invalid columns become ZgotmplZ. Some direct integer casts abort builds.

Add section normalization with common handling for classes, icons, URLs, CSS lengths, grid counts, booleans, and enums. hero.media.ratio should accept two constrained track values, not arbitrary CSS. max_width should use the length validator. All Landing actions should use content/url.html. Each built-in section needs negative tests.

F05 — Two configuration URL surfaces bypass shared policy (P2)

params.ui.page_context_menu.links passes through url-template.html directly to safeURL. url_latest_version is also treated as trusted configuration and marked safeURL. Neither path validates schemes, hosts, whitespace, or protocol-relative URLs. Warning-free builds can produce:

<a class="td-page-actions__item"
   href="javascript:document.body.dataset.pwned=1;undefined">

Clicking executes JavaScript, which violates the published safe-URL model and gives copied configuration fragments unnecessary execution capability.

Use the shared resolver to allow only HTTP(S) and explicitly supported first-party relative URLs. Also validate archived-version URLs. The browser action registry’s second check provides useful defense, but progressive-enhancement anchors must not bypass it.

F06 — Generated schemas disagree with actual YAML (P2)

The small parser in generate-config-schema.py does not remove inline comments. At least 11 defaults become strings. These include print.toc, which becomes "true # ..." instead of a boolean, and print.section_break_wordcount. Both index column counts and enum defaults such as footer_style, blog_index, and typography are also affected.

Comment association is also incorrect. Breadcrumb commentary attaches to section_index; quick-link commentary attaches to sidebar_icon_policy. Taxonomy-icon commentary attaches to pager_types; local-interface commentary attaches to image_zoom.

The front matter schema offers removed detector keys: release, upstream_attribution, and downstream_modified. It incorrectly treats navbar-menu Params.columns as page front matter. The drift check compares the same defective generator with committed output, preserving the error.

Use a real comment-preserving parser or explicit machine metadata markers. Do not extend the ad hoc parser. The scanner must distinguish page, menu, shortcode, and legacy-detector contexts. Tests should compare schema defaults with Hugo’s actual parsed values and exclude removed keys from completion.

F07 — Public configuration and front-matter references are not current (P2)

Both reference pages claim to list every key read by the theme. Material differences include:

  • Long English date defaults, although hugo.yaml uses ISO 2006-01-02.
  • Blog docs omit hero, table, toggle, size, toc_style, and toc_taxonomies.
  • Removed release maps and filters are presented as current, while release_url is absent.
  • images: [] is described as disabling featured images, although bundle discovery continues.
  • upstream_modified is described as adding a line, although it changes the attribution verb.
  • Invalid-input claims conflict: immediate failure versus warnings in ordinary previews and failure only at strict gates.
  • The Book guide says OINK stops at Print HTML, although v0.7 shipped BookManifest/EPUB/PDF tools.
  • Asciinema/OpenAPI guides present static-output defects as product contracts.
  • Features lists 28 vendor dependencies, although the authoritative manifest has 26.

English and Chinese usually share the same outdated answer. Translation parity cannot detect that error. Treat both references as a focused contract migration. Derive comparable key inventories from implementation/schema. Review semantics manually. Check current-key coverage, placement of removed keys, enums, and defaults.

F08 — The Design tree contains conflicting authorities and unretired proposals (P2)

Shell retires navbar columns/mega panels and promises a warning with one column. Landing still says navbar mega-menu columns accept 1–4. Implementation and tests follow Shell.

The lifecycle is also incomplete. config-schema is marked implemented but remains an Active proposal. Book publication has shipped the manifest, EPUB, PDF, and most CI work, but a Draft proposal duplicates the Architecture contract. Media convergence keeps implemented milestones and open M4 in the original design record.

Correct Landing. Move stable config-schema facts to Architecture/Decision and retire the proposal. Reduce Book publication to the remaining consumer-migration question, or replace it with a focused follow-up. Active proposals should not define a second current API.

F09 — OpenAPI accessibility claims conflict with test exclusions (P2)

The axe suite excludes .td-swagger-ui and .td-redoc. Its comments identify Swagger’s unnamed server selector and version stamp that cannot scroll by keyboard. They also identify Redoc operation-description contrast. The guide discloses only Swagger defects and presents rendered Redoc as the alternative. This implies that Redoc meets the site’s zero-violation gate.

Publish the actual boundary in both languages. Fix Redoc contrast in theme CSS where possible. Use a narrow post-render adapter for fixable Swagger DOM. For remaining upstream defects, provide versioned waivers, upstream issue links, and a separate axe report. Do not exclude the entire supported feature while claiming zero site-wide violations.

F10 — The current theme does not directly support a strict CSP (P2)

Deployment guidance says strict CSP is workable. It lists only author scripts, ECharts callbacks, analytics, remote specifications or diagram services, and Giscus. Ordinary Docs pages already emit two theme-owned inline scripts for initial theme display and shell prepaint, plus inline styles. Markmap, Swagger, Algolia, and Google CSE add more theme-owned inline initializers. There is no nonce API, hash manifest, or complete sample policy.

script-src 'self' blocks initial theme display and shell-state restoration. style-src 'self' blocks theme colors, font roles, Landing, and several inline custom properties. Consumers must add 'unsafe-inline', maintain hashes, or override templates. The guide states none of these requirements.

Move stable initializers to same-origin chunks with data/JSON configuration. For unavoidable inline content, provide a generated hash manifest or one nonce hook. Publish policies for minimal core, Markmap/OpenAPI, and third-party integrations. State the style-src requirements.

F11 — Browser compatibility has no baseline or cross-engine proof (P2)

CI installs only Chromium. Product documentation gives no minimum Chrome, Firefox, or Safari version. The implementation uses or enhances content with :has(), dialog, inert, color-mix(), @property, logical properties, and discrete display transitions. Some paths have fallbacks, but there is no engine matrix.

RTL checks mostly use source markers, small JS tests, and one element-level geometry change. They do not use a complete RTL-language site. Most forced-color checks verify SCSS strings instead of computed behavior.

Publish a small support matrix. Test core shell, navigation, content, and dialogs on Chromium, Firefox, and WebKit. Add a real languageDirection: rtl integration configuration. Also test forced colors, reduced motion, 320 px, and 200% zoom.

F12 — Output-security and Markdown gates do not inspect every claimed surface (P2)

For .md, check-output-security.py checks only Markdown links. It does not send raw HTML through the HTML scanner. Redoc/Asciinema scripts, spec-url, and raw href are therefore invisible. It also ignores CSS and JSON URLs. The fixture uses a broad --third-party allowance.

check-rendered-markdown.mjs has a misleading name. It scans generated HTML text for leftover Markdown syntax, not generated .md. The actual Markdown golden set covers 15 pages and omits OpenAPI/Asciinema.

Use clearly named gates for HTML trust, machine-output purity, and rendered-text residue. Give generated Markdown a narrow raw-HTML allowlist. Deliberately parse CSS URLs, form actions, JSON URLs, and non-executable JSON scripts. Every public shortcode should have at least one Markdown/Print/RSS behavior case.

F13 — Candidate integration across the two repositories is manual (P2)

Theme CI tests only synthetic tests/site. Documentation-site CI tests only the public tag in go.mod. Real EN/ZH and Playwright validation for theme PRs depends on local maintainer HUGO_MODULE_REPLACEMENTS. Changes in both repositories cannot be committed atomically.

Both repositories can pass checks while public references differ from implementation, as this review shows. The written separation of release states is correct, but automation does not enforce delivery of implementation, owning checker, and paired contract together.

Add a read-only candidate workflow. Check out a theme PR SHA and a declared documentation-site SHA. Apply a temporary module replacement, then run npm test and critical browser suites. Allow Design-contract PRs to identify candidate theme SHAs. Tag, pin, and deployment remain distinct. The candidate pair gains one traceable joint result.

F14 — Checker maintenance cost and source coupling are high (P3)

Coverage is valuable, but 34 check-*.py files contain 546 read_text() calls. Many repeat require, temporary-site creation, file writes, Hugo invocation, and error aggregation. Many assertions preserve template/SCSS spelling, nearby comments, or complete file equality instead of observable behavior.

Some helpers hard-code theme: oink with --themesDir <repo-parent>, making the checkout or worktree basename an implicit requirement. Without a common Python lint/type gate, checkers are quick to add but can retain shared testing omissions.

Create a common fixture builder and assertion library. Put negative cases in table-driven data. Keep source checks only for actual topology rules. Move other checks to parsed output or computed styles. Load themes through explicit symlinks or module replacements instead of repository basenames.

F15 — Runtime splitting succeeded, but baseline CSS/fonts dominate first visit (P3)

The isolated strict fixture baseline was:

Metric Value
Cold/warm build 1.256 s / 1.273 s
Pages 249
Stable JS chunks 18
Main + Font Awesome CSS 549.8 KB raw / 91.1 KB gzip
Fonts total (FA portion) 999.7 KB raw / 248.5 KB gzip
Median Docs-page JS 176.9 KB raw / 55.3 KB gzip
Generated public 26.2 MB
v0.7.0 Go module zip 7.8 MB (about 20.5 MB and 1,140 files expanded)

Stable first-party capability chunks removed bundles for feature combinations correctly. Large third-party runtimes remain page-local. Bootstrap/theme/Landing CSS and the complete Font Awesome distribution are the remaining common cost.

Do not prune Font Awesome based on theme template usage. That would violate the authoring contract. Measure whether Landing, Book, or Swagger CSS can be independently cached and limited to relevant pages. Inspect fonts requested on first visits. Maintain a trend report instead of an arbitrary hard threshold.

F16 — Vendor builds are reproducible, but advisory and CI supply-chain gates remain manual (P3)

Positive evidence: VENDOR.json pins 26 packages, 56 artifacts, 31 license files, and tree hashes. check-vendor.py passed. OSV and npm audit found no known advisory in this snapshot.

The custom manifest is outside common SBOM/advisory gates. npm audit cannot inspect vendored browser packages. Two documentation-site workflows download Hugo .deb files and immediately run sudo dpkg -i without checking a checksum. Actions use movable major tags. Theme CI uses floating Python 3.x.

Generate CycloneDX/SPDX from VENDOR.json. Schedule OSV scans. Pin Hugo archive/deb SHA-256 values and trusted release actions to commit SHAs. Select a specific Python version or matrix.

F17 — Design and release records have lost signal (P3)

CHANGELOG.md has 1,768 lines. Its v0.7.0 section has about 300 lines, and Unreleased uses about 20 lines for one checker retry. These narratives provide useful engineering history, but make breaking changes, migrations, and observable behavior harder for upgraders to find.

Contracts recognize book_kind and book_part, and content front matter repeats them, but templates explicitly do not read them. They impose API-like authoring work without behavior. Implemented proposals that remain active provide another duplicate answer.

Keep changelog entries focused on observable changes, breaking/migration notes, and concise fixes. Move long design accounts to Blog/Research and link them. Give metadata without behavior a consumer/schema, or make it site-owned.

F18 — The Print isHTML FIXME is no longer accurate (P3)

hugo.yaml says to leave isHTML unset until Hugo fixes issue #14381. Hugo closed it on 2026-01-17, and the fix shipped before OINK’s 0.160.1 floor. Enabling isHTML: true still produces missing page/section/landing Print-layout warnings in this theme, which fail strict builds.

The dependency changed from “waiting for an alias fix” to “the current Print template names rely on non-HTML lookup rules.” Do not simply remove the workaround. First complete the HTML-classified Print lookup matrix and alias/subpath tests. If false remains intentional, explain the actual reason in the comment. Add a test to prevent cleanup based only on the closed issue.

Strengths

  • Source, local validation, commit, tag, public module, consumer pin, and deployment are explicitly separated.
  • The Hugo 0.160.1 floor plus 0.164/0.165 theme matrix is strong.
  • Most newer components follow warning/fallback, four-output, shared URL/attribute, and capability-flag contracts.
  • The 32 locale schemas match, with strong real EN/ZH page, heading-ID, link, and narrow-navigation gates.
  • Search, keyboard behavior, surface coordination, page actions, and theme color have both unit and browser behavior tests.
  • Vendor license/hash checks and EPUB/PDF path, loopback, CSP, and overwrite boundaries are thoughtfully designed.
  • Manual 320 px review found no page-level overflow; current core visual quality is good.
  • Builds are fast, and first-party JS now uses stable capability chunks.

Recommended remediation roadmap

Phase 0: before the next tag

  1. Set Swagger validatorUrl: null and add a production-origin no-network test.
  2. Build the public-parameter inventory and validate every F02/F04 field with negative cases.
  3. Redesign four-output behavior and runtime gates for Swagger, Redoc, and Asciinema.
  4. Validate custom action and archived-version URLs.
  5. Repair the schema parser/scanner and regenerate both schemas.
  6. Synchronize paired Config, Front matter, OpenAPI, Asciinema, Book, Features, and Landing-contract pages.

Phase 1: contract gates

  1. Create a minimum HTML/Print/Markdown/RSS coverage map for all 29 shortcodes.
  2. Split and strengthen output-trust and machine-output-purity gates.
  3. Normalize all Landing section input centrally.
  4. Externalize theme-owned inline initializers and publish CSP guidance.
  5. Add a cross-repository candidate workflow.

Phase 2: compatibility and structure

  1. Add Firefox/WebKit, real RTL, forced colors, and 200% zoom.
  2. Consolidate the Python checker harness and source-string assertions.
  3. Evaluate surface-specific CSS and actual font requests.
  4. Generate an SBOM, schedule OSV, and pin CI download digests.
  5. Retire implemented proposals and reduce changelog volume.

Acceptance criteria

  • A same-origin Swagger specification on a production-like origin makes no third-party request.
  • Every invalid public configuration warns and falls back/omits in ordinary builds, fails strictly, and emits no ZgotmplZ.
  • Generated .md contains no td-*, theme script/style, or empty interactive container.
  • Print loads no Swagger/Redoc/Asciinema runtime and provides an understandable static alternative.
  • Schema default types exactly match Hugo parsing, and removed keys are absent from completion.
  • EN/ZH configuration and front-matter key/enum/default inventories match implementation.
  • Core Playwright passes on Chromium, Firefox, and WebKit, with real RTL and forced-color behavior assertions.
  • Every candidate theme SHA has a traceable joint validation against the real documentation site.

Review limits

This review did not individually audit consumer repositories, production response headers/CDN caches, real Firefox/Safari, or screen readers. It did not manually reverse-engineer 13 MB of minified third-party source. Advisory checks are a 2026-08-26 snapshot and may change. Existing CI/contract evidence covered DDIA/TPME EPUB/PDF consumers.

8.8 - Community issue and PR review, 2026-09-19

Evidence, acceptance advice, and focused remedies for community issues 40, 41, 42, 44 and pull request 43.
Historical review snapshot (2026-09-19)

This page records source inspection, GitHub status, local builds, and targeted browser observations from 2026-09-19, followed by the same-day implementation and acceptance follow-up.

The initial review remains below; the maintainer later authorized merging PR #43 and implementing the other items directly on main. See the same-day implementation and acceptance follow-up.

Verdict

The reports identify useful problems, but they are not all defects of the same kind. Fix hidden navigation focus first. Accept PR #43’s direction as a small correctness fix after clarifying its boundary and adding coverage. Treat search-tail registration and public sidebar state as additional APIs requiring their own acceptance work.

Item Finding Recommendation
PR #43, MagicFollower Self-root collection ignores an explicit sidebar_root_menu: false. Reproduced. Conditional acceptance: the patch correctly filters the global candidate list. Document the current-root exception, add regression tests, and obtain successful CI.
#41, imbajin Hidden whole-sidebar content remains focusable. Several controllers write disclosure state, and no public API exists. Split a correctness repair from an optional API. The former has higher priority.
#44, lloydsun Pointer focus followed by a key produces the reported outlines. Reproduced on another platform. Improve the main-content focus treatment. Retain useful keyboard cues for scrollable content. The browser heuristic itself is expected.
#42, aucru Existing hiding and divider options do not provide a complete non-link section group with its children. Explain the options separately and obtain the author’s exact minimal example. If the missing group behavior is confirmed, implement it.
#40, imbajin There is no supported way to append a query-dependent action to local search. This is a reasonable small extension proposal. It does not identify a failure of existing local search. Correctness repairs have higher priority.

Baseline and method

GitHub API reads found four open external issues and one open external PR. The other open issue, #37, was the maintainer’s release tracker. The external items had no discussion comments or submitted PR reviews at the snapshot time.

Input Verified snapshot
Remote theme main 93ac292014a3cd81f7c41caec4df98ed9d2dc45a
Local theme 75ddc95. Only the release text in CHANGELOG.md differs from remote main.
PR #43 head 8eeb8ecaf525097cc56572fe22234db381bfc16a, one changed template line
Local documentation ff0ba39. go.mod still requires OINK v1.0.0.
Published release GitHub’s latest release is v1.0.0. The remote query returned no v1.1.0 tag.
Build tools Hugo Extended 0.166.0, Node 26.9.0, npm 11.19.1
Browser observation macOS, Chromium 153.0.0.0, light theme, real sibling documentation site using a command-scoped module replacement

The method combined complete issue/PR bodies and comments, the exact diff, and bilingual Design contracts with inspection of owning templates and JavaScript. It also used a temporary bilingual site under the /sub/ base path and targeted documentation-site browser interactions. No theme implementation changed in the shared checkout.

PR 43: accept the small fix with a precise boundary

The first pass in root-menu-roots.html filters top-level sections by sidebar_root_menu. The second pass collects sections with sidebar_root_for set to self, but omits that filter. Sections excluded in the first pass can therefore return in the second.

The PR adds the same explicit-false predicate to the second pass:

{{- if and .IsSection (ne .Params.sidebar_root_menu false) -}}

The patch keeps the default for absent or true values, the section constraint, and URL deduplication, while preserving navigation-tree order, pager order, and language-specific caching. These properties make it a focused correctness fix with no need for a broader navigation refactor.

However, root-menu-entries.html subsequently appends the current resolved root when absent. This existing behavior is documented in the navigation guide, so it is not a new PR regression; it does prevent the broader claim that false hides the root on every page.

The local probe used a top-level Blog root and nested Docs root, both with sidebar_root_for: self and sidebar_root_menu: false. It also included a visible Docs root and a self-root without a visibility override. English and Chinese results were identical and retained language-aware /sub/ URLs:

Viewed page Before the PR With the PR
An unrelated Docs page Both hidden self-roots appear Both disappear
A page inside the hidden Blog root Blog appears Blog still appears through current-root fallback
A page inside the hidden nested root Nested root appears Nested root still appears through current-root fallback
A visible self-root Appears Still appears without duplication

Recommended contract: false excludes roots from site-wide selectable candidates, but the current root may remain for orientation. Keeping this exception is the smallest compatible interpretation. State it explicitly in both languages. If the intended contract requires absolute exclusion, change the current-root fallback and switcher trigger together. Another predicate alone is insufficient. Check zero and one-entry states.

Before merging:

  1. Add output-based bin/check-shell.py cases for hidden top-level and nested self-roots, absent/true values, deduplication, and current-root behavior. Cover one-entry degradation and EN/ZH subpaths.
  2. Update the Shell contract and navigation guide together. Change the PR description’s YAML comment from // to # so readers can paste its example.
  3. Resolve the workflow’s action_required result and run required checks on the final head. At this snapshot, the PR head had no completed check runs (MERGEABLE, UNSTABLE).

The maintainer can add these small changes while preserving the contribution. Do not make acceptance depend on #40 or all of #41.

Issue 41: repair isolation, then expose state

There are two separate findings.

Whole-sidebar hiding uses transforms and, on desktop, opacity. Drawer and collapse controllers leave hidden controls in keyboard navigation. In the browser probe, Collapse sidebar left focus on the transparent collapse button. Tab then moved focus to the hidden root switcher. The panel had zero opacity and no effective inert or aria-hidden ancestor. This is a reproducible keyboard usability defect. Closed mobile panels use similar off-screen positioning without explicit isolation.

Disclosure writes are duplicated across the click controller and responsive relocation and cached active-path hydration. There is no public setter, getter, or committed-state event. Existing storage for sidebar collapse, width, and scroll position does not persist per-branch disclosure state across page loads. The authoring guide’s local expansion-state claim needs this distinction.

Recommended repair:

  1. Centralize whole-sidebar isolation at initialization and every open, close, collapse, hover-overlay, restore, and breakpoint transition. Remove isolation before moving focus inside. Return focus to a visible external control before making content inert.
  2. Isolate content while keeping the external restore button and desktop edge hover target active. Applying inert to the pointer sensor would break hover interaction. aria-hidden alone does not prevent keyboard focus. The HTML inert contract controls interaction and accessibility exposure.
  3. Route disclosure changes through one commit function separately. Update aria-expanded, the open class, and localized label before emitting one event. Repeated writes of the current value should have no effect.
  4. Expose a small setter/getter and event only after defining stable IDs, invalid-ID behavior, initialization readiness, and restoration order. Keep version/locale storage policy downstream-owned. Let the active path take precedence after restoration.

The proposal needs a scope correction. Responsive TOC/backlink/taxonomy groups can move from the sidebar to the right rail. A controller searching only current-sidebar descendants cannot control wide-layout writes. Register OINK-owned targets independently of their current DOM parent. Restrict the public sidebar API to its intended registered subset.

Acceptance must check real Tab order and the accessibility tree in hidden states. It must also check restored desktop collapse on first load, hover entry/exit, focus return, Escape, backdrop close, and scroll unlock. Cover the 768/1200 breakpoints and preserve #24’s visible no-JavaScript fallback.

Issue 44: real symptom, partly expected behavior

On the documentation configuration page, clicking the article heading focused main#td-main-content. Clicking table headers focused div.td-table-scroll; clicking code focused pre.chroma. In each case, :focus-visible was false after clicking and true after pressing unbound z. Main/code outlines changed from none to browser auto outlines. Tables used the theme’s solid outline. This reproduced the mechanism without the reporter’s Linux compositor or Super key.

The Selectors specification explicitly describes keyboard activity changing focus indication while focus stays on the same element. The report therefore provides useful UX feedback. Browsers are not required to keep mouse-focused elements free of focus rings after keyboard activity.

Recommended treatment:

  • Keep the main skip-link target and focusability. Replace its oversized outline with a local, visible content-entry cue, such as a title-area indicator. Verify actual skip-link activation.
  • Keep visible keyboard focus on scrollable tables and code. Normalize its appearance if needed. Focusability enables keyboard scrolling.
  • Do not apply global outline: none, remove all tabindex attributes, or blur focus on arbitrary keypresses.
  • If OINK suppresses only pointer-origin reading focus, define that behavior explicitly for these non-editable containers. Test pointer, Tab, skip-link, and programmatic focus, including dark and forced-colors modes. A global input-modality framework is disproportionate to this report.

This review recommends a focused presentation improvement while keeping table and code keyboard focus cues.

Issue 42: distinguish hiding from grouping

The question names _index.json and supplies screenshots instead of a source fixture. This review could not visually inspect the original screenshots. The author’s intended first change remains unresolved. When replying, request a small directory tree and actual index/front matter. Without that evidence, do not assume _index.json is a supported page source or a typo.

The existing options have different meanings:

Option Current behavior and limitation
no_list: true Removes the child list from the section’s content body. It does not hide the section’s sidebar row.
hide_summary: true Removes an item from a parent section’s body list. It does not change sidebar grouping.
toc_hide: true The content-tree walker filters out the node before recursion. This also removes its subtree from that tree.
sidebar_root_menu: false Controls root-switcher candidates. It does not control the node’s row in the reading tree. See PR #43.
sidebar_root_link_self: false Redirects a self-root’s row to its parent. It does not make the row a non-link group.
sidebar_divider: true Emits a non-link heading. The shared renderer does not emit the supplied children in that branch.
build.render: link Suppresses the section HTML and retains its permalink. The current sidebar still emits a link to it. This option alone is insufficient.

The temporary site confirmed that divider sections keep child HTML while child sidebar links disappear. Sections with only build.render: link have no section HTML, but keep clickable sidebar rows and children. This matches Hugo’s build-option semantics and the theme’s shared node renderer.

For a real “group label with child links, but no directory-page navigation” requirement, first consider completing sidebar_divider for sections. Keep leaf dividers and section children. Use real disclosure buttons when folding is enabled. Check existing consumers before adopting this interpretation. Add a separate node switch only if the divider contract cannot express it compatibly. Keep section publication separate from whether its navigation label is linked.

The change must preserve hierarchy and active-path expansion in both walkers, and keep children in the pager. If a section is intentionally unpublished, the change must avoid dead targets in breadcrumbs, search, root switching, Print, and machine-readable navigation. Hiding whole nodes with CSS is not a solution.

Issue 40: a narrow extension is reasonable

Source inspection confirms the gap. groupsFor creates only built-in page/action groups. The public Palette object has no provider registration. registerExecutor accepts only built-in action IDs. Static URL commands cannot replace rows carrying the current query.

The proposed search-tail slot is a useful upstream boundary if its scope stays small. It uses synchronous data-only row creation, asynchronous activation, and local results first. OINK controls rendering, selection, keyboard handling, and ARIA. It needs no bundled AI provider, credentials, remote search, or generic plugin system.

Before adopting the proposed API, settle and test:

  1. Define which settled text-search states call providers. Preserve empty, command, choice, loading, and default no-extension behavior.
  2. Snapshot the query/locale used for each rendered row. Preserve native empty/index-error messages, retry behavior, and the difference between local page counts and all selectable rows.
  3. Validate and copy descriptors. Render titles and descriptions as text. Isolate provider exceptions, duplicate IDs, and invalid descriptors.
  4. Handle synchronous throws and rejected promises. Clear pending state and reject duplicate activation. Cancel stale sessions. Ensure unregister handles remain safe when IDs are reused.
  5. Test handoff to another dialog. Palette close already avoids returning focus when focus moved outside. Preserve this guard. Define how successful handoff differs from cancellation. An “every close aborts activation” rule can cancel the assistant being opened.
  6. Preserve default local-only network behavior and conditional bundles. Document that registered extensions run as trusted first-party scripts in the page context.

Before implementation, record the accepted API in a bilingual Design proposal. Downstream Ask AI wrappers can continue until a tagged release provides the hook. This is not required for the small correctness fixes.

Delivery order and ownership

Order Delivery Owning checks and documentation
First PR #43 completion and hidden-sidebar isolation as separate small changes check-shell.py; site responsive/keyboard/accessibility cases; EN/ZH Shell contract and navigation guide
Next Main-content focus styling and clarified grouping behavior Content/reading and navigation checkers as appropriate; browser focus/scroll/skip tests; EN/ZH architecture, shell, and authoring guidance
Later Public disclosure controller, then search-tail API Theme JS tests and check-navigation-contract.py / check-palette.py; real site fixtures; accepted bilingual API contracts

For each behavior change, run its owning checker first. Then use the sibling site’s make check, make browser, and make dev for relevant integration and visual review. Do not combine unrelated proposals into one large sidebar/search rewrite. Do not delay small fixes until all features exist.

Suggested response content, not posted: acknowledge #43’s filter defect and explain its current-root exception. Accept #41’s isolation defect separately from the API request. Acknowledge #44’s reproduction and explain standard focus behavior. Explain #42’s options and request minimal input. Describe #40 as a scoped enhancement, not a local-search failure.

Historical external issues are closed. #22 was resolved by enabling Goldmark passthrough, with reporter confirmation. #21 received the Mermaid viewer and corrected centered presentation. Arbitrary right alignment was explicitly excluded. Do not silently count either issue as a new open defect.

Validation and limits

Executed for this review:

  • python3 bin/check-shell.py passed on the local baseline and in an isolated checkout at PR #43’s exact head.
  • Palette controller and model tests passed: two test files, no failures.
  • Strict temporary Hugo builds before/after the actual PR diff reproduced EN/ZH self-root filtering and fallback under /sub/. The same fixture demonstrated grouping limitations.
  • The real bilingual site built with --panicOnWarning using the local theme. Targeted Chromium interactions reproduced all three focus outlines and the desktop hidden-focus defect.
  • Bilingual, rendered-content, and link checks passed, along with all 57 non-browser tests. Initial make check stopped at the llms.txt snapshot because this report added an index entry. After verifying that one-line addition and updating the golden, affected and remaining groups passed on rerun.

Local verification used Hugo 0.166.0 on macOS. Linux Super-key behavior, mobile accessibility-tree isolation, dark/forced-colors cases, and the exact #42 screenshots are covered in the follow-up acceptance below.

Implementation and acceptance follow-up

The maintainer chose to merge the contributor patch first, then complete repairs and extensions directly on main without another PR. PR #43 merged as 6e814089. The merge was pulled while preserving the local release-note commit. The implementation follow-up is 56bfe37.

Item Implemented behavior Owning acceptance
#43 Both root collectors honor explicit false. Current-root orientation remains compatible. Dividers and unpublished sections do not become switcher links. Strict EN/ZH subpath fixtures cover hidden top-level/nested roots, absent/true values, deduplication, current-root fallback, zero and one entry.
#41 One disclosure controller commits ARIA, classes, labels and inert state. A late-safe API supports downstream persistence. Hidden whole-sidebar content is isolated. Hover and drawer restoration remain usable. Runtime tests plus browser checks for atomic events, no-op writes, scope, active paths, blocked storage, responsive relocation, focus return, real Tab traversal, Escape, backdrop and breakpoints.
#44 A pointer-origin mark suppresses later incidental container outlines. Tab and fresh programmatic focus retain visible cues. The skip destination outlines the title. Browser checks for article/table/code in light, dark and forced-colors modes, plus keyboard and skip-link regression coverage.
#42 Divider sections keep their children under a non-link label. build.render: never suppresses their own page. Breadcrumb, search, pager, navigation JSON, Book TOC/Markdown and Print agree. Explicit navigation also works under bilingual subpaths. Strict generic/data-tree fixtures, Book depth-three heading checks, EN/ZH browser fixtures and no-JavaScript traversal.
#40 Trusted site scripts can register synchronous data-only search-tail rows and asynchronous activation. OINK continues to own native ordering, ARIA and validation. It also owns error isolation, cancellation, unregistering and focus handoff. Runtime lifecycle tests and a Chinese browser scenario cover pointer/keyboard selection and literal display text. They also cover context snapshots, external-dialog focus and unregistering.

Acceptance used the sibling theme checkout on macOS with Hugo Extended 0.166.0, Node 26.9.0, and Chromium:

  • All 44 theme JavaScript tests passed.
  • check-shell.py, check-reading.py, check-palette.py, and check-keyboard.py passed. A broader run passed 29 of the other 31 theme CI commands. Two local failures involved the media checker’s version-specific processed-image hashes and four goldens with Hugo 0.166’s changed KaTeX output. Ordinary navigation markup matched after preserving its existing whitespace. Fixed-toolchain verification is recorded below. Unrelated expected outputs were not rewritten.
  • make -C ../oink.pgsty.com check passed bilingual source/rendered/link checks and all 57 non-browser tests.
  • make -C ../oink.pgsty.com browser passed all 141 tests: 30 accessibility, 45 responsive/blog/palette, 16 keyboard, 10 content, 18 code-block, 4 scenario, 5 theme-color, and 13 community regressions. Accessibility included the complete multilingual sitemap scan.
  • Strict theme fixture output and namespace checks passed. Local Book packaging produced an EPUB with five chapters and zero checker errors. It also produced a 23-page PDF with all five expected Book pages and zero checker errors.
  • make dev served the real site for desktop-light, Chinese-dark, collapsed-sidebar restore, and 375px mobile-drawer review. Escape returned focus to the visible drawer opener. The temporary viewport and development server were cleaned up afterward.

Accepted contracts are in Shell and Architecture, with matching Chinese sources. Navigation, organization, palette, and Print guides were also updated. The documentation repository owns regression suites. The theme keeps focused checkers and synthetic inputs.

The merged PR’s fixed-toolchain CI passed all three jobs. The final implementation’s CI run also passed at exact revision 56bfe37092a43fc12c0e16f865d3d3407c55cbde. Hugo 0.165.0, browser runtime tests, and Book publication succeeded. This included media and four-state golden checks that differed locally on Hugo 0.166.0, plus root/subpath publication. The supported 0.160.1 floor was not separately retested. The declared continuous-test toolchain remains 0.165.0.

At this checkpoint, the documentation repository stayed pinned to v1.0.0 while awaiting the v1.1.0 tag, and issues #40, #41, #42, and #44 remained open pending release publication.

Image-copy follow-up

The maintainer also reported preview instructions below images after copying blog articles to rich-text editors. The blog pins OINK v1.0.0 and enables params.ui.image_zoom. That release and the reviewed main revision inserted a visually hidden text span after every eligible image. Native Chromium copying reproduced Open image preview and its Chinese equivalent in clipboard content. This is a theme defect independent of the destination editor.

Theme commit 75052f8 puts image descriptions and localized actions in the button’s aria-label, keeping helper text nodes out of the article. Image alt text, authored captions, native button behavior, and dialog focus return remain intact. The component contract and image guide document this copying behavior.

check-image-zoom.py and all 57 non-browser site tests passed. The focused browser run passed 16 tests: 14 content-component cases and two desktop-light/mobile-dark dialog accessibility cases. Component cases included four new EN/ZH image/gallery clipboard regressions. The regressions read plain-text and HTML clipboard data and check text without its original styles. They verify retained image URLs, alt text, captions, and accessible names.

Downstream blogs pick up the fix once they upgrade their theme dependency past v1.0.0.

8.9 - OINK 1.1 release review, 2026-09-20

Five reproduced runtime defects, documentation corrections, validation evidence, and the OINK 1.1 publication follow-up.
Historical release review (2026-09-20)

This record captures the pre-release validation and five runtime fixes for OINK 1.1, followed by the v1.1.0 publication record.

Scope and baseline

The review starts at theme commit 75052f8a3106d13ef313644836a5ad545135f484, after the community fixes and image-copy repair. It examines the v1.0.0..main changes and behavior requested by issues #40, #41, #42, #44, and merged PR #43. It also examines bilingual documentation and the release boundary. The previous review records those original reports and their implementation.

The method inspects owning JavaScript, templates and contracts, then exercises transition boundaries with focused regressions that compare failing assertions before each fix with the repaired implementation. Theme checkers and the real sibling documentation site’s integration and browser suites provide the subsequent acceptance evidence.

At this snapshot, the public release, documentation go.mod pin and configured public version are still v1.0.0. The blog consumer’s theme pin is unchanged.

Findings and repairs

Five P2 correctness defects were reproduced and repaired in theme commit 08f6563, pushed to main. They concern ordering in the new APIs and existing focus/navigation behavior. They require no new configuration format or content migration.

Finding Trigger and observed failure Minimal repair
P2: sidebar readiness fires before hydration A consumer awaits OinkSidebar.ready or handles oink:sidebar-ready. The readiness microtask can run between DOMContentLoaded listeners. The cached sidebar’s active path is not yet hydrated, so consumers see incomplete initial state. After all initialization listeners and aside placement finish, resolve readiness in the next task. Preserve the existing ready Promise and event contract.
P2: a pending action can enter a native choice menu Start an asynchronous search-tail action, then activate a native choice such as theme selection. The pending guard ran after the choice branch. This allowed that menu to replace the pending action’s rows. Check pending activation before any row-type branch. After completion, ordinary choice activation is available again.
P2: a collapsed right TOC rail remains focusable Collapse the desktop right rail. Its hidden control and links remain keyboard targets. Focus can stay inside the hidden panel. Apply inert and aria-hidden to the rail panel. Move focus to the visible restore control. On restoration, return focus to the column control. When relocated, keep the movable aside outside that isolation.
P2: arrow navigation skips non-link groups From a child of a divider-only group, Left/a cannot consistently return to the parent disclosure and fold it. The group button is absent from the tree’s focus sequence. Include group disclosure buttons in tree focus navigation and direct-parent traversal. Right/d opens or enters the group. Previous/next page navigation still uses links only.
P2: drawer focus wrapping counts inert descendants In the mobile drawer, collapse an aside group and wrap with Shift+Tab. Hidden descendants still count as focusable. They can make the wrap fail or leave focus stuck. Exclude controls under inert or hidden from the drawer’s focusable set. Also exclude controls with hidden/collapsed visibility.

Implementation and regression ownership:

Finding Theme implementation Owning regression
Readiness assets/js/sidebar-state.js tests/js/sidebar-state.test.js; site tests/browser/community-feedback.spec.mjs snapshots the active path from both readiness signals in EN/ZH
Pending choice assets/js/command-palette.js tests/js/command-palette.test.js exercises pending extension → native choice → completion → available choice
Right rail assets/js/docs-shell.js Site tests/browser/community-feedback.spec.mjs covers EN/ZH collapse, Tab traversal, restoration, reload and aside relocation across desktop/tablet/mobile
Group keys assets/js/keyboard-nav.js tests/js/keyboard-nav.test.js covers LTR/RTL, arrows/WASD and link-only paging. Site community tests exercise real EN/ZH groups.
Drawer trap assets/js/docs-shell.js Site community tests collapse relocated groups and wrap Shift+Tab and Tab. They assert that focus never enters an inert or hidden subtree.

The readiness and pending-choice regressions failed against the previous implementation before their fixes. The right-rail browser assertions also failed in both English and Chinese before isolation was added. The repairs remain small: they change timing, move one pending guard earlier, add explicit rail isolation, and adjust tree focus targets and the drawer’s visibility filter.

These changes preserve the already accepted behavior: both root collectors honor sidebar_root_menu: false, and non-link groups retain their children. Pointer focus avoids incidental article outlines while keyboard cues remain visible. Search-tail callbacks retain their cancellation and handoff contract. The image preview fix continues to use an accessible name without inserting helper text into copied article content. Final regression results are recorded below.

Documentation readiness

The current documentation update covers 28 files in 14 EN/ZH pairs:

  • The six Design contract pairs use candidate-v1.1.0. They describe implemented main behavior without announcing a published release.
  • Navigation, layout and front-matter guides match current root filtering, divider groups and bilingual deployment paths. They also match the centered navbar, narrow-screen drawer and in-place navbar reveal behavior.
  • Organization and palette guides explain runtime load order, readiness and feature detection. They also explain site-owned persistence/integrations. Keyboard and image guides explain the fixes and the older-version boundary.
  • Installation guidance distinguishes the validation toolchain from the public version. Existing heading IDs remain stable. The new sidebar API heading has a matching Chinese ID.

The two 1.1.0 release-note files and two upgrade-guide files are also prepared. The release note remains a draft/candidate. Both home-page release entries point to the published 1.0 version.

Validation snapshot

Counts below describe the 2026-09-20 snapshot for theme 08f6563. Site acceptance uses the sibling checkout through a command-scoped module replacement. Local site checks used Hugo Extended 0.166.0, Node 26.9.0 and Playwright 1.62.1. Candidate CI used the pinned Hugo 0.165.0 toolchain. The 0.160.1 floor was checked separately with the official binary.

Check Result and scope
Baseline 75052f8 CI Passed all three jobs: pinned Hugo toolchain, browser runtime tests and Book publication. Exact baseline run.
JavaScript unit suite after the fixes Passed: 44 tests.
Official Hugo Extended 0.160.1 Passed the focused i18n and shell checkers. i18n covers 32 catalogs × 194 messages. The real documentation site also passed a production build against the local candidate with --panicOnWarning: 376 pages per language. The draft release is absent, and both home-page links point to 1.0.0.
Bilingual source and style checks Passed including this report: 129/129 page pairs, 988 source headings, Markdown style and git diff --check.
Final focused theme checkers Passed: shell, palette, keyboard and image zoom.
Final real-site non-browser suite make check passed all 57 tests. It checked 200 rendered content pages, 331 linked HTML pages, 39,803 internal links and 3,863 fragment links. Only the two expected Markdown goldens changed, for the release summary and documentation index. The floor production build also passed link checks: 327 pages, 39,059 internal links and 3,833 fragments.
Final browser suite make browser passed all 149 Chromium tests in eight suites. The suites contain 30 accessibility, 45 responsive/blog/palette, 16 keyboard, 14 content components and 18 code blocks. They also contain 4 scenarios, 5 theme-color and 17 community regressions. Coverage includes the full multilingual sitemap and six viewport widths. It also includes light/dark, forced colors, clipboard and no-script cases.
Agent documentation sample 93/100 (A) across 50 same-origin sampled pages. Sampled links resolve. 49 pages provide Markdown, and all 270 sampled code fences close correctly. The checker warns that the HTML llms.txt discovery hint is missing or too deep.
Rendered review Reviewed the Chinese release note in a desktop dark view and English in a narrow light view. Right-rail collapse removes its descendants from the accessibility tree. It also moves focus to the restore button. Restoration returns focus to the visible rail button.
Final theme revision and its CI 08f6563 passed all three jobs: Hugo 0.165.0, browser runtime tests and Book publication. Exact candidate run.
Public v1.1.0 tag, consumer upgrade and deployment Not performed.

Within this review’s scope, no unresolved implementation blocker remains. The candidate is ready for the publication steps below.

Repeat the checks from sibling checkouts. During development, keep the published dependency pin intact:

# From the theme repository
node --test tests/js/*.test.js
python3 bin/check-shell.py
python3 bin/check-palette.py
python3 bin/check-keyboard.py
python3 bin/check-image-zoom.py

# The site Make targets apply a command-scoped sibling module replacement.
make -C ../oink.pgsty.com check
make -C ../oink.pgsty.com browser

Remaining publication steps

Publication has not been executed. After the final revision passes acceptance:

  1. Finalize CHANGELOG.md, the release date and the release record. Publish the v1.1.0 tag and GitHub Release from the verified theme revision.
  2. Verify that the module proxy resolves that tag to the intended revision.
  3. Update the documentation consumer pin and version configuration together with its home-page release entry and contract status. Set the release-note state to draft: false in the same update.
  4. Rebuild and accept the documentation site using the published dependency, without HUGO_MODULE_REPLACEMENTS. Deploy it and verify the public routes.

A future improvement is an earlier, consistent llms.txt discovery hint for agents entering through HTML.

Limits

Browser verification ran in Chromium. The automated accessibility gate covers theme-owned surfaces while retaining its existing exclusions for vendored Redoc and Swagger UI, and Hugo 0.160.1 floor checks ran on the focused i18n, shell, and production build paths.

Publication follow-up

After this review, the v1.1.0 release was published on 2026-09-20 from 3a18234. Only the changelog differs from the accepted 08f6563 implementation. All three release-commit CI jobs passed before the annotated tag and stable GitHub Release were published.

A download with a fresh cache, using only the official Go module proxy, resolved the tag to that exact commit. Its .info, .mod, .zip, version-list entry and signed checksum record were verified. The module checksum is h1:121L5g57ChRCPyidzEBBcln2Co+0zYRQ+XDDXjymd0Q=. The go.mod checksum is h1:pHvbUhJCfseB41n5RGwsF7abT3i32VSTpofLQoq4b7Y=. The public records are the proxy version and checksum entry.

The documentation publication update pins v1.1.0 in go.mod and go.sum. It aligns the advertised version and both home-page release entries, and publishes both release notes. It also promotes the six contract pairs to released-v1.1.0. The historical acceptance tables above continue to describe the earlier sibling-checkout run. The site’s Site checks and Browser quality workflows track published-dependency validation separately, with both Go and Hugo module workspaces disabled.

Local validation of this published module passed all 57 non-browser tests and 26 focused Palette/community browser tests. It also passed the strict production build with 378 pages per language. The checks ran with GOWORK=off, HUGO_MODULE_WORKSPACE=off, and no HUGO_MODULE_REPLACEMENTS. The publication commit’s Browser quality workflow also runs the complete 149-test browser suite.

8.10 - CLI maintenance acceptance on 2026-10-03

Dated source and binary evidence for the local R1–R8/A18 program, preserving the initial audit, failed trials, and final acceptance scope.
Historical CLI maintenance acceptance ledger (2026-10-03 to 2026-10-04)

This record preserves the initial audit, intermediate trials, and local R1–R8 and A18 runtime/archive acceptance for the CLI maintenance roadmap. On 2026-10-04, the CLI surface was simplified to the Cobra/text/JSON/YAML command set defined in the current CLI contract and CLI introduction. These results apply only to the recorded historical source and binaries; later changes to the reduced CLI require separate validation.

Scope and evidence rules

The maintenance roadmap defines the authorized R1–R8 scope. The current CLI contract defines its compatibility baseline; the original roadmap does not add Docsy migration, version lifecycle, OpenAPI, theme publication, or the conditional E1–E4 extensions to this program. Hugo remains an external renderer. Generated sites remain ordinary Hugo projects.

Stages are accepted in dependency order. Each stage needs a complete usable flow supported by owning tests and relevant actual Hugo integration, together with known limits, a reviewable diff, and accepted EN/ZH contract and guide updates. New public behavior moves from the proposal into the owning contract only after its implementation and acceptance evidence exist.

In the tables below, existing, not rerun means code or a named test was inspected but its current runtime outcome was not established. Partial means the first candidate provides a reusable part of the required behavior. Open means new implementation or decisive acceptance evidence is missing. Passed, failed, unverified, and unsupported describe a specific executed input and scope when later runs are recorded.

Inspected inputs and tools

The initial 2026-10-03 audit read both repositories’ instructions and the documentation README and translation rules, both maintenance PRD languages, the original proposal, and the current CLI contract. It also inspected existing Go packages and test names. Execution was limited to version and Git inspection commands, without running the owning suites or writing consumer sources.

Input Observed initial state
Host and Go darwin/arm64; go version go1.27.1 darwin/arm64
Hugo hugo v0.166.0+extended+withdeploy darwin/arm64, Homebrew build dated 2026-09-09
Node and npm v26.9.0; 11.19.1; contributor/documentation tools, not CLI consumer requirements
Git 2.54.0 (Apple Git-157)
CLI source e623d93d589c49e5c58b8fae1bd5db720fc904cb, main; clean initial tracked/untracked status; generated bin/, dist/, tmp/ ignored
Documentation source 907d873eb05cfc2e194f492462dfa94849e93474, main; 184 initial porcelain entries, including existing proposals, contracts, guides, and unrelated content changes
Embedded Starter 137843b25bacd76ddd1f7ce71330bf2e3155b954; provenance and license already recorded by internal/starter
Declared theme baseline github.com/pgsty/oink v1.1.0 in Starter and the three selected sites; effective resolved bytes still require each acceptance run

The 2026-09-29 acceptance record provides baseline reproduction inputs from the first candidate.

Stage requirements and implementation evidence

Stage Required complete flow and invariants Initial implementation evidence Acceptance evidence still needed
R1 Shared page identity, languages, publication state, source provenance, actual outputs, translations and observed references from Hugo; oink.yaml owns check policy only; links/translations/style share analysis; severity and exclusions cannot hide required incompletion; trustworthy locations Partial: internal/site isolated snapshots and Page.OutputFormats probe, internal/outputcheck, internal/report; no shared translation/page facts or policy commands at initial audit Real Hugo routes, aliases, mounts, unlisted/generated-source cases and language relationships; public focused-check/policy cases; required unknown/tool/build/input failures remain 2; source locations only when reliable
R2 Three language layouts; strict/manual and localized policies; duplicate, missing and draft states; explicit versioned review records bind source language and source/translation hashes; bounded native syntax rules; effective-theme coverage; visible versioned baseline; reviewed fixes validate before narrow apply Open: no translation/review/native-rule/baseline public command at initial audit; rendered-reference checks remain reusable A04–A07; valid/invalid reviewed content corpus; no mtime review inference; disabled/localized languages handled; acknowledged findings stay visible; missing required checks stay incomplete; fix preservation
R3 Preserve thin default build/dev; build --check checks and manifests one strict Hugo output, exports only to new/empty target; digest/provenance manifest and optional minimal public identity; both local CI templates upload the same tree; release diagnosis; explicit-network public verification Partial: direct wrappers, strict isolated checks and licensed workflow inputs exist; managed build/export, digest verification, CI plans and public verify are absent at initial audit A08–A10; exactly one Hugo build; stale-byte rejection; revision/dirty/input/theme/tool/settings/coverage provenance without secrets or machine paths; workflow customization/conflicts/provenance and immutable source input; example address policy; fallback/language/resource/canonical/timeout/auth/rate-limit HTTP fixtures
R4 new, snippets and editor setup create ordinary inputs without overwrite; docs/blog/book/project profiles compose one licensed Starter; upgrades provide readable diff and old/new routes, aliases and enabled outputs; unsupported migrations give manual action; existing protections survive Partial: fixed archive language profiles and hash-bound single-site module upgrade with candidate validation, backups, dirty/workspace/replacement/vendor protection A11–A12; all new profile/language combinations build with ordinary Hugo; unknown editor settings retained; upgrade route/capability regression and readable diff; source provenance and licenses retained
R5 inspect, impact --since, bounded context, preview move; shared plans include touched files, diff, base hashes, translations, attachments, output/route changes and alias advice; candidate validation and stale/concurrent-safe recovery; ambiguous references require review Partial: module-specific upgrade plan/apply primitives; no shared content plans or inspect/impact/context/move flow at initial audit A13–A15; deleting B includes unchanged inbound A; translation/attachment/derived-output impact; uncertain/global changes force full checks; no content execution; candidate/stale/failed-write preservation and ambiguous-link handling
R6 Explicit versioned site registry reuses single-site engine; per-site and aggregate completion; writes only to selected sites; configured preinstalled markdownlint/Vale/lychee adapters normalize findings and declare syntax/network coverage Open: no workspace/adapter public command at initial audit A07/A15/A18; direct/per-site parity; no sibling discovery, implicit installation or default formatting writes; required missing tool 2, optional omission visible, external network uncertainty distinct
R7 Read-only loopback Studio with overview, issues, translation comparison, page relationships and publication views; filters, known sources, actual Hugo preview, comparisons and copied actions; CLI parity; prebuilt assets; explicit allowlist, separate preview origin, Host/Origin/session protection Open: no Studio server or assets at initial audit A16; browser/keyboard/screen-reader/mobile/light/dark/long-list flows; same underlying results as CLI; unauthorized hosts/origins/sessions and preview-to-management requests rejected; Node unnecessary for consumer runtime
R8 Markdown/text and front matter forms, selected components and collision-safe attachments reuse plans; authorized allowed writes with visible diff, hashes and candidate validation; no-op bytes and unknown fields/comments/order/encoding/whitespace retained; unsupported form syntax stays text Open: editing follows accepted read-only R7; no editor API at initial audit A17/A14; byte-identical no-op, surgical YAML field updates and text fallbacks; stale external-editor saves, traversal/symlink escapes and preview requests fail safely; attachments never overwrite; no management API in static publication

Evidence pages

The stage-by-stage receipts are kept on two companion pages, moved there unchanged on 2026-11-06 so each page stays small enough for people and agents to read whole:

  • R1–R5 evidence: local validation for R1 to R3, authoring and upgrade acceptance (R4), and implementation and documentation acceptance (R5).
  • R6–R8 and A18 evidence: workspace and adapter acceptance (R6), the read-only Studio candidate (R7), accepted reviewed editing (R8), and the 2026-10-04 runtime completion supplement (A18).

Acceptance case ledger

This ledger combines the initial audit with accepted R1–R7 evidence and the qualified R8 candidate gates.

Case Required outcome Code or checker evidence Status and missing decisive evidence
A01 One oink.result/v1 JSON result. Stderr logs. Policy 1, required incompletion 2 Protocol/public R1–R8 commands, frozen owning tests and exact-binary CLI/API reports. Unchanged result schema. Current eight owning gates/Linux qualification plus unchanged-runtime carry-forward of the preceding corpus in #a18 Passed supported current command scope
A02 Hugo resolves slug/url/permalinks/aliases, mounts, unlisted pages and language roots Real PageFacts/manifest/custom-mount/translationKey fixtures. Preserved ordinary artifacts. Final consumer facts R1 scope passed
A03 Definite local missing routes fail. Outside origin/path and declared external scope classified honestly Actual rendered-reference fixture plus subpath/policy regressions and final real sites Passed the required A03 scope. External availability remains unchecked
A04 Filename, directory and translationKey. Duplicate/missing/draft cases. Strict/localized policy R2 translation engine, actual Hugo/public commands, final reports and numeric supplement Passed R2 required scope
A05 Absent record unknown. Changed source/translation hash visible. No mtime inference R2 hash/status/diff, public preview/apply and final reports Passed R2 required scope
A06 Real fences, inline code, shortcodes, HTML, attributes, unknown fields and protected text boundaries R2 actual syntax/provenance fixtures, reviewed corpus and final reports Passed R2 required scope. Catalog and unsupported-source limits remain explicit
A07 Acknowledged findings visible. New findings block per policy. Required unavailable tools cannot pass R2 baseline/public plans. R6 fake/actual protocol, missing/unsafe/offline/network-uncertainty and required-precedence fixtures passed Supported scope passed. Required unavailable/uncertain tools remain 2
A08 Post-check bytes invalidate manifest. Provider uploads verified tree without another build R3 manifest/export/tampering/public one-build tests. Final ordinary-Hugo comparison and provider rehearsal Passed R3 required local scope
A09 Both CI templates. Custom workflows preserved. Permissions/variables/provenance and stale plan protection R3 offline generation/bootstrap, public preview/apply/stale-input tests, custom workflow supplement and local rehearsal Passed R3 required local scope. Custom workflows remain unknown and unchanged
A10 Reject HTTP 200 fallback, wrong language/build, missing resource/canonical mismatch. Incomplete timeout/auth/rate-limit R3 explicit-network local HTTP and public result fixtures, including required identity absence Passed R3 required fixture scope
A11 All declared profiles/languages. Target protection. Ordinary Hugo. Unknown editor settings retained R4 24 ordinary Hugo/public profiles, full Starter authoring/editor flow, snippets, actual mounts, source identities, JSONC preservation and external schema reproof Required supported R4 local implementation/corpus scope passed. Documented unsupported editor inputs remain explicit
A12 Readable diff and route comparison. Dirty/workspaces/replacement/vendor. Recovery/concurrency Frozen actual-Hugo seven synthetic pinned cases, public upgrade, source/external guards, observed alias retarget and guarded partial rollback Required bounded R4 local implementation/corpus scope passed. Unknown redirects/multihost remain incomplete
A13 Deleted B finds unchanged inbound A. Translations/attachments/derived outputs. Global full scope R5 committed Git/actual Hugo deletion, alias-inbound, global/uncertain input and unavailable-baseline fixtures. Exact-binary consumer reports Passed required supported R5 scope. Unavailable or unproven historical inputs stay explicit 2
A14 Candidate before apply. Stale/hash/write failures preserve later edits. Ambiguous references unchanged R2/R4 shared safety, R5 full-mode/inventory moves and R8 regenerated intent/fresh-input candidate validation, guarded writer and stale/late-editor/attachment tests. Current eight owning gates/Linux qualification plus unchanged-runtime carry-forward of the preceding corpus in #a18 Passed supported R5 CLI and R8 CLI/Studio editing scope. Ambiguous or unavailable required inputs still block
A15 Workspace/direct parity. Selected writes only. Bounded context with paths/versions/reasons. No content execution R5 bounded captured-source/context fixtures and four-site queries. R6 registry/direct/aggregate parity and explicit-name saved apply with other sites preserved Supported context/workspace scope passed. No implicit batch writes
A16 Five useful CLI-parity views. Keyboard/mobile/light/dark. Source/preview isolation Accepted R7 evidence retained. Historical source-bound R8 read-only 14 axe/screenshots and Editor 12 axe/screenshots with unchanged UI bytes. Current backend gates, ARM and corpus separately verified, native/API parity, preview isolation, four consumers and canonical render passed. Current eight owning gates/Linux qualification plus unchanged-runtime carry-forward of the preceding corpus in #a18 Passed supported local views. Required partial-preview incompletion/native findings remain visible
A17 No-op bytes. YAML unknown/comment/order preservation. Stale-save and attachment collisions rejected Corrected frozen core/public/guarded-writer race, actual Hugo/tools, source-bound Editor/read-only browsers, exact-binary four-consumer proposal parity/preservation and guarded canonical source/render passed in #r8. Current eight owning gates/Linux qualification plus unchanged-runtime carry-forward of the preceding corpus in #a18 Passed supported local editing scope. Required partial preview/native findings still block Apply. Final A18 separate
A18 Actual declared macOS/Linux runtimes. Child signals. Provisioned offline runs. Honest unsupported inputs Current freeze/source and repeated five-archive reproduction. Darwin arm64, native Linux arm64 and emulated Linux amd64 nonroot ext4/full offline unit-vet/selected Hugo/native archive/signal smokes passed in #a18 Passed current declared runtime/archive scope. Optional guest prerequisites remain explicit skips. Darwin amd64 is experimental/unverified and Windows outside scope

Candidate sites and source preservation

The selected acceptance inputs include the embedded Starter and three distinct maintained consumer sites, reusing the historical corpus without writing consumer sources. The Starter source checkout provides provenance, while generated profile trials use disposable directories.

Input in the sibling checkout layout Initial observed identity and purpose Current candidate acceptance
oink-starter / generated Starter Source 137843b, two initial status entries. Licensed fixed archive, language/profile/root/subpath trials R1 bilingual init/check and R4 all-profile ordinary/public authoring flows passed. Archive/license unchanged
oink.pgsty.com Source 907d873 with existing changes. Bilingual documentation/regression and explicit local-theme trial Final R1 check and source preservation passed. Local-theme evidence remains distinct from public-pin evidence
pig.pgsty.com Source 75050c0, five initial status entries. Root Docs/Blog rewrites and nonrendering sidebar entries. Declared v1.1.0 Final R1 check and source preservation passed
repo.pgsty.com Unborn main, no HEAD revision. Materialized untracked sources, generated catalog and declared v1.1.0 Final R1 check and source preservation passed. Revision remains unknown

For each run, record effective module source and versions, flags/network policy, exit/result/coverage, raw evidence location, and preservation outcome. Before/after inventories must include all tracked and non-ignored untracked source bytes and modes, Git status/index state, workspace/replacement files, and effective vendor inputs. Compare exact inventories. Keep reports, isolated candidates, output and caches outside consumer sources and outside Git. Full-build timing comparisons must use the same current input baseline.

Owning checks and documentation gate

Start with the smallest affected Go packages and public behavior tests. The existing repository gates are make test (offline tests and vet) and make test-hugo (actual Hugo Starter, snapshot, manifest and public command fixtures). The owning Hugo gate now runs all owning packages without the old narrow test-name filter. New fixtures must remain in that gate. Use a race run for concurrent plan/server changes when the focused tests justify it. Unit fixtures remain offline. Networking requires explicit invocation.

For documentation, preserve EN/ZH heading number, order and stable explicit IDs. Use these narrow source checks:

node scripts/check-markdown-style.mjs content/docs/design/research
node scripts/check-doc-translations.mjs

Both source checks passed after this record and its Chinese peer were added. Eight Chinese research files passed the style checker. Translation source coverage was 137/137 pairs with 1,082 source headings.

After building the relevant site, complete the rendered documentation gate:

npm run _check:markdown-style
npm run _check:translations
npm run _check:rendered-markdown
npm run _check:rendered-links

make build validates the declared published pin. make check selects the sibling theme for the complete non-browser regression suite. Studio uses its own actual browser and accessibility checks.

Delivery state and remaining limits

State Current completion evidence. History retained above
Local implementation Finite R1–R8 supported implementation completed locally, including Studio/read-only and opt-in reviewed editing. Current A18 runtime/archive scope passed. Canonical lifecycle rendering is bound separately to these exact bytes
Local validation Historical R1–R8 owning/browser/corpus/render records retained. Current 2026-10-04 backend correction and eight current owning gates, actual three-target runtime/archive checks and unchanged-runtime carry-forward of the preceding four-consumer preservation/parity passed in #a18. Required repository findings/partial preview remain visible. Rendered navigation/URL checks have a separate exact-byte receipt boundary
Commits Baseline CLI commit identified
Archive and runtime qualification Current corrected source: Darwin arm64, native Linux arm64 and QEMU-TCG-emulated Linux amd64 passed installed archive/offline/signal/filesystem flows. Two fresh builds reproduce all five archives. Darwin amd64 remains experimental/unverified after actual failed execution
Public distribution and consumer adoption Not performed in this local validation run
Deployment and public-content verification Verified against local HTTP fixtures

The finite R1–R8 implementation and required current A01–A18 runtime/archive scope have local acceptance evidence. Known repository findings and required preview incompletion remain visible diagnostic outputs.

8.11 - CLI maintenance acceptance on 2026-10-03: R1–R5

R1–R5 local validation and acceptance evidence from the dated CLI maintenance record.

These R1–R5 sections of the dated record were moved here unchanged on 2026-11-06 so each page stays small enough to read whole. The scope, evidence rules, case ledger and delivery state remain on the main page.

R1 local validation

R1 now provides shared Hugo page/translation/source facts, rendered reference and anchor evidence, strict oink.policy/v1 input, check links, --format json, visible reviewed exclusions/external scopes and required-work precedence. Translation and style selections explicitly return required unsupported coverage while those engines remain unimplemented. Default build/dev remain direct Hugo operations.

Requirement Executed evidence Current outcome
Public result/policy and incomplete precedence make test: all packages and vet; public severity/exclusion/unimplemented-group/JSON-alias tests; TestEveryRequiredUncompletedCoverageFails Passed R1 scope; any required uncompleted status, including not_checked, remains 2
One build and shared facts TestPublicCheckSharesOneBuildAndRenderedFacts Passed; one strict Hugo build supplies page and observed target/anchor facts
Hugo authority and source mapping Actual TestPageFacts* fixtures: translationKey, actual routes/aliases, unknown generated nodes, custom mounts, excluded-page analysis and failure preservation Passed; separate analysis preserves production facts/artifact bytes and source bytes/modes
Repeatable real Hugo gate Corrected make test-hugo includes TestPageFacts* and TestHugoRendered*, alongside Starter and manifest fixtures Passed; scoped route/reference, reviewed external-scope and original-output preservation cases
Fresh Starter Bilingual init, check links, ordinary strict Hugo using isolated provisioned v1.1.0 module archives Exit 0; 223 files, 4,461 references, 66 page facts; dependency preparation remains explicit
R1 documentation source and schema Markdown style under content/docs; bilingual source checker; JSON parse and equality of CLI/docs result schemas; scoped diff whitespace check Passed: 88 Chinese docs, 137/137 source pairs and 1,085 headings; schemas remain additive oink.result/v1 with exits 0/1/2
Final candidate reports and rendered EN/ZH Refreshed current-binary consumer reports; actual rendered source/Markdown/link owning checks below R1 scoped gate passed; existing draft-release omission in production is recorded separately

Earlier offline R1 trials returned 0 without diagnostics on three consumers:

Earlier trial Source files Built files HTML files References Page facts Bytes/modes/Git inventory
OINK documentation 421 1,139 512 74,689 341 Exact before/after equality
PIG project site 858 1,392 424 64,440 248 Exact before/after equality
Repository catalog 2,294 3,287 1,635 851,535 1,572 Exact before/after equality

These earlier reports spell optional unselected coverage not_selected, outside the existing result-schema enum. The final code corrects it to not_checked and includes project.pages coverage. Their measured counts and exact inventories remain valid observations of the earlier binary. The final reports below establish final JSON conformance. Raw evidence stays in task-named local acceptance directories outside consumer sources.

The final R1 binary was rebuilt from the dirty CLI working tree based on e623d93d589c49e5c58b8fae1bd5db720fc904cb. The recorded input inventory includes file hashes, modes and Git-status identity. Its SHA-256, computed over sorted JSON serialization, is 518260f07f3c916468ee3d56c4eeca03c131514155aa82539564ccd2f3c1f664. The exercised binary SHA-256 is 3deb7e357fc86f6907df60da0769d93f2d41ba5e01949b641548a67d7f459d12.

Final current-binary trial Source files Built files HTML files References Page facts Acceptance
OINK documentation 421 1,139 512 74,755 341 Exit 0, valid result, complete page facts, exact source bytes/modes/Git preservation
PIG project site 858 1,392 424 64,440 248 Exit 0, valid result, complete page facts, exact source bytes/modes/Git preservation
Repository catalog 2,294 3,287 1,635 851,535 1,572 Exit 0, valid result, complete page facts, exact source bytes/modes/Git preservation

Each final result has required check.links: complete and project.pages: complete coverage. Unselected translation/style coverage is optional and reports not_checked. The final offline make test and vet passed; the corrected actual-Hugo owning target also passed. The recorded tools remain Go 1.27.1, Hugo Extended 0.166.0, Git 2.54.0 on macOS arm64. The three exact before/after inventories were independently compared while preparing this record.

Production output passed rendered Markdown and link checks. Its global translation checker returned 1 solely because the pre-existing draft content/blog/release/1.2.0.md / .zh.md pair is absent from production. The changed R1 pages rendered in both languages. A separate explicit analysis build set HUGO_BUILDDRAFTS, HUGO_BUILDFUTURE and HUGO_BUILDEXPIRED to true. All three owning checks passed: 137/137 paired sources, 1,085 headings, rendered Markdown and rendered links. That view checks excluded sources in isolation while keeping production output unchanged.

R2 local validation

The local candidate now implements translation policy/status/diff/hash review, syntax-bounded native content rules, visible reviewed baselines and shared oink.plan/v1 preview/validate/apply. Default check requires links, translations and style. Production output and the explicit draft/future/expired analysis are separate. Stable behavior and examples are in the contract. The R2 local gate passed owning checks, final frozen-input consumer reports and rendered bilingual documentation. The exact exercised binary and the subsequent narrow equality fix are recorded below.

Requirement Executed owning evidence Outcome and limit
A04 translation relationships/policy Actual TestHugoFilenameDirectoryAndTranslationKeyLayouts; scope, duplicate/missing/disabled-language, draft, strict/localized and selected-constraint tests Passed owning tests; no universal heading/code/localization parity
A05 explicit review and diff Full byte hash/current/source/translation/both-changed, mtime-independent, unknown/unreadable/ambiguous and malformed-record tests; public status/diff/review preview/apply fixtures Passed owning tests; review state is change evidence, not semantic judgment
A06 source boundary and provenance Actual Hugo enabled/disabled canonical title/block attributes and configured passthrough fixtures; front matter/CRLF/BOM/shortcode/code/HTML tests; every public v1.1.0 source/license SHA verified Passed owning tests; unsupported syntax remains incomplete and custom hooks remain outside catalog attestation
A07 baseline scope Capture/visible acknowledgement/new finding/incomplete precedence and malformed-record tests; public baseline preview/apply fixtures Passed R2 baseline scope; external tool adapter acceptance belongs to R6
A14 shared metadata plans Stale bytes/modes/existence/guards; edits during validation; exclusive commit collision; partial restore; later editor bytes/modes/deletion; old open inode write; new-directory children; confinement/identity/diff tests Passed owning tests and vet; candidate/source overlap refused; later move/reference ambiguity remains R5 scope
Frozen runtime gates macOS arm64 make test/vet, owning actual Hugo and focused race runs Passed; logs /tmp/oink-r2-frozen-go-gate.log, /tmp/oink-r2-frozen-hugo-gate.log, /tmp/oink-r2-frozen-race-gate.log; final all-owning-package Hugo gate /tmp/oink-r2-owning-hugo-final.log explicitly includes configured passthrough
Bilingual documentation Narrow source style/pairing/IDs, equal result schemas, scoped whitespace and actual production/analysis node checks Passed scoped gate: 88 Chinese docs, 137/137 source pairs and 1,092 headings; production draft omission separately recorded below

The frozen parser corpus at /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r2-source-corpus-lqx25kwr/summary.json records parser input SHA-256 a601200ec4fe275d2bd4baf11d4db7d46a2cc6f1674900c1fd801769e55d12de. Each scope parsed completely with zero findings. The core uses actual Hugo site-source identities from the recorded configuration. Supplemental Markdown includes disabled/unpublished files. It does not invent routes or relationships. These captures precede the authorized R2 documentation edits.

Corpus Unique actual Hugo source files Supplemental local Markdown Source inventory files Bytes/modes/Git
Starter 52 78 97 Exact before/after equality
OINK documentation 272 274 421 Exact before/after equality
PIG 212 212 858 Exact before/after equality
Repository catalog 1,568 1,572 2,294 Exact before/after equality

Preliminary public-command reports at /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r2-final-qu_zprps/summary.json used binary c8d87e6d73d3101fefcb62c5d6845518573c02c400f474dc9f4603afafc774d5 and CLI input inventory d8a75be0e074365a4164b7aaaa27d82a1e844e04406a36c3dd6d39ff2b6e873f. They precede the final parser/doc freeze and are not final acceptance evidence. The initial Starter invocation selected the enclosing evidence folder and returned 2. This was a validation setup error. Selecting its actual site child returned 0, with evidence in /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r2-starter-27vmi0w5.

Preliminary check Exit Page facts Built files References Translation statuses Outcome
Correct Starter child 0 66 223 4,461 28 Complete; 97 source files/inventory unchanged
Documentation 0 341 1,139 74,755 144 Complete; 421 source files/inventory unchanged
PIG 0 248 1,392 64,440 120 Complete; 858 source files/inventory unchanged
Repository catalog 1 1,572 3,287 851,535 788 Completed policy check: 10,462 actual HTML_ID_DUPLICATE findings in existing merged-print output; 2,294 source files/inventory unchanged

The repository catalog run completed with policy findings from existing duplicate HTML IDs in merged-print output; informational review states remain visible.

The final frozen-input reports at /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r2-candidate-6xzcs7fk/summary.json exercise binary SHA-256 ff88b407a6cddb9007f94275c65a80ed4c9c4fd13f5e821f9b7a4a8973abaa56 from CLI input inventory bd8c71b55250a89dc15c7534924bb82a5447d6f2628eba23c8cb3d864309ee9f. All four exact source byte/mode/Git inventories were independently compared equal before/after. These reports supersede preliminary public-command trials:

Final check Exit Source files Page facts Built files References Translation statuses
Starter 0 97 66 223 4,461 28
Documentation 0 421 341 1,139 74,825 144
PIG 0 858 248 1,392 64,440 120
Repository catalog 1 2,294 1,572 3,287 851,535 788

No final report has incomplete diagnostics. The repository catalog retains 10,462 actual merged-print HTML_ID_DUPLICATE findings and 788 informational review states; the other sites retain informational unknown review states.

Kept production docs at /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-site-2201601475/public passed rendered Markdown and links. Global translation checking returned 1 only for the existing draft release 1.2.0 pair absent from production. The separate draft/future/expired analysis at /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-site-3698773232/public passed all three node checks: 137 pairs/1,092 headings, 216 content pages/41,586 text nodes, and 347 pages/48,682 internal links/4,171 fragments. Evidence logs are /tmp/oink-r2-docs-production-{translations,markdown,links}.log and /tmp/oink-r2-docs-analysis-{translations,markdown,links}.log.

A final review identified optional equal_fields comparing JSON 7.0 with YAML/TOML numeric 7 by representation. The narrow supplement now normalizes decoded numeric values recursively to an exact rational number tag, preserving strings versus numbers, map keys and array order. Tests cover decimals/exponents, negative zero, integers beyond float64 precision, and nested differences. They also cover source byte preservation and required incompletion for unrepresentable values. Actual-Hugo translation tests passed in /tmp/oink-r2-numeric-translations-gate.log; all public maintenance actual-Hugo cases passed in /tmp/oink-r2-numeric-public-gate.log; owning vet and whitespace checks passed. Supplemental source SHA-256 values are:

Source SHA-256
internal/translations/check.go 24664377e14b4ae2fc554d0d7fde2ec33cc987707250e130fd88d9a25d5e1637
internal/translations/translations_test.go f58f4a305fe9fe3f5500ddfcf85faf3cfa37d72f8c220a1cb16ce4ccfbddb74d

The frozen real-site reports and Linux qualification predate this supplement; because those sites configured no numeric equality constraint, the fix does not affect their recorded outputs.

At this stage, macOS arm64 was exercised; an attempted Darwin amd64 runtime on this host failed with arch -x86_64 / posix_spawn: Bad CPU type in executable (/tmp/oink-r2-darwin-amd64-gate.log) because Rosetta was not installed. Both native Linux arm64 and Docker Desktop Rosetta-emulated Linux amd64 executed the same runtime/schema/license inputs. Their SHA-256 is 0f786df68ef3c4844c983a51595f79242d1cb1d2bf6c5b5eb7f2c6415fb8d861. Evidence is retained at /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-a18-linux-ajbbnvki in arm64-results, amd64-results, commands.json, candidate-inputs.json, preparation.json and qualify.sh. Each target passed 270 test/subtest cases with zero failures and two optional external corpus/provenance skips. Checks included full actual-Hugo go test ./..., vet, and built CLI version/bilingual init/doctor/full check/translation status, plus missing-Hugo exit 2 smoke. JSON stdout and source byte/mode inventories were verified. Go 1.27.1 ran on Linux arm64; Hugo Extended 0.166.0 architecture assets were SHA-verified.

R3 local validation

R3 adds managed build --check, oink.artifact/v1 sealing/export/local verification, explicit-network HTTP verification, release diagnosis and guarded local CI generation. The default build/dev path remains ordinary Hugo. The executed runtime and paired contract/guide gates passed.

Requirement Executed owning evidence Outcome and limit
A08 one checked artifact Public fake/actual Hugo one-renderer tests; exact export, manifest/marker, post-check byte/mode/missing/extra/symlink tampering, failure/concurrency and source-preservation tests Passed local scope; a failed/incomplete check cannot seal/export; local artifact verification does not rebuild
A09 both CI providers Offline deterministic generation, pinned source/Hugo archives and action revisions; safe bootstrap archives; guarded public preview/apply/stale-input cases; actual-Hugo original-input binding Passed local configuration scope; every existing generated target is refused and custom workflows remain unchanged
A09 upload identity Both local provider rehearsals and TestProviderUploadRehearsalPreservesActualSealedManifestIdentity Passed: one managed build, separate verification, then the same tree; GitHub tar includes the hidden marker, Cloudflare rehearsal receives that verified directory; no provider upload executed
A09 custom workflow diagnosis Generated-plus-other-custom and standalone-custom/no-metadata public tests, actual-Hugo preview and owning vet Passed supplement in /tmp/oink-r3-ci-custom-owning-gate.log and /tmp/oink-r3-ci-custom-vet-gate.log; each unrepresented workflow stays unknown, informational and optional release.ci: not_checked, including beside valid generated metadata
A10 deployed identity Local HTTP fixtures for all recorded files/routes/languages, marker, canonical/base/inert-template behavior, HTTP 200 fallback, wrong bytes/language/build, missing resources/Markdown/search JSON Passed local fixture scope; definite mismatches return 1; browser JavaScript is explicitly unchecked
A10 unknown network state Explicit network/credential refusal, timeout before headers/during body, authentication/rate-limit/server errors, required marker absence, bounded body/gzip and redirect/no-cookie fixtures Passed local fixture scope; incomplete states return 2 with remaining requests unknown; no public deployment was contacted
Frozen runtime gates Full tests/vet, owning actual Hugo and focused race checks Passed on macOS arm64 in /tmp/oink-r3-frozen-go-gate.log, /tmp/oink-r3-frozen-hugo-gate.log, /tmp/oink-r3-frozen-race-gate.log; the subsequent custom-CI change has the focused supplement above

The latest single-binary corpus is retained at /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r3-ci-final-ahc4csjk/summary.json. It compiled an exact captured CLI input copy, with binary SHA-256 425845c1d2db7b1cd3c3cdb5f28475cb06ba6f656054909759e2359a39925dd2, 67 runtime/schema/license inputs SHA-256 6789a3a0235ff8d81453b9bfde37824979eac7d56af3710da390e4d2ef8479dc, and 108 broader CLI inputs SHA-256 4ca473a4cb586d232baeb4cee029b281469c5bb03c831cc199b95451e6832c60. Runtime inputs remained exactly equal after all runs. Live tools were Go 1.27.1 and Hugo Extended 0.166.0 on Darwin arm64. The manifest’s normalized Hugo version excludes vendor build text and private paths.

Each run used offline build --check. It used fresh external destination/manifest paths, the optional marker, and retained isolated work. These existing local consumer inputs were checked without --release. Their configured workspaces were preserved. Every raw report records exactly one strict Hugo renderer, zero incomplete diagnostics and zero required unfinished coverage.

Final managed build Exit Source files Copied source inputs Page facts Built files References Exported files Local artifact verify
Starter 0 97 94 66 223 4,461 224 0
Documentation 0 421 427 341 1,139 74,825 1,140 0
PIG 0 858 861 248 1,392 64,440 1,393 0
Repository catalog 1 2,294 2,299 1,572 3,287 851,535 None Not exported

Both inventories compare exact bytes, modes and file types before/after; the primary inventory also compares logical Git state. Git sites include tracked and non-ignored untracked sources; the non-Git Starter includes its existing generated files and lock. The supplemental copied-source inventory also includes ignored workspace/editor metadata read by snapshots, excluding existing generated output/cache trees. All four comparisons were exactly equal.

The repository catalog retains 10,462 existing merged-print HTML_ID_DUPLICATE findings, so neither destination nor manifest was created. Production review states number 28/143/120/786. Analysis includes unpublished pages, which explains the earlier R2 144/788 counts. Existing custom workflow information remains visible, and Starter’s example address is a warning in this non-release run.

The three fresh exports match the retained independent ordinary-Hugo trees in every original file’s SHA-256, size and mode. The sole extra file is .well-known/oink-build.json. Their original source inventories and complete manifest input hashes match the earlier capture, so reusing those ordinary trees does not substitute different inputs. The helper source SHA-256 is 13e4957a3d7847eb28c8b1eeba3588a4f4a9982c2bfca2ebc729ab2827159607; its binary SHA-256 is b2699fe7a7aa3a34c41f9e4aba4b22d39cf8d0c156a369f3dfc4ca8c8c0fbce5. Raw helper and ordinary evidence are in /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r3-candidate-wb643dhh; the temporary compilation source was removed after building the helper.

Earlier R3 captures preceded the runtime freeze (oink-r3-final-pisrr21h preceded custom-CI diagnosis), and an initial /Users/vonng/pgsty/PIG target selection returned 2 before switching to pig.pgsty.com.

The scoped R3 documentation gate passed at /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r3-docs-render-pljj5aqd/summary.json. Ten paired contract/guide/roadmap/index/overview edits were installed only after the original bytes/modes matched. Their recorded hashes are at /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r3-doc-drafts-s0b3g48l/applied-files.json. Source style passed 88 Chinese docs; translation coverage passed 137 pairs and 1,099 headings; schemas remained equal and scoped whitespace passed. Actual production Markdown passed 214 pages/41,871 text nodes; links passed 345 pages/48,344 internal links/4,171 fragments. Production translations returned 1 only for the unchanged draft release 1.2.0 absent from production. A separate draft/future/expired analysis passed Hugo and all three owning checks: 137 pairs/1,099 headings, 216 pages/42,177 text nodes and 347 pages/48,720 links/4,199 fragments. All 421 canonical and 488 copied source files retained exact bytes/modes throughout these rendered checks.

R4 authoring and upgrade acceptance

The supported R4 implementation and read-only corpus scope are locally accepted after frozen owning/full gates. This record covers profiles, ordinary authoring/editor/snippets and bounded upgrade views, along with guarded canonical documentation promotion and fresh scoped rendered validation.

Executed profile evidence Outcome and limit
One fixed licensed archive Snapshot verification against commit 137843b25bacd76ddd1f7ce71330bf2e3155b954 passed without --write; archive SHA e55bde279715f6d8d19d3d88671a2cf7561b515be46915b0f12c640d0ce1d958 and MIT license unchanged; projection metadata/script match
Composition and preservation Default/explicit project byte parity; selected archived model/localized home, invalid profile, nonempty target, concurrent validation/publication and cancellation recovery tests passed; unit/vet/race gates passed
Ordinary Hugo All four profiles × three language choices × root/subpath passed 24 actual warning-strict offline builds using provisioned public OINK v1.1.0; complete source byte/mode/no-extra-file and rendered-reference checks passed
Public init workflow Four profiles with en/en,zh, actual subsequent root/subpath Hugo URL facts/checks, workflow/license preservation and default parity passed; unknown/nonempty refusals 1, missing/failed Hugo 2, empty/absent targets and pure JSON/separate logs verified
Public authoring and source identity Actual candidate/apply/ordinary Hugo, review-unknown and source preservation passed in /tmp/oink-r4-authoring-public-gate.log; fresh-directory/site guards and vet passed in /tmp/oink-r4-new-input-race.log and /tmp/oink-r4-public-core-vet.log. Actual ignored input refuses 2 without a saved plan or source writes even when source groups are disabled; selected draft peers still force analysis identity in /tmp/oink-r4-authoring-sourceproof-gate.log. Supported owning scope passed
Bounded upgrade owning gate Seven actual-Hugo synthetic pinned module-fixture cases, observed-stream digest/inventory fidelity, independent cross-page alias-retarget blocking, source/concurrency/exclusive installation and later-edit rollback protection passed under race; vet passed. Final hardening logs /tmp/oink-r4-hardening-owning-gate.log, /tmp/oink-r4-hardening-final-focused.log, /tmp/oink-r4-hardening-vet.log; final public/full frozen gates passed
Integrated authoring/editor hardening Actual-Hugo language-directory plan/apply/ordinary builds, link/never new-source refusal, external schema/license/full-mode/module identity and legacy schema reproof, shared translation/baseline/CI regression and full Starter docs→new draft peer→editor→check→ordinary Hugo flow passed. /tmp/oink-r4-app-authoring-hardening-gate.log (58.241s), focused race and vet passed; post-candidate external mutation proof /tmp/oink-r4-app-external-during-validation.log passed. Opaque saved external-input hashes and canonical workspace-origin guards passed /tmp/oink-r4-external-plan-binding-final.log, /tmp/oink-r4-workspace-origin-gate.log and their vet logs. Frozen full-stage, corpus and scoped canonical rendered documentation gates passed
Actual language mounts Standalone ordinary per-language contentDir and explicit site-matrix fixtures each passed config/mounts/strict-render with source bytes/modes unchanged; Hugo0.166 emits sites.matrix.languages and distinct physical files with reciprocal public translations. /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r4-language-mounts-lgmve1sk/summary.json; public actual language-directory plan/apply/ordinary-Hugo integration passed

Owning evidence is retained at /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r4-starter-owning-0pv41lw5/summary.json. Logs are /tmp/oink-r4-starter-{unit,hugo,vet,snapshot,race}-gate.log and /tmp/oink-r4-public-init-gate.log, /tmp/oink-r4-public-init-vet-gate.log. Generated source counts are project 94, docs 58, blog 40 and book 34.

Final frozen gates all returned 0: make test/vet /tmp/oink-r4-frozen-go-gate.log, make test-hugo /tmp/oink-r4-frozen-hugo-gate.log and actual-Hugo core race /tmp/oink-r4-frozen-core-race-gate.log. The final public flow includes Starter docs → primary/translation draft → editor → check → ordinary Hugo; post-candidate external schema mutation still refuses before source writes. Seventeen owning and three final gate logs are retained verbatim with hashes in the final corpus’s owning-gates.json.

The exact four-site evidence is /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r4-corpus-lw2cjyq6/summary.json with bounded summary.compact.json, raw JSON/logs and per-command inventories. Binary SHA is c169b3d4d046c811dca80867068b86fb66ada5c8ce6910dd5cda7353c406f377; 82 runtime-input files bind SHA fdff7f50d49b44f03fa1db79eec6b6c9b9bd5e52f8967a88aed84b3207a7b3c6, which equals the final root inventory with no runtime changes. The broader 139 CLI inputs bind SHA 562e838d9eccb628eac86ae59b9b9587c1e23ad52991ec50eafb1e604e3924da. Driver SHA is d3ac41dc2e18295bfb26134d1a696935c8174913e2801a5766dbf7a1139d89f8. Actual tools were Go 1.27.1 and Hugo 0.166.0 Extended on macOS arm64.

Frozen consumer Primary/copied source files Pages; output files; references Managed build / artifact verify Read-only upgrade / new / editor
Starter 97 / 94 66; 223; 4,461 0 / 0; 224 exported files including marker 0 / 0 / 0
Documentation 421 / 427 341; 1,139; 74,937 0 / 0; 1,140 exported files including marker 0 / 0 / 0
PIG 858 / 861 248; 1,392; 64,440 0 / 0; 1,393 exported files including marker 0 / 0 / 0
Repository 2,294 / 2,299 1,572; 3,287; 851,535 Completed finding 1; no export/manifest Completed finding 1; new/editor not attempted after blockers

Each managed build used exactly one strict production Hugo render and had no required incompletion or uncompleted required coverage. Primary Git-visible source bytes/full modes/logical Git state, supplemental copied inputs and source directory modes matched exactly before/after every command and each complete site flow. Repo’s 10,462 existing merged_print duplicate HTML IDs remain visible.

Consumer upgrade previews selected the available public v1.1.0 pin and did not apply writes. Cross-version route/alias/output regressions use explicit synthetic fixture pins. New/editor plans were validated previews without saving or applying consumer plans. Multi-host and unknown relative-alias identities stay incomplete, and nondeterministic output requires a fresh v2 plan preview.

Fresh canonical documentation acceptance passed after applying the ten guarded files. Evidence is /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r4-docs-render-v01eima0/summary.json; the promotion manifest is /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r4-doc-drafts-3i8bw994/applied-files.json. The frozen c169b3… CLI performed one strict production render and its focused link check returned 0.

Fresh canonical documentation gate Executed result
Source owners Translations 0: 137/137 pairs and 1,104 headings; complete canonical style 0: 137 Chinese files, 181 strong spans, no emphasis; ten-file whitespace check and public JSON schema equality passed
Production rendered Markdown/links Both 0: 214 content pages / 42,214 text nodes; 345 pages / 48,360 internal links / 4,187 fragments
Production translations 1 solely for the pre-existing draft content/blog/release/1.2.0.md absent from production; no new pairing/heading finding
Separate nonpublishable analysis Fresh ordinary Hugo with the actual original snapshot environment/rebased paths and explicit draft/future/expired flags returned 0; all three owners 0: Markdown 216 pages / 42,520 nodes, links 347 pages / 48,736 links / 4,215 fragments, translations 137/137 pairs / 1,104 headings
Source preservation Canonical 421 Git-inventoried files and 427 copied inputs retained exact bytes, modes, Git state and directory modes; production copied 428 and analysis copied 427 files remained unchanged through their checks; analysis build also retained copied full modes

The temporary helper copied the frozen core without modifying it: helper source SHA 7faea7e726a6c6fb2e0747be1a4428f4c5fb5734fa52b6f981157a5fe37d9989 and helper binary SHA 532638e76f96f8b173c122e512b3bf5fc2c4d4a7130f59c99c2c69e135e87073 are retained with raw logs.

R5 implementation and documentation acceptance

R5’s supported local scope is accepted after focused public/core, corrected frozen full-stage, exact-binary read-only consumer and guarded canonical source/rendered documentation gates.

The actual public Git/Hugo flow at /tmp/oink-r5-public-final-flow.log passed in 53.963 seconds. Its committed synthetic site owns its local theme, bilingual pages and binary attachment. Ordinary modes 0640 and 0600 remain full current facts. Historic Git comparison uses only executable bits. Deleting B selects unchanged inbound A, the remaining translation, removed attachment and actual RSS output. Actual alias-inbound uncertainty, global configuration/template/data and unknown-input changes expand full scope.

Completed inspect/impact/context returns 0 with separate current-check findings 1. Check-since retains current quality 1 and full validation scope. Missing/unborn/foreign history returns 2. It retains every known current page/attachment/reference/output. It does not invent a prior identity or change. Malformed selectors/limits, missing tools and failed renderer logs are tested. Bounded context gives reasons/versions/source and excerpt hashes, visible omission/truncation and no execution of literal document instructions.

Saved move preview/apply and subsequent ordinary Hugo passed, retaining binary bytes, raw full modes, unrelated files and Git index/revision. Actual opaque HTML/shortcode references remain manual. Inline/fenced/opaque spans stay unchanged. Their broken final candidate returns 1, with no saved plan or source writes. Source/config/attachment/mode/fresh-target drift returns 2 and preserves the later edit. A deterministic mutation after the actual candidate renderer also refuses before writes and preserves editor bytes/mode. Focused actual move race passed in 8.286 seconds at /tmp/oink-r5-public-move-race.log; app vet passed at /tmp/oink-r5-public-vet.log.

Before the cached-module supplement, frozen parent make test/vet and make test-hugo both passed at /tmp/oink-r5-frozen-go-gate.log and /tmp/oink-r5-frozen-hugo-gate.log (actual app fixtures 185.709 seconds). Actual move/source race and vet passed /tmp/oink-r5-move-hugo-gate.log, /tmp/oink-r5-source-move-race-gate.log and its vet counterpart; full inventory/mode/selector plan safety passed /tmp/oink-r5-plan-owning-final.log.

The first frozen consumer trial exposed a cached-public-module guard gap. The original graph contained resolved module inputs that were absent from a fresh outer candidate hash. It returned false incomplete 2, without source writes. Content plans now resolve/capture the same module inputs before comparison. Legacy metadata/authoring plan scopes remain unchanged. The separate checksum-verified public OINK v1.1.0 regression passed preview, fresh saved apply and ordinary bilingual Hugo in 27.42 seconds (package 28.220) at /tmp/oink-r5-public-cached-module-move.log, including raw modes, binary bytes, unrelated inputs and Git preservation. Corrected current-binary corpus and supplemental race evidence remain separate from the earlier unaccepted trial.

The corrected current candidate passed full make test/vet at /tmp/oink-r5-corrected-frozen-go-gate.log and actual make test-hugo at /tmp/oink-r5-corrected-frozen-hugo-gate.log (app 278.787 seconds). The cached/public and committed/in-site move safety race passed in 38.578 seconds at /tmp/oink-r5-public-cached-seam-race.log; its app vet also passed.

/tmp/oink-r5-corrected-runtime-freeze.json records 96 runtime inputs with SHA-256 e5b6e0eda972116dbb94a8086668e6ef34bfaa56138cf31f1f71f4832c477842 and 165 broader CLI inputs with SHA-256 4965a0c92cb6126f67a6dabd548c7c25ee5d7c9c57e14cce5e55ebb7a22fca2d. The corrected binary SHA-256 is d7675aecca2f77b1eb37bb4f664c3314cf5207149e6abbb86523686c5c50bff0. The corrected four-consumer capture completed 16 commands in 831.825 seconds at /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r5-corpus-corrected-y2eue81h. Its bounded final-receipt.json has SHA-256 b86e0e6c7dbfbaed62c845c03a55d963068f7d9a16771de5ff3b0974e76fce3b; the receipt retains 12 copied owning gate logs and all 20 observed move routes. It links to the complete raw JSON/logs and per-move classifications.

Site Primary/copied inputs/directories Inspect/context Current check Impact Move preview
Starter 97/94/21 0/0 0 2: no Git baseline 0: validated, unapplied
Documentation 421/427/109 0/0 0 0: complete historical comparison 1: six candidate missing references
PIG 858/861/52 0/0 0 2: historical foreign-input provenance incomplete 1: 32 candidate missing references
Repository 2294/2299/48 0/0 1: 10,462 existing duplicate HTML IDs 2: unborn HEAD baseline unavailable 1: the same existing duplicate IDs

Starter and Repository impact retain known current facts without inventing prior pages or changes. PIG’s actual baseline is complete (theme v1.0.0 versus current v1.1.0). Required foreign-input provenance is incomplete. The comparison therefore expands full scope and returns 2. These are distinct outcomes. Documentation impact completes with 192 captured input changes, 343 affected prior/current pages and full scope. All completed fact queries expose current quality findings separately. Repository inspect/context remain 0.

Documentation move proves 18 rewrites and four routes. Two ordinary literal /docs/admin/comments/ occurrences in content/docs/customize/repository.md at lines 216 and 313 remain manual because repeated source/output occurrences cannot be attributed precisely across ordinary and print outputs. Their six missing candidate references block validation. PIG moves two Markdown files and four binary attachments, with eight proven page/processed-resource routes. Equal-byte paired outputs prove processed featured_hu_* resources, but not new URLs for the four original absolute image references /article/pgext-day/{featured,topic,venue,schedule}.webp. Their 32 candidate missing references block validation. Original-asset rewrites are not guessed. These ordinary Markdown limits are separate from opaque HTML/shortcode limits.

Repository move proves ten rewrites and four routes. Its candidate retains only the same 10,462 existing duplicate-ID findings. It has no new missing reference or required incomplete finding. Starter’s zero-link bilingual move is validated. All four moves remain unapplied. No consumer plans were saved. No consumer source writes occurred. Failed candidates have validated: false. All JSON stdout is pure. Primary/copied inputs, full modes, directory inventories and logical Git/index state are unchanged. These comparisons include ignored copied inputs. The Git metadata inventory excludes immutable object storage. The runtime and broader CLI inventories still match the captured identities.

The first ten-file guarded canonical promotion was qualified in 62.37 seconds with the corrected frozen binary and runtime hashes above. The separate rendered receipt is /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r5-docs-render-ks2tw82c/summary.json, SHA-256 06ae844a4b3f1c01bb5faa8a21091d5461c28aab592d12c4310fb34bc176c5d4.

Canonical documentation gate Executed result
Source owners Translation 0: 137/137 pairs, 1,109 headings; style 0: 137 Chinese files, 181 strong spans, no emphasis; scoped whitespace and public JSON schema equality passed
Frozen CLI Production check links returned 0 using the exact corrected binary
Fresh ordinary production Hugo Build 0; Markdown 0: 214 pages/42,571 nodes; links 0: 345 pages/48,376 links/4,203 fragments
Production translation owner 1 only for the pre-existing draft release-1.2 omission from ordinary production output; no new R5 discrepancy
Separate ordinary analysis Hugo Fresh nonpublishable -DFE build 0, without the CLI probe; Markdown 0: 216 pages/42,877 nodes; links 0: 347 pages/48,752 links/4,231 fragments; translations 0: 137 pairs/1,109 headings
Input preservation All per-command and overall guards passed: 421 primary files, 427 copied inputs, 109 directories and 36 mutable Git files retained bytes/full modes/logical Git state; both isolated source copies remained unchanged

The permanent first-promotion applied-files.json in /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r5-doc-drafts-t3_klnck retains the ten authorized files and their original modes. Core owning logs /tmp/oink-r5-frozen-core-hugo.log, /tmp/oink-r5-owning-race.log and /tmp/oink-r5-owning-vet.log passed. A13 impact, A14 move safety, and A15 bounded context passed their required supported CLI scope.

8.12 - CLI maintenance acceptance on 2026-10-03: R6–R8 and A18

R6–R8 and A18 workspace, Studio, editing and runtime evidence from the dated CLI maintenance record.

These R6–R8 and A18 sections of the dated record were moved here unchanged on 2026-11-06 so each page stays small enough to read whole. The scope, evidence rules, case ledger and delivery state remain on the main page.

R6 workspace and adapter acceptance evidence

R6 supported scope is accepted locally after frozen owning/runtime, exact-binary consumer parity/preservation and guarded canonical source/render gates. The supported registry/tool fields are documented in the contract and command reference.

The registry has an independent version, oink.workspace/v1. It requires strict one-document regular YAML, 1–64 entries, and at most 256 KiB. It requires exact ASCII names, literal relative/absolute directories, and proven canonical identities. It refuses overlap. Missing-site results stay per-site incomplete while later selected sites run. Selection preserves registry order. There is no default named site, sibling discovery, Hugo settings duplication or automatic multi-site apply. Optional tools extend oink.policy/v1, with pinned protocol versions, configuration/full-mode provenance and typed omissions/coverage.

Workspace owning receipts

Focused gate Executed local evidence
Registry core Strict fields/document/bounds/names/literal paths, existing aliases/case-inode ancestry, duplicate/overlap refusal, missing-directory listing and exact subset order; go test -race ./internal/workspace -count=1 passed in 1.414 seconds, /tmp/oink-r6-workspace-core-race.log
Public actual Hugo OINK_TEST_HUGO=1 go test ./internal/app -run '^TestPublicR6Workspace' -count=1 -v passed in 10.498 seconds, /tmp/oink-r6-workspace-public-hugo.log
Public race The same workspace public suite with -race passed in 12.426 seconds, /tmp/oink-r6-workspace-public-race.log; excluded commands specifically reject registry selection
Vet go vet ./internal/workspace ./internal/app completed with exit 0, /tmp/oink-r6-workspace-vet.log
Public outcomes Actual bilingual committed fixture sites retain direct diagnostics/coverage/exit parity for links and full checks. A missing first site yields 2 while later clean/finding sites yield 0/1; explicit subsets preserve registry order, invalid unregistered siblings remain untouched and human output retains findings
Selected application Saved translation-review preview is validated but unapplied; a different registered name is refused before writes and preserves plan/source bytes/full modes/Git. Explicit matching-name apply writes only its planned review file; other registered and unregistered sites remain unchanged

The inspected core workspace.go SHA-256 is cf2cbc9509e8c83eedf6d8833c9eb0ea6492de9a85c959798112fa3f105213f4; its owning test is 9070a8e2c3e58680f6567f2394160ec682bf0457c068c2addf354921e7612d6b; the public test is 3e57a6417ae2e7604f7cb06933759bb06a2f40758ff7059848593cedbaa6570a. All three inspected files retain mode 0600.

Corrected protocols and stage gates

Protocol or gate Recorded status
Actual markdownlint-cli 0.49.1 and Vale 3.24.0 Corrected public trial passed: exactly one finding mapped to the original UTF-8/BOM/CRLF line; excluded front matter/shortcode/math/raw HTML/enabled attributes/code produced no false original attribution
Actual lychee 0.24.2 Corrected trial actually reached the local HTTP fixture: 200 → 0, 404 → 1, 401/403/429/503/timeout → required 2. Optional offline → 0, required offline → 2, both with zero HTTP requests
Final focused actual-tool receipt /tmp/oink-r6-public-actual-tools-final.log passed in 15.192 seconds; the earlier corrected 14.686-second run is retained as prior evidence. Node preload and discovered JS configuration did not execute; source full modes/Git were preserved
Fake/protocol failure receipt /tmp/oink-r6-public-fake-tools-final.log passed in 13.089 seconds: malformed output, version mismatch, timeout, unsafe configs, required missing/optional/group omissions and raw stderr normalization
Focused public race/vet /tmp/oink-r6-public-tools-race.log passed in 30.273 seconds across fake and actual cases; /tmp/oink-r6-public-tools-vet.log completed with exit 0
Frozen runtime inputs Parent freeze at 2026-10-03T10:58:01.807947Z, /tmp/oink-r6-runtime-freeze.json: 103 runtime inputs bind b85affd96378b45bfc56a996b0c5672d02ee4c6cc9bc95335fa5072f6c42a03b; 179 broader CLI inputs bind fbb8176ebc58f1aa26336f4e6036cf9bd5f7a0d62b142f16532b50a8071e9fbe. The exercised 0.3.0-r6-local binary SHA-256 is aa8b347fbe01071f9da729f4d98aa2f50d7264456be6c5f05771bcfadadc371f
Frozen owning suites Full Go/vet completed with exit 0, /tmp/oink-r6-frozen-go-gate.log; full actual Hugo plus pinned tools completed with exit 0, /tmp/oink-r6-frozen-hugo-gate.log (app 382.832 seconds). Workspace/core/protocol/source-mask/policy/report race and vet receipts passed and are copied into the final receipt
Four consumer sites Qualified: exact-binary direct/aggregate diagnostics, coverage, exit, identity and registry-order parity for all four sites; per-command/overall source byte/full-mode/type/logical and mutable Git/ignored-input/directory guards passed. Aggregate completed 4, finding 1, incomplete 0, exit 1
Canonical EN/ZH Passed: guarded first ten-file promotion, source owners and fresh ordinary production/nonpublishable rendered evidence; only the known production draft-release omission remains
Stage decision Supported R6/A07/A15 scope accepted locally after the required receipts

The durable focused-tool receipt is /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r6-tools-6bf67ltv/r6-public-tools-acceptance.json, SHA-256 16b6e47fc0618c76d2f9e3680a4112b6e47b478af8aabd3f2fc84821f840cc8a. It binds the provision record, executable/configuration evidence and 1,422 resolved Node package files. Markdownlint reports original content/tools.md line 7, bytes[80:92] (ppears here.); Vale reports the same line, bytes[71:78] (BADTERM). Each of the seven network cases actually makes one HTTP request.

The exact-binary consumer receipt is /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r6-corpus-59_asiyr/final-receipt.json, 42,212 bytes, SHA-256 0ad86afaf235bdcff0c474e76b08e0591591a7b22c7992b02e20fb17975d029e; the completed summary binds 467b66eb6d178829508115050d4243909313acf1b4d59317ecda37ab7383ca55. It retains 14 copied owning/completion gate logs. The six original operations sum to 314.912887 seconds, excluding candidate compilation and receipt-only correction. workspace list returns 0; four direct full checks return 0/0/0/1; the aggregate returns 1 with all four sites completed.

Site Preserved source files Direct/aggregate child exit Diagnostics/coverage Recorded finding boundary
Starter 97 0/0 28/29 Translation review information only
Documentation 421 0/0 144/34 Translation review information only
PIG 858 0/0 120/41 Translation review information only
Repository 2,294 1/1 11,250/29 Existing 10,462 duplicate-ID findings and 788 translation review information items

Direct and aggregate child identities, order, every diagnostic and coverage record match. After every operation and overall, all four consumer sources retain full modes/types, logical and mutable Git metadata, ignored copied inputs and directory inventories. The complete root CLI inventory still equals its frozen capture. The 478,603,149-byte direct repository JSON and 635,470,795-byte aggregate JSON were validated streamingly rather than truncated. Separate pinned-tool fixtures qualify optional-tool protocols. The consumer registry is task-local and writes no consumer policy.

The initial acceptance driver overwrote a summarized result’s command string with invocation argv, producing a false parity exception after all six CLI operations and their per-operation guards had completed. The failed driver and summary remain preserved as pre-correction.r6_qualify.py and pre-correction.summary.json. Receipt completion corrected only invocation metadata. It verified unchanged raw-result SHA-256 values and header commands. It retained all original full-stream diagnostic/coverage digests and rechecked overall consumer/root guards. No CLI runtime correction or Hugo/CLI rerun was needed. The receipt-only completion took 2.002 seconds and exited 0 in /tmp/oink-r6-corpus-receipt-completion.log.

The executed driver SHA-256 is 4d2a360c6f7f6f96c38698bd189bc4d4b2cb02a7509858920d752897fdd85988; the corrected driver is 4870f5c0374fcc11ad1a6b2e3aefe36f493b6f9f4666c293993dc6a59df8a11b; the receipt-completion driver is cd50d3fe704370f73fa4e7d94ce8e4bc925d11ec8ef04d463aacec37c2053daf. The streaming helper binds 144f778cdb7907372797b47b97f817f340e70423701a2a958dee589281a9a11c, and the inventory helper binds d3ac41dc2e18295bfb26134d1a696935c8174913e2801a5766dbf7a1139d89f8. This receipt qualifies local darwin/arm64 with Go 1.27.1, Hugo Extended 0.166.0, Node 26.9.0 and Apple Git 2.54.0.

The initial actual-tool trial exposed Darwin /var versus /private/var staging identity, actual loopback proxy routing, and an invalid inline-block-attribute/line assertion in the Vale fixture. Staging is now canonical. The Vale fixture uses a real standalone block attribute. The source-mask boundary is unchanged. The qualified child environment forwards literal NO_PROXY/no_proxy host-list data while omitting proxy URLs/credentials and Node preload settings.

Supported source diagnostics require proven original ranges. Rendered lychee locations remain output file/DOM pointers without inferring a Markdown line. Offline lychee is not invoked. Authentication/rate-limit/server/transport uncertainty cannot become required success through severity, exclusions or baseline acknowledgement.

The first guarded ten-file promotion and its fresh rendered qualification are complete. The receipt is /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r6-docs-render-dcwtcmyl/summary.json, 555,297 bytes, SHA-256 ee153932900dc6f1ec62beef1a75927fc60b857efccfbcc558bf0e2c2b12cc04. The 64.17-second run used the exact qualified aa8b347f…371f binary and unchanged 103-input b85affd9…a03b runtime inventory recorded above.

First-promotion documentation owner Actual result
CLI production links 0; one strict production Hugo renderer, no analysis build
Ordinary production Hugo / Markdown / links 0 / 0 / 0; 214 content pages and 43,376 text nodes; 345 HTML pages, 48,438 internal references and 4,259 fragments
Ordinary production translations 1 only for the existing draft content/blog/release/1.2.0.md absent from production; not a new R6 failure
Independent ordinary nonpublishable Hugo / Markdown / links / translations All 0; 216 content pages and 43,682 text nodes; 347 HTML pages, 48,814 internal references and 4,287 fragments; 137/137 pairs and 1,118 headings
Source owners / schema Translation, style and whitespace all 0; 137/137 pairs, 1,118 headings; 137 Chinese files, 181 strong marks, zero emphasis marks; CLI/documented result schema both bind 7468c2d04cde8a368ce0ba44a1f27125b5fca364b6d4672353519b9545b3bdda
Preservation All 12 owner commands, CLI/schema checks and overall comparison preserve 421 primary files, 427 copied inputs, 109 directories and 36 mutable Git files with full modes/types/bytes and logical Git; both private ordinary source copies and all 103 runtime inputs unchanged

The first-promotion installer receipt, oink-r6-doc-drafts-ymjop499/applied-files.json, binds 13c965592d64056d8365aed1927d2d422fadec8adc54ee7050b22e2ea0ad6270. It retains captured actual original inodes in private temporary storage, preserving later old-open-handle writes. Recovery also preserves later target edits or deletion.

R7 read-only Studio candidate evidence

R7 implements the embedded five-view browser and authenticated loopback API candidate described in the contract. Frozen core/browser, exact-binary four-consumer qualification, and guarded canonical rendered gates passed within the declared scope.

Focused native and browser evidence

Owning boundary Evidence status
Native/public parity Actual shared check reports preserve diagnostic/coverage/exit identity for 0/1/2; explicit selected workspace startup, cleanup/signal and no-source-write proofs are recorded separately by the owning test receipts
HTTP management/source/preview Literal-loopback selection; exact Host/origin/Bearer checks; no arbitrary request paths/writes; captured source/diff bounds and source-mode/output inventory guards; focused core/new browser and current corpus receipts below bind this supported scope
Initial held browser 14 axe checks with zero violations and 14 screenshots; five desktop light views, captured BOM/CRLF source/diff, desktop dark, mobile dark and all five 320-pixel light views plus capture changes. Synthetic actual-Hugo fixture retains 228 native diagnostics and coverage parity; copied suggestions use a private test clipboard, leaving the host clipboard unchanged
Browser preview attack Actual attack script executes in the isolated preview, but parent access, management fetch and popup are blocked; token query refused. Actual draft-only page remains production 404
Snapshot preservation Captured source instructions/HTML stay literal data; the initial capture retains its old bytes before refresh after an explicit task-fixture external edit. Source full modes/Git/directories preserved except that declared fixture edit; changes show the actual modified captured input
Preceding held browser Passed refreshed held UI/backend receipt: all 14 axe checks zero violations and 14 screenshots, including declared/captured theme rows
New partial-preview browser Passed new frozen partial-preview runtime: 14 axe checks with zero violations and 14 screenshots; actual Hugo normal HTML 200 and 67,108,865-byte output 413; native 1/228 diagnostics and coverage retained, required partial coverage visible and Studio/refresh 2

Initial browser receipt: /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-studio-browser-AfwaYi/summary.json, SHA-256 930fbd1ab86806069b963bff2e3e95aaa07e3634400cec65e2b8c7922e2a1707. Its exact binary binds 92e5b962e40fbe828a0b006f3ae76a2bddf4ad7e8b1c5b6967e365b8f1827879. The qualified local versions are Node 26.9.0, Playwright 1.62.1, @axe-core/playwright 4.13.0 and Chromium 151.0.7922.34.

The refreshed held UI/backend browser receipt is /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-studio-browser-vn0ofb/summary.json, SHA-256 520603779f712539865c6e9ef7a9ad3ad21ec1906adfb067ec607cc69d071b7e, with exact binary 73bf90c69dce84849ee20ddfbfe825b9f2dd46f0cd37a228ce1b041a83afa33f. All 14 axe runs and 14 screenshots passed, including declared/captured theme metadata and all five views at 320 pixels.

The initial parallel whole-suite trials in /tmp/oink-r7-frozen-go-gate.log and /tmp/oink-r7-frozen-hugo-gate.log failed due to ten-second CI-test deadlines under parallel package load and a graph test observer refreshing its own Git index. The isolated CI target sets then passed in 12.149 and 2.291 seconds. The controlled Git-observer graph run passed in 1.354 seconds. Only internal/projectgraph/hugo_test.go changed: its read-only observer disables Git optional locks, filesystem monitoring and the untracked cache. The ordinary actual-Hugo graph run passed in 1.562 seconds after that test-only correction. No runtime or embedded UI bytes changed.

The corrected freeze is recorded in /tmp/oink-r7-corrected-runtime-freeze.json: the 113 runtime inputs retain 15a7de85a1ae9e6a73d8ea6570aa4f97bdd0ad5677ad7ca996fdd081ad43f7b5; the 193 broader inputs now bind 67c6d36cf91d175f208f79cdd4d337aab6d2ef71e43453b20394b677678725e8, with only the test-observer file changed from the preceding 85ad60d24c93e899020fbdcd34f8252c578253ce5afaf8652e561a432ecc8067 freeze. Corrected serial Go tests and vet passed in /tmp/oink-r7-corrected-go-gate.log. The corrected serial actual-Hugo/pinned-tool suite also passed in /tmp/oink-r7-corrected-hugo-gate.log, SHA-256 2aed822ff6fc8be04919aa74ca6ada721789232c14c1d77f1d44113bc0d235a7; the application package took 220.782 seconds. The independent post-Go source-preservation audit is /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r7-postgo-audit-qygh7bcc/receipt.json, SHA-256 5ee45fe041536243bc1229054516835c61b27909a4f296ac226b1a138e4bc8dc.

The durable corrected owning-gate receipt is /tmp/oink-r7-corrected-owning-gates.json, SHA-256 c7f94a740e33a7349886b3f3689419719f857f39031375e80ca384a3dac36e67. The prepared documentation renderer requires the completed consumer receipt to prove a private captured-source rebuild byte-identical to the final browser binary. Its source-only independent audit, oink-r7-docdriver-audit-ig_r8ud1/receipt.json, binds SHA-256 858cc48bf602fbdb26fcbda03c78ca485338b1295d64257d32cfb14b24f1ade3 and prepared driver f25d9ac4bf1a7ef43d5526b7b3cbadf84dd64ad8a57fd82d1c82e76fdb2b3435.

The first consumer driver trial, oink-r7-corpus-h1lOFl, stopped with KeyError('preview_base_path') because it indexed a field omitted when the actual preview base path is empty. Its private rebuild was byte-identical to the final browser binary 73bf90c69dce84849ee20ddfbfe825b9f2dd46f0cd37a228ce1b041a83afa33f, and all four consumer source inventories and the root inventory were preserved. The fresh oink-r7-corpus-corrected-cByXTa driver changes only those two accesses to get(..., ''), with SHA-256 4c409acacbb9b82e658e6705eddefd9a3541def5c63c340b65678a6c9a8354e4. That fresh run subsequently failed when the repository produced an inventoried file larger than 64 MiB: the preceding runtime refused all production preview. Its native check retained outcome 1, while required unavailable preview made Studio outcome 2. Starter, docs and PIG completed that run with outcome 0. All four source inventories and the root inventory were preserved.

A narrow runtime/test correction for partial preview keeps the 64 MiB limit, exposes guarded production files within the limit, returns 413 for the exact skipped oversized paths and keeps required studio.preview coverage incomplete. Native check outcome remains unchanged. Studio still returns 2 for required incomplete preview. The embedded UI is held unchanged. The bounded coverage detail records actual omitted relative paths, sizes and count. A prepared real-Hugo browser fixture adds static/oversized.bin at 64 MiB plus one byte to exercise an available guarded HTML preview, an exact skipped-file 413, native outcome 1 and required partial-view outcome 2.

The new partial-preview freeze is /tmp/oink-r7-partial-preview-runtime-freeze.json, SHA-256 c426ce3e641ed7b39bb711a26006306cab22e761c5062f2164f10deb4bea8765. Its 113 runtime inputs bind 4900ae05abbdf4409b0be54f276fb4135269cf0a49e9071013ccf42544d35c84; 193 broader inputs bind 8b172cef2b228e2642f0139d6cc569136e86843f818e52e412fa4a2d56add25d. Only internal/studio/preview.go changed among runtime inputs. The broader changes also include its test and scripts/test-studio.mjs. All three UI files retain their exact bytes and modes. Focused core final race passed in 1.748 seconds, with vet and scoped whitespace checks also passing. Its receipt, oink-r7-partial-preview-owning-a56dunn4/receipt.json, binds SHA-256 7b6ecb491f283d04fe54347e564dba426b1a84d152040a1d945af54bc67756ac. In the initial sparse-fixture mode trial, host umask 0077 made a requested 0640 file actually 0600; explicit fixture chmod to 0640 corrected the setup. Focused proof covers normal 200, oversized GET/HEAD 413, changed identity 409, private path 404 and refusal for other unknown output errors.

Whole serial Go tests for the new partial-preview freeze then passed in 61.481 seconds, and vet passed in 0.571 seconds. Completed logs are /tmp/oink-r7-partial-preview-go-gate.log, SHA-256 be7d6eccf99a6f4c1b8f09d1fb782455c7cbd3bad4a2f37e2f0e9da916bcb313, and /tmp/oink-r7-partial-preview-vet-gate.log, the empty SHA-256 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. The independent held-input audit oink-r7-partial-held-audit-o6p98i1l/receipt.json, SHA-256 e567efc5f580db9395afab8ad36c4db842c3db95db442eb1cb1c740dbd43ec31, verified all 113/193 inputs and physical/logical identities during that parent Go/vet run. The new whole actual-Hugo/pinned-tool invocation subsequently completed with exit 1 after 285.649 seconds. Its sole failure was the parent’s unavailable Markdownlint preparation path /md/node_modules. All other actual cases passed. The log is /tmp/oink-r7-partial-preview-hugo-gate.log, SHA-256 1ab6b8cfd399d484e08a1d1f05d25475754caa731991dd1eec1cca03cf6ce970. The sole owning case was rerun with the exact provisioned /markdownlint/node_modules executable. Source/runtime did not change. The case passed: application package 2.317 seconds, wall 3.265 seconds. Its receipt is /tmp/oink-r7-partial-preview-corrected-tools-gate.json, SHA-256 62b75e563e8074995ed9dd354434e653b2f5f2c6d20767226286d0c08d4c667c; log SHA-256 is e9bddac210654d219d9c5d6ebabaa3b91a0f5f4de4daf228b3ae21aeaac7673a. The executable comes from provision receipt 268e601e81bc03a263296d57257b85635371bda642d0632532a7d9318c981461. The independent case-matrix/held-source audit verifies cumulative executed actual-owning-case coverage 0 from the whole invocation plus that corrected case. Its receipt, oink-r7-partial-case-matrix-audit-16_bl9hr/receipt.json, binds SHA-256 0a9e4a1a1e1a08f597becb2f27e743c9f23df672c713c2757241704edb16b51e. All 113/193 physical/logical inputs remain frozen. Optional TestArtifactCorpus and TestPublishedRuleSourceProvenance cases were explicitly skipped.

The new post-Go input audit, oink-r7-partial-postgo-audit-g1hcqdtl/receipt.json, SHA-256 b369737ec48456f673c850ea702cb3cb7efffb8ecc129d87e00dc03af82b2e3b, then confirmed the complete held 113/193 physical/logical inputs after Go/vet.

The new partial-preview browser passed against exact binary f39d6754f7ad13599e4e849394e0f470b2c6f26edf96ce40f199d27b65a8030e, version 0.4.0-r7-local, 16,000,578 bytes and mode 0700. Its summary is /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-studio-browser-cE9be3/summary.json, SHA-256 9099e6c407fd0f9de3c29ce80e03f034a4223d7d7a7c1f1378052e8b9084e0ae; provenance SHA-256 is 85b9f537fb09eecbb09d133b53a297c78184c11200ab0938734c0d10f3449095. The private oink-r7-browser-partial-ZZIqzZ/source-binding.build.json, SHA-256 7a89ab8318c3a38455ab6ce12bcdbc53ae5ce0674fb5aaaa1df0fcf68a093399, binds all 113 runtime and 193 broader source inputs plus physical identities before capture/build/after to the new freeze; root inputs stayed unchanged. All 14 axe checks had zero violations and all 14 screenshots passed, retaining the keyboard/mobile/light-dark/source/clipboard/security checks described above. Actual Hugo emitted oversized.bin at 67,108,865 bytes. A request through its rendered /sub/oversized.bin link returned 413. Ordinary actual HTML returned 200. Required partial preview coverage stayed visible. The CLI/API/UI matched 228 typed native diagnostics and native coverage/outcome 1. Studio and the subsequent refresh returned 2. Source preservation still excludes only the declared task-fixture external edit.

Another prepared corpus driver had assumed that an available normal preview always appends a studio.preview coverage row. Actual normal Starter/docs/PIG Overviews do not emit that row, so the driver assumption was corrected without changing native coverage. The repaired fresh oink-r7-corpus-partial-pZLwY0 driver, SHA-256 47778df62505beeb7432985be927f1b001e03824e9dee3a6dbed9d9b2dbe049c, was reviewed against those three retained actual Overviews and the current partial browser capture. Normal availability still requires its actual preview URL and independent HTML 200. A partial capture retains its actual required row, omitted count/identities and 413. The preparation audit is oink-r7-partial-driver-correction-audit-sa98cm6k/receipt.json, SHA-256 a519a5bc6ae83438146ff4710d53f5edb0e656a05d0532c02123e5771416f07e.

The fresh four-consumer qualification completed with driver outcome 0 in 234.6425 seconds. Its current summary is /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r7-corpus-partial-pZLwY0/summary.json, SHA-256 d7b5a4f1607b6f75ae6a596c19cbab28685fb67dac750096173060ed097c8bf5; log /tmp/oink-r7-partial-corpus-gate.log binds SHA-256 a7b724500569bd594d8e01502ec1956eb089cc9153b04b693992a9322013c811. The durable current corpus qualification.receipt.json binds SHA-256 4e5df7c3fda9f0b763091af3e6cb85c68c736c319a1de68030b81d5cd5b384bc; primary source inventories contain 97/421/858/2,294 files respectively. The private captured-source rebuild is byte-identical to the new browser binary f39d6754f7ad13599e4e849394e0f470b2c6f26edf96ce40f199d27b65a8030e. Runtime 113/broader 193 inputs and root physical identities stayed frozen. Every operation and the overall boundary preserve all four consumer bytes, full modes/types, logical/mutable Git, ignored copied inputs and directories.

Consumer Native outcome Typed diagnostics Studio outcome Actual captured pages
Starter 0 28 review-info records 0 66
docs 0 144 review-info records 0 343
PIG 0 120 review-info records 0 248
repo 1 10,462 existing duplicate-ID findings plus 788 review-info records 2 1,576

Nested native headers, typed diagnostics, coverage and exit match direct CLI checks exactly for all four sites. All issues were paginated. Other views used bounded samples. Captured physical source and translation diff were available on all four. The first three actual production previews returned HTML 200 and emit no studio.preview omission row. The repository normal HTML returned 200 with 60,100 bytes. Its current capture exposes four oversized print paths, where each actual HEAD returned 413 with zero response-body bytes:

Captured omitted relative path Captured byte size
_print/pkg/index.html 73,976,221
_print/pkg/pgsql/index.html 69,903,999
zh/_print/pkg/index.html 73,086,240
zh/_print/pkg/pgsql/index.html 69,052,754

Required studio.preview remains incomplete, so repository Studio 2 retains native 1. Actual analysis-only draft routes returned production 404 in docs and repo (Starter/PIG had no unique captured draft route). Workspace subset/full/healthy-subset sessions selected only registered sites and closed listeners without captures. Unknown or selected missing sites returned 2 before startup. Independent final corpus audit oink-r7-final-corpus-audit-xr3_u5dt/receipt.json, SHA-256 b8a8eedf5c899fe5830bdde959783c46b3f191ab144c0d3798077555d55238fc, verifies raw typed native/API/shutdown parity, all 132 operation preservation comparisons and four overall guards.

For temporary disk capacity, the parent retired three private Go build caches totaling 366,184,826 bytes, as recorded in /tmp/oink-r7-private-cache-retirement.json.

Remaining stage gates and promotion boundary

Required gate Current status
Frozen runtime input/binary identity New partial-preview freeze binds 113 runtime inputs 4900ae05abbdf4409b0be54f276fb4135269cf0a49e9071013ccf42544d35c84 and 193 broader inputs 8b172cef2b228e2642f0139d6cc569136e86843f818e52e412fa4a2d56add25d; all UI bytes/modes unchanged. Source-bound browser binary f39d6754f7ad13599e4e849394e0f470b2c6f26edf96ce40f199d27b65a8030e passed; fresh private consumer rebuild is byte-identical
Full Go/vet and actual Hugo New whole serial Go/vet and browser passed. New actual-Hugo/pinned-tool whole invocation remains exit 1 for a preparation path; sole corrected owning case passed 0, yielding independently verified cumulative executed actual-case coverage 0; two optional cases explicitly skipped
Four consumers Completed exact-binary CLI/API qualification; native 0/0/0/1, Studio 0/0/0/2, exact nested native parity and source byte/full-mode/type/Git/ignored-input/directory guards; repository partial preview remains required incomplete
Canonical paired sources/render First guarded TEN promotion and scoped actual render passed
Stage decision R7/A16 supported local scope accepted

The documentation installer retains the actual captured old inode outside canonical source storage on both success and recovery, without unlinking its last name after an earlier target identity check.

The completed first-promotion rendered gate is /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r7-docs-render-n8tw2tbw/summary.json. Its SHA-256 is 35e79f51d39803b3e4cdf134ed277957dd627acba42e0e0dc785e4745ec3c481. The log SHA-256 is de3a07eac661c15805070e0ed2e364a71ebbd38e15d8907aab3bdf716e95131d. The run took 63.33 seconds. Exact qualified binary f39d6754f7ad13599e4e849394e0f470b2c6f26edf96ce40f199d27b65a8030e passed production CLI links with one strict Hugo build. Ordinary production Hugo without a probe passed rendered Markdown (214 pages/44,075 text nodes) and links (345 pages/48,482 internal links/4,303 fragments). Its translation owner retained exit 1 only for the existing nonpublished release 1.2.0 draft. Independent draft/future/expired analysis passed Markdown (216 pages/44,381 nodes), links (347 pages/48,858 internal links/4,331 fragments) and translations (137 pairs/1,129 headings). Source translation/style/whitespace checks passed and CLI/docs schema 7468c2d04cde8a368ce0ba44a1f27125b5fca364b6d4672353519b9545b3bdda remained identical. All twelve operations, schema and overall guards preserved 421 primary files, 427 copied inputs, 109 directories, 36 mutable Git files and 113 runtime inputs.

The first guarded promotion receipt is oink-r7-root-promotion-p9g1u7pz/summary.json, SHA-256 323a5ce267e39aaf8f97dc4a12cccbdde83730155a199efb5f3815e29b334e4a, verifying that actual original inodes are retained outside canonical source.

R8 accepted reviewed editing evidence

R8/A17 supported editing scope is accepted locally after the corrected frozen owning/browser/corpus and guarded canonical rendered gates recorded below. CLI edit text, field, snippet and attachment preview the same bound oink.edit/v1 intent. Explicit studio --edit uses this intent. Saved-plan apply or explicit acknowledged Editor Apply owns selected source writes. The default Studio session remains read-only.

Candidate scope and preservation

Known site-owned UTF-8 Markdown is bounded to 1 MiB. Full text and supported ordinary top-level YAML scalar forms retain the declared BOM/line-ending and source-span preservation boundaries. Unsupported form shapes remain text. Exact value_json numeric tokens avoid browser Number rounding. Scalar forms limit numeric literals to 4,096 bytes and absolute decimal exponent 10,000. Larger/nonfinite constructs remain manual text. Field JSON is at most 1 MiB. Escaped lone surrogates are refused. Valid Unicode pairs are supported. Catalog components use original UTF-8 body byte offsets. Attachments require actual leaf-bundle identity, at most 4 MiB and an exclusive new clean basename. Source hashes, full modes, all site/external inputs, regenerated intent and fresh actual Hugo validation bind the same shared guarded application path.

The Editor displays the complete UTF-8 review, selected-file base/after identity and native candidate result. The review is capped at 2 MiB. Its literal bytes are hash-checked before acknowledgement. The actual selected candidate HTML is draft/future/expired analysis, visibly nonpublishable and separate from the original production preview. Required candidate-view incompletion may raise the proposal/session to 2 without changing native findings. For page-file edits, the selected candidate source hash/full mode matches its reviewed After state. Attachment/no-op proposals retain the selected page’s reviewed Base state. Stale/replayed plans, attachment collisions and untrusted preview requests are refused. Applied-with-refresh-error remains explicitly applied.

Focused preparation receipts

Candidate evidence Current observation and boundary
Pure editing core Owner’s focused exact-numeric tests passed for 18446744073709551615 and 7.12345678901234567890123456789, exact no-op raw bytes and changed final decimal digit; broader frozen receipt pending
Actual DFE output ownership Live ordinary output is copied through a confined os.Root, exclusive target files and guarded streaming reads; files over 64 MiB can be captured while serving limits remain unchanged
Copy cancellation/race Context-aware helper focused 0 in 0.703 s, race 0 in 1.856 s, vet/whitespace 0; actual first-chunk cancellation retains partial output, source bytes/modes/identity unchanged; source FIFO replacement cannot block before descriptor proof
Helper log identities Focused c227a88210ab0dc46b24eaff50a347d5c494e9ce23f5bdef5d5b822efab4976f; race 13f0616d55fd4df791ecded0712a18096392c88cb9b849383414c305e50b6779; vet is empty SHA-256 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Read-only candidate integration review Selected actual HTML URI/base prefix and inventory, retained private DFE lifetime, source SHA/full-mode equality, native versus view coverage and cancellation reviewed; no new material defect found within this code review scope
First Editor browser trial Harness stopped on ambiguous global Open editor selector; retained as failed trial
Corrected-selector Editor trial Desktop field/component/binary apply checks and axe checks passed before 320 px draft-review horizontal overflow failed; retained original trial
Narrow layout correction Editor review hashes/receipt text wrap and intrinsic widths are bounded; prior CSS and failure evidence retained separately. Development rerun passed 12 axe checks/screenshots, including real 320 px dark review and light receipts/refusals; final frozen-source/binary rerun pending

The preceding preparation rows were captured before the first complete R8 freeze. The first whole frozen gates later passed for binary 84b804d3246a5be581e44884ed910fa3f45d8be29734b8babdeeb763a11fa882 (0.5.0-r8-local), runtime 123/58517b8e98b80df6642be4ee6275a0074ec187768b20e009f41da2607b635d46 and broader 212/d81335c78413acc60e27adee0ac794862285e41cb2a3a7687ec820c1065ba003. The whole-gate summary is b49f4a3272af3e3dcc92e7e9b38d4289bb49cb19aa3e9354ea148d2d8cb2cea8: Go tests 0/56.523 s, vet 0/0.904 s, whole actual Hugo plus all three pinned tools 0/320.044 s, core race 0/16.610 s and public R8/helper race 0/48.319 s. Its source guards passed.

The first frozen browser receipt eb6977235ef9ae6cec28651b5654eb101685af67abe0cbed0acb0f8375458d9c binds that same binary and source freeze. Editor had 12 axe runs with zero violations and 12 screenshots. Retained read-only Studio had 14/zero/14. The actual form preserved the literal 1e400, its planned after hash and diff. It then discarded the proposal. Exponent ±10,001 and a 4,097-byte numeric literal were refused locally without an API request. Four acknowledged field/component/binary/draft applications occurred only in disposable fixtures. Default read-only refusal, stale preservation, no-op source bytes, preview isolation and native-result independence passed.

The first exact-binary consumer trial then stopped at Starter after 37.533 s. Its immutable failed-trial receipt is 853a8397ba4c527c03aa3cc9ac7cacc41c0ab0379549d145b874f1d1ecc3901c. Two failures are recorded separately. A driver event hash depended on JSON object-key order. Recursive comparison nevertheless proved API/CLI arrays equal: 28 diagnostics, 29 coverage rows and native exits 0/0. Separately, repeated resolved cache capture produced a genuine duplicate module input, .gitattributes. Required candidate graph capture became incomplete. Mutation outcome was 2, and native check remained 0. There was no actual selected DFE HTML or applicable lease. The public published-cache fixture reproduced that defect; its retained failing log is 50ab704e715665096e0f36391bb1364841c3a2b2ac88dd262915ce53fb66afa6. All 48 recorded per-operation source proofs and four overall consumer guards preserved bytes, full modes, types, Git, ignored copied inputs and directories; root inputs stayed exact. No Apply or saved plan was performed.

The narrow runtime correction gathers complete resolved-module rows before committing additions. Identical repeated or reordered captures retain the original inventory. Changed hashes/full modes and added or removed paths within an existing scope are refused. Missing scopes, conflicting identities and capture errors are also refused. Refusal does not refresh prior evidence or append partial additions. Non-module rows remain exact. Site owning receipt e7b284b9dece1c5f2b696cd76166d2286fcbec69e6c48912ab9a78204bdb980b records focused 0/0.746 s, site 0/2.123 s, focused race 0/1.958 s and vet 0/0.167 s.

The corrected published-cache receipt 6358dc81f06e34b789cb47a0f4442d6d036d2e33423a06f5dbe85b3064766da6 records actual github.com/pgsty/[email protected] from a task-local copied checksummed archive, with no downloads or replacement. Original and candidate graphs each have 1,256 unique inputs, including 1,198 module inputs. Full API/CLI typed diagnostics, coverage, exits and plan identity match. Actual selected DFE HTML returns 200. Source bytes/full modes/Git are unchanged. No Apply or saved plan occurred. Owning race passed in 30.255 s; vet passed. Its corrected race log is c7d21a30b8af141d9d9604a80ddf9cf3f608320b97a441a06a742376e2119551.

The current complete corrected freeze is fb276500a3d2643bd0aa220f8bebb380fce2c98493d62b0502b6497b2f02949f, runtime 123/cdf629eeb4bbef6d4d88ee27fe3fb0a73b07b6bf6438336e033a18fb7feb1c17 and broader 212/f6e305e792733a550814eb841615d12fa14a9a6bb2a97c4ada85f7275183e579. Only source_inputs.go, its owning test and the public published-cache test differ from the first freeze. Held UI/helper bytes and all full modes remain unchanged. The rebuilt candidate is bd25f9e0b35ec10e227aabf9582ae40b0b367390f64b93668de6ae85222c3d71 (0.5.0-r8-local). Its observed corrected source-bound browser receipt 33a698985a55c14c3e64e981da1f8e74c686497083dc0edb241406f185e3eeb8 again reports Editor 12/zero/12 and read-only 14/zero/14 with complete 123/212 pre/post source preservation.

At the next evidence observation, the corrected whole gates completed for that held bd25f9e0…22c3d71 binary and fb276500…02949f freeze. Summary 208f156c0954e803eccbada678a4689683dc1576c543c379e5cc04b3497ef772 records Go tests 0/57.826 s, vet 0/0.521 s, whole actual Hugo plus all three pinned tools 0/378.847 s, core/site/Studio race 0/17.937 s and public R8/attachment/output-helper race 0/85.159 s. Every gate’s source pre/post guard passed. The actual-Hugo log has 434 top-level passes and zero failures. The two optional external fixtures TestArtifactCorpus and TestPublishedRuleSourceProvenance remained explicitly skipped.

The corrected whole actual-Hugo log is 4eb1a2afdce2adbe570b10922fd53b6d8954f7c95747370c3c661e94d2f71a05; Go log ea59463e9649ffe2f8aff9da66c91cf6895c86fde96a524db23c89cd4eb35925, core race cdd3d761b5ca7b5e986b25aee3129d65663e3e5ebb83eecb6fbb080387298a58 and public race bb610bdcd7a299cb9b66f4c69e30e246c20546efae47653c01d350b1026ea2de.

The 434 passes and two optional skips above are top-level counts. The same whole invocation also skipped the nested Unix-socket refusal fixture because the Darwin temporary pathname exceeded the socket limit. A first shorter private-path trial still skipped. Receipt 93106854ca890b497d3c74522b895f597ac60cec55ced42cad7b187d334da200 retains process exit 0 and records no actual socket execution.

A subsequent nonresolved short private TMPDIR executed the same frozen socket fixture under race detection without a skip: 0/2.954 s. Receipt 531a503b3b91e1b423c2be61b92ed806d3a813738c38d57e5ec122577b4337f9 and log 236c84f1842ffce76174c834f3888718a109cec6377ada6f3242b02f551f00b3 bind fb276500…02949f and all 123/212 logical/physical/Git inputs unchanged before/after.

The corrected four-consumer trial subsequently completed in 845.705 s. Summary af4fc53326163c4a03aa2982c1f01363fbbdd5a447c9baed3639bd8599d46370 and qualification receipt 4d6fd02543c1920497e1a1bb0a68fcf89b0546130fd9cc12c1df391b7e673e75 bind a byte-identical private rebuild of bd25f9e0…22c3d71, the complete held 123/cdf629ee…feb1c17 runtime and 212/f6e305e7…5183e579 inputs. All 2,383 entries of the first failed trial retained their exact bytes/full modes/types.

Corrected consumer Native/current and native candidate exit API candidate outcome Full diagnostics/coverage Actual selected analysis HTML
Starter 0 / 0 0 28 / 29 200, 48,149 bytes, /blog/design/content-model/
Documentation 0 / 0 0 144 / 34 200, 61,738 bytes, /blog/oink/immersive-reading/
PIG 0 / 0 0 120 / 41 200, 55,641 bytes, /404/
Repository 1 / 1 2 11,250 / 29 200, 92,352 bytes, /blog/infra/2020-12/

These are actual selected Hugo HTML routes in the separate, visibly nonpublishable draft/future/expired candidate view. Each expected candidate marker was present. API and CLI matched full typed diagnostics/coverage, native exits, and plan ID. They also matched Base/After hashes and full modes, unified diff, and the selected page’s proposed source. The complete literal API review and its hash were independently validated. No consumer Apply or saved plan occurred, and no listeners remained. The repository retained 10,462 existing duplicate-ID findings and 788 information records. Its four actual PRINT outputs remained required partial-preview incompletion: _print/pkg/index.html 73,976,221 bytes, _print/pkg/pgsql/index.html 69,903,999 bytes, zh/_print/pkg/index.html 73,086,240 bytes and zh/_print/pkg/pgsql/index.html 69,052,754 bytes. Each bounded HEAD request returned 413 with zero body. Selected in-limit HTML remained 200. Native 1 remained unchanged. Proposal/session 2 and Apply refusal stayed visible. The other three complete previews had no invented explicit complete-coverage row. Actual guarded HTML 200 supplied the evidence.

Exactly 53 protected operations each checked all four sources: 212 per-operation source proofs plus four overall proofs, with source bytes/full modes/types, copied ignored inputs, directories and logical/mutable Git unchanged. Each source proof compared four inventory categories, yielding 864 raw inventory pairs including the overall comparisons. All 53 root guards and the final complete 123/212 logical/physical inputs also matched. All issues and pages were paginated. The other five view endpoints were sampled to their first 50 records. Each site included one known source and one bounded diff. Full native/CLI record parity used the declared bounded complete-record codec. Object order was canonicalized. Array order, types, null and field presence remained significant.

Independent audit receipt 6b72ca06d8392a5271fc40757f176f26e1144c21eec93dbd035e0a1bd645657b verified 69 artifact hashes, complete bounded API/spool/shutdown typed records and the large native/CLI raw-file digest bindings. Its additive receipt 335f137663d4ec0b2a0d3e49c8d70b9918f86078ab6264855171a2644d8aa6c6 also verified the fresh current root’s complete logical Git inventory against the freeze. The original audit stayed immutable.

The reviewed first TEN promotion subsequently passed through the guarded retained-inode installer, root receipt 7cd9b4604d2340b9e46965a26281c921b967060909d518b8b4b31e5f42d0120c. Its actual original source inodes were retained outside the documentation site. Unselected source/copied inputs, directories and Git, and complete CLI 123/212 logical/physical inputs stayed unchanged.

The canonical render then completed in 67.21 s, summary bb0d0710294f810fb14284f7b5b0329befbd290b66c21397b9a45e8382287fb6, qualification receipt 32d3ffeca43bc9ad4615edcca0d3cc47cc932bbc93c6576724c800e0a62405b1. It used the exact qualified bd25f9e0…22c3d71 binary and corrected 123/212 freeze. Actual CLI production links passed 0 with one strict Hugo build. Independent ordinary probe-free production Hugo/Markdown/links passed: 214 Markdown pages/44,691 nodes and 345 link pages/48,532 internal references/4,351 fragments. Its translation owner retained 1 solely for the existing release/1.2.0 draft absent from production. Separate explicitly nonpublishable draft/future/expired Hugo analysis passed Markdown (216 pages/44,997 nodes), links (347 pages/48,908 references/4,379 fragments) and all translations 0.

Source translations passed 137/137 pairs and 1,143 headings. Chinese style passed 137 files/181 strong spans/zero emphasis. Whitespace passed. Schema SHA-256 7468c2d04cde8a368ce0ba44a1f27125b5fca364b6d4672353519b9545b3bdda matched exactly. All 12 commands, schema and overall guards preserved 421 primary source files, 427 copied inputs, 109 directories and 36 mutable Git files, plus all 123 runtime/212 broader CLI logical/physical inputs. The qualification receipt binds 60 canonical inventory pairs, 15 CLI guard pairs and six private-copy source pairs.

R8/A17 supported local editing scope is accepted after corrected owning, socket, source-bound browser, exact-binary four-consumer preservation and these guarded canonical gates. R1–R8 are accepted locally. Native repository findings and required partial-preview 2/Apply refusal remain visible. The separate platform-authority audit 762571dab9a07651ac8e4c71764bfef292f8d5eba729a089e72d9d755b7e2d7c confirms that the initial contract qualifies actually exercised architectures: macOS arm64, native Linux arm64 and emulated Linux amd64. Darwin amd64 remains an experimental archive with failed actual execution/unverified runtime.

Required gate matrix

Required gate Current status
Final immutable runtime/source freeze and exact CLI binary Corrected complete 123/212 freeze and bd25f9e0…22c3d71 bind completed owning/browser/corpus/canonical scope; first-freeze trials separate
Public CLI/JSON/exit, stale source/config/external-input and guarded writer tests Corrected public R8/attachment/output-helper race, whole Go/vet/actual Hugo and canonical stage gates passed
Frozen whole Go/race/vet and actual Hugo/ordinary Hugo after selected application Corrected whole Go/vet/actual Hugo and core/public race passed; 434 top-level passes, zero failures, two optional external fixture skips explicit; first trials remain separate
Editor browser five-view parity, text/forms/components/binary attachments, exact numeric/no-op, stale rejection and preview isolation Corrected source-bound Editor 12 zero-violation axe runs/12 screenshots and read-only 14/zero/14 passed; bound completed corpus and canonical acceptance
Exact-binary four-consumer read-only qualification Corrected all-four completed in 845.705 s; full typed native/API/CLI candidate parity, 212 per-operation source proofs plus four overall, no Apply/save/source writes; first failed trial preserved
Protected canonical TEN promotion, EN/ZH source/schema/style/whitespace and actual production/analysis render Guarded first promotion and independent exact-binary 67.21 s render passed; only known draft translation omission in production; rendered and status bytes separately bound
R8/A17 stage decision Supported local scope accepted after corrected whole owning/browser/corpus/canonical gates; R1–R8 accepted locally
Final A18/platform/archive delivery Completed in the 2026-10-04 supplement below

Prior R1–R7 sections, whole-invocation failures and scoped acceptance receipts remain unchanged. Temporary qualification files stay outside canonical content and Git.

Current runtime completion supplement on 2026-10-04

This supplement records the current candidate on 2026-10-04 (Asia/Shanghai). The dated page URL and all initial 2026-10-03/R1–R7 records remain unchanged. The three UI files retain the browser-qualified bytes and full modes. Current Go, Hugo, platform, archive and four-consumer checks refresh the changed backend.

The first current ARM offline unit run exposed an output-copy integrity gap. On ext4, adding a directory entry could preserve the parent’s allocation size and observed timestamp. That failed run stopped before later qualification steps. The correction captures and rechecks actual sorted directory membership and entry identity. It also checks regular-file bytes and full modes. Only internal/app/studio_output.go and its owning test changed. The failed receipt and independent audit are retained.

The preceding integrity-correction qualification freeze is 683daca0e522193c7ff1b0de6ac2fee5d2fca080811bf184a8dfd5b90a33f224: 123 runtime inputs hash to d346ad15cd4239004e32e1b9f30d727eaf156be0187dc165ca874032a7cf962a, and 212 complete CLI inputs hash to 2abd1a044d8192b07f9bbc06b55dc8b4544d66ca17b8867971cec702ba3af088. The 0.5.0-r8-local Darwin arm64 candidate is 74ad94e73557f6538cd64edd1766d6df92c596d98411031159d94af072c186ec. The integrity-correction receipts below bind that source scope. The later one-test fixture amendment has a separate complete source identity and completed formal qualification boundary. Both are recorded below.

The current complete source freeze is now 196245a3ba09305e34b86539c8eb79f1473e4373ee47aa1f56f8933b04a42d43. The 123 runtime inputs remain d346ad15cd4239004e32e1b9f30d727eaf156be0187dc165ca874032a7cf962a. The 212 complete CLI inputs are 2c487bfb4c65ed40ff78356b2860de627e6ac1afa0da2df433b09345dab7f5b0. Only the owning published-cache test changed, to source 54c10ef89310256b5f4c165c7de5de9668e1d4d2991b71751076680141dbe779. The fixture amendment is separately guarded. Production bytes and all semantic assertions remain unchanged. Formal qualification of this complete source passed. It includes the current eight owning gates, reproduced archives, and full plain-Go AMD/ARM runs. Root A18 proof 2c018cb2afa3f26699a9e6b5a0971096246b12405fde5a27e43a9e213e46da60 binds all three declared supported targets and five reproduced archives.

Current proof and preserved earlier input boundary Observed result and bound receipt
New complete-source formal qualification Freeze 196245a3ba09305e34b86539c8eb79f1473e4373ee47aa1f56f8933b04a42d43, owning test 54c10ef89310256b5f4c165c7de5de9668e1d4d2991b71751076680141dbe779, unchanged runtime123. Current eight gates, host/archive and both full plain-Go Linux flows passed, bound by root A18 proof 2c018cb2afa3f26699a9e6b5a0971096246b12405fde5a27e43a9e213e46da60
Narrow integrity correction Owning receipt 6966d768025497b45958073d4c53a2a2981065c8a95857834dcf6a4faa4f0201. Independent audit 6cb5d2eabf57b41079026a38a674f46def9f56a15df17ad27e671e4f765798df
Prior-source six frozen owning gates Build, full offline Go unit/vet, whole actual Hugo/pinned tools, core race and public R8/output-helper race all 0. Elapsed 3.501/68.257/3.909/333.801/37.070/79.670 seconds. Summary b40b7787b3da8dc1e0763812b6dde529b4b5b69fe479d79940f1161223124e1d. Independent audit 20780662b7ff35019b2c8c84e6dc763f9351ae0816f6ef7a7789f7a15be99167
Eight current frozen owning gates Selected published-cache actual Hugo and race, build, full offline unit/vet, whole actual Hugo/pinned tools, core race and public R8/output-helper race all 0. Current summary d6272fcc4dfab114aecfcdf19a7e2b78f1e931817331b460f43ff2056bf754a4. Raw whole Hugo has 435 top-level passes, no failures, two optional top-level skips and the explicit long-path socket child skip. Runtime/binary bytes remain identical
Prior-source Darwin arm64 and archives Current extracted candidate runs outside the checkout with no consumer Node requirement. Seventeen commands and eight actual process tests, including child signals, passed without process-test skips. Two fresh release directories contain byte-identical five archives and checksums. Source/license/provenance/canonical tar checks pass. Summary bcb4d7599e965c1b3cfe7fe698ca14061ad53d45e7a194337aeebb8d37aa77c1. Independent audit 60a04771365d8be15ac91fbbd8d485b019aae081598e468018861ca5734e387c
Current Darwin arm64 and deterministic archives Seventeen extracted-archive/ordinary-Hugo/process commands passed expected exits, with missing Hugo explicitly 2. Eight actual signal/process cases ran without skips. Two independent fresh builds reproduced five byte-identical archives from current complete source. Summary 3890fd8468b6bce5271bb32ffa1a18bd5daf99c19c43becac0be8e3b908a5d57. Source, tools, module-cache and smoke-source guards remained equal
Prior-source Linux arm64 Actual nonroot Linux arm64 on ext4 with Go 1.27.1, Hugo Extended 0.166.0 and Git 2.47.3: full offline Go unit/vet, all 13 required pure top-level pass records and the membership case plus its four children without skips, 10 selected actual-Hugo cases without skips, native rebuilt archive identity, installed bilingual/offline/ordinary-Hugo/missing-Hugo 2 JSON and signal/source-mode checks passed. Guest summary 409990bc1425f4bf219f8911a71581af6e68729865580121dbeb6d85a06d2ea7. Outer receipt a022e40f068703cd59ce6d6a7fb6530cce6907681baa26eb1dfc77c09f0c8898. Exported-record audit 24afc50f6f860394d1ebfa7a8b754ddd9cb97f9e88a0dcfcbcb659193ecbfe5f
Current Linux arm64 Current nonroot Linux arm64 ran on ext4, with native ARM through QEMU HVF and Go1.27.1/HugoExtended0.166.0/Git2.47.3. Full offline unit/vet passed with 370 top-level passes. The following cases passed without skips: all13 decisive pure cases and4 membership children, and 10 selected actual-Hugo cases. Exact native/installed current archive identity and bilingual/offline/ordinary-Hugo/signal flows passed. 24 commands reached expected exits, including missingHugo2. Guest 268102f69c0950f9d2994d22cd2fd290fc11e24bd6d6f916fd70a93ca4946c74. Outer f3c066fdc9b97feff92160346185a1af978a5172eed5c81904ac7c0e5fc6c982. Source/SDK/borrowed/old-task guards were equal. The owned VM was reaped. Default optional unit skips retain their named gating reasons
Prior-source Linux amd64 failed trial Preserved current TCG trial failed. Outer receipt 3543664ba5590f2ba5a8f676b196bb636b72bc819913289f415d0a8a841c1bdb, guest summary 16075204d287713c7f7650c0a65dd289dd4bd83db07c9ba4b85b3f21244d5240. Full offline units (370 top-level passes), vet and the first three selected Hugo cases passed. The published-cache candidate request reached the test HTTP client’s 90-second deadline. Candidate parity, the remaining six selected Hugo cases, native rebuilt archive and installed archive smokes were not reached. Deadline review 12917b9eb89e3abc5893e08da3b6b6e20743dcb4c14e6f7ba8561628e3566934
Current Linux amd64 Current nonroot Linux amd64 ran on ext4 under QEMU TCG emulation, with Go1.27.1/HugoExtended0.166.0/Git2.47.3. Full offline unit/vet passed with 370 top-level passes. The following cases passed without skips: all13 decisive pure cases and4 membership children, and 10 selected actual-Hugo cases. Exact native/installed current archive identity and bilingual/offline/ordinary-Hugo/signal flows passed. 49 commands reached expected exits, including missingHugo2. Guest 3a1a32979efc843de8b95b7c13824026e17f71c06d4c458b738c0b9583fb4723. Outer 30cf4950cc83fa0732047d9a0f89bb59e68779ee2e8f5c755724c9679be265e3. Source/SDK/borrowed/old-task guards equal and owned VM reaped. Default optional unit skips retain their named gating reasons
Runtime-equivalent preceding four-consumer candidate corpus Source epoch 683daca0…33f224. Runtime123/binary74ad is byte-identical to current 196245a3…42d43. The corpus was not rerun after the test-only amendment. 853.249 seconds. Native/candidate-native 0/0/0/1, API/view 0/0/0/2. Diagnostics 28/144/120/11250, coverage 29/34/41/29. Summary a1e98ca3e10095a1134381666bacf256f8e8827cd3900c9e811b7120de4c2974, receipt 05c4562a50d9f83ba2c99879ec841870c5e753199e41792bd5bc718cf8046e7b, independent audit 3a1b0b6e3a8c6b1a0d82c5f82b46c84b1e44d6c30bab655610cb9e86e6a30b47
Final canonical lifecycle and rendered checks The promoted TEN bytes use independent canonical rendering and navigation/URL receipts

The preceding six-gate b40b7787b3da8dc1e0763812b6dde529b4b5b69fe479d79940f1161223124e1d, host/archive bcb4d7599e965c1b3cfe7fe698ca14061ad53d45e7a194337aeebb8d37aa77c1, and ARM outer a022e40f068703cd59ce6d6a7fb6530cce6907681baa26eb1dfc77c09f0c8898 / guest 409990bc1425f4bf219f8911a71581af6e68729865580121dbeb6d85a06d2ea7 / audit 24afc50f6f860394d1ebfa7a8b754ddd9cb97f9e88a0dcfcbcb659193ecbfe5f remain retained alongside the new exact-source proof. Historical 26 axe checks/screenshots and 22 codec cases are carried with unchanged UI/codec/runtime inputs.

The initial max-CPU AMD trial remains failed: receipt 3543664ba5590f2ba5a8f676b196bb636b72bc819913289f415d0a8a841c1bdb, guest summary 16075204d287713c7f7650c0a65dd289dd4bd83db07c9ba4b85b3f21244d5240. The test client timed out after 90 seconds while awaiting candidate headers. Candidate parity and the remaining six selected Hugo cases/native rebuild/installed smokes were not reached. Guest inputs stayed exact. The host guard recorded only a .git directory timestamp change. The separate qemu64 one-test preflight also failed at the unchanged 90-second HTTP client deadline: outer receipt fc68173ccdfd8ce263ecdf082a533d9da666a4cc2e1e5e29880ee827286132ac, guest summary e350ff65feeee166ffac1d337db9bbd70d3895b1fb6d93df0a30ca4de09019fc. The named case took 177.71 seconds. The first trial took 176.64 seconds. Its inputs remained exact and its VM was reaped.

A later Go-overlay diagnostic preserved the same production source and every original semantic assertion. Outer receipt 0bc6d563b7cd9ca862717c2123ee0836d83b6b927d00204a0b031049c38e93f0 and raw-bound classification 66a1422cdb79ab9f1cf683f441ade0ce4adb4a7a666d524c4b9ed98ebee28708 record a passed named case in 352.40 seconds. Original capture took 26.254 seconds, Studio capture 26.211, candidate HTTP 94.312, direct preview 94.318 and CLI preview 81.962. Both graphs retained 1,256 unique inputs, including 1,198 module inputs. The original-capture context had expired when the HTTP result arrived. Fresh independent direct/CLI contexts completed normally. All 20,564 host guards and five guest command guard pairs stayed exact. The owned VM was cleanly reaped. The scoped owning-fixture amendment now uses a 300-second budget for that candidate request and fresh direct/CLI operations, about 3.18 times the slowest observed operation. General/original-capture 90-second limits, restoration of the shared client, shutdown 15 seconds and Go’s default ten-minute cap remain unchanged.

The consumer driver compared complete typed diagnostics, coverage, native exit, PlanID, selected Base/After/full modes, unified diff and selected source between API and CLI. It separately verified the complete literal API review and its hash. For attachments and no-ops, the selected page retains reviewed Base. Page-file edits match reviewed After. Nonissue views are bounded samples. All issues and pages are paginated. The 53 protected operations have 212 all-four per-operation source proofs plus four overall proofs (864 raw inventory pairs across four categories) and 53 root pairs. Seventy-one retained artifacts are bound. No Apply, saved plan or consumer write occurred. The completed corpus’s file-only collector needed two preserved metadata corrections for absent historical trial/self-test files. No CLI/Hugo operation was rerun.

The repository retains its 10,462 pre-existing duplicate-ID findings and 788 review-info records. Its selected actual DFE HTML is available. Four oversized actual PRINT files remain unserved (413, zero response body): _print/pkg/index.html 73,976,221 bytes, _print/pkg/pgsql/index.html 69,903,999, zh/_print/pkg/index.html 73,086,240 and zh/_print/pkg/pgsql/index.html 69,052,754. The 64 MiB per-file preview bound is unchanged. Required partial-preview incompletion remains 2. Native findings remain 1. Apply is refused.

Linux prerequisites were prepared in exclusively owned guests from signed Debian metadata. Exactly ten new packages and three approved existing-package updates were verified before and after installation. SDK/Hugo/module caches were provisioned separately and reused offline. Qualification runs as an ordinary user on ext4. Cached inputs and all 212 source files’ bytes/full modes stay guarded. Default unit skips retain their actual gating/not-applicable reasons. All required pure top-level cases, no-skip membership children, selected Hugo cases, and signal cases must execute. Linux amd64 uses QEMU TCG on the ARM host and is explicitly emulated. Darwin amd64 remains an experimental archive. Actual execution returned Bad CPU type (errno 86). Windows is outside the declared scope.

The current Linux archive digests are ac883e54a1df0b820696279c63881ba75a00d279f507330128fe8d5aff59c52e (arm64, 4,552,687 bytes) and 2dde43bf94ef35aac2111b07dcb9b2766fbf9f883fe39ccd646d14a98b94d734 (amd64, 5,034,668 bytes). The preceding 683daca0…33f224 archive digests c191383af21913be6940ec41be11755b3d985344bbc0f65cc3f5de16424a96a4 and 6531b27d889260afe804c1f49f37541fbae46e57b5d17a20178c28cb51968794 remain historical. SDK/guest preparation failures, the first ext4 membership failure, and earlier private host metadata/resources trials remain immutable evidence. Uninvoked E1–E4 extensions are separate inactive scope.

8.13 - Document comparison research, 2026-10-29

Dated evidence for a generic OINK side-by-side reading mode across languages and revisions.
Historical research; see the 1.5.0 decision

Research date: 2026-10-29. This bounded source review of OINK v1.4.0 informed the translation reader in OINK 1.5.0. The accepted decision and the shell contract describe the released behavior and supersede the recommendations below.

Scope and evidence

The question was how OINK could support a generic comparison reading mode for roughly 30–40 local sites: translated documents, eight-language sets, proofreading books, arbitrary languages, and old/new revisions in one language. The review covered Docusaurus, VitePress, Material for MkDocs with mike, Read the Docs, Hugo, Sefaria, MediaWiki ContentTranslation, OmegaT, Weblate, Joplin, VS Code, and CodeMirror. Evidence came from official documentation and pinned source revisions; no upstream application was started and no browser behavior was claimed from source inspection alone. Unpinned official documentation records what was read on 2026-10-29; it is not an immutable source snapshot. OmegaT evidence is limited to the 6.1.0 manual, not an inspected implementation.

Project Fixed documentation/source revision Verified relevance
Hugo v0.168.0 source commit e27a6760c5547237f87d353aebe0580feadb20f4 Page relationships and native version rotation; no paragraph alignment.
Docusaurus, VitePress, Material/mike Docusaurus v3.10.2, VitePress v1.6.4, Material 9.8.0, mike v2.2.0 Stable identity, explicit anchors, version metadata, and existence-aware navigation.
Read the Docs and VS Code RTD platform commit 9b012b1df15fc153590b4db5f4da7bd3eb8ae74a; Addons d8f99069d9a8b9647f5bd68fdedb95ffa11e63ce; VS Code d7658021df8289f549bf2af8c8dec131f2580d69 Real rendered HTML/Markdown comparison and mapped previews; neither proves a generic OINK reader.
Sefaria and ContentTranslation Sefaria af96a1a1695a6307a3d616493455a6802455be1b; ContentTranslation 8d5dde493528330efcb373dc448f352e81815115 Independent panes and strict segment rows are separate products.
Joplin, OmegaT, Weblate, CodeMirror Joplin b48e75856d81152c32e71f21075e1c043d9ea922; OmegaT Standard Manual 6.1.0; Weblate 503129cadb056e2ea0db629fe8e37907b41ff054; CodeMirror 53c8f7b213332743a1f4f7d26bf40cfe2b512b53 Logical scroll maps, manual alignment, stable message context, and geometry spacers.
DDIA consumer sample Vonng/ddia a6b2e6f85e1249720c8a349273455190d2fc9515 Four Hugo members with repeated Chinese locales and distinct editions.

Identity and relationship lessons

For the original general-purpose scope, comparison would need to keep candidate-set identity, member identity, Hugo site key, actual locale and direction, edition/version, canonical URL, and anchor correspondence separate. A language code is not a document identity. The pinned DDIA configuration provides a concrete case: zh, tw, v1, and v1_tw are four configured members that include repeated Chinese locales and different editions. Deduplicating by locale would remove valid choices and mislabel editions as translations.

Hugo 0.168.0 provides a sound starting point. .AllTranslations includes the current page and .Translations excludes it; an explicit translationKey can relate pages whose paths differ. .Rotate "version" can adapt native version dimensions while holding other dimensions, including language and role, fixed. That adapter is optional for comparison and does not require a consumer to reorganize content. It must not be confused with an OINK params.versions menu, which is a navigation configuration rather than a semantic partner resolver. Custom version or role dimensions still need an explicit adapter so ambiguous native matches are not silently accepted.

Automatic translation candidates should therefore begin with the actual Hugo page relationship, then pass an eligibility filter: published, built, renderable HTML siblings; the selected page is excluded; home pages used as language-navigation fallbacks are excluded; foreign role or version members are excluded when the set requires that boundary. A navigation link proves that a destination exists, not that it is a translation or a comparable document. Missing translations remain missing; OINK must not copy source text behind the reader’s back.

The original generic design used two selectors for an eight-language set. It does not require 28 prebuilt pair pages or eight simultaneously loaded documents. Same-language v1/v2 comparison uses two member IDs and explicit labels. The same identity model also supports a proofreading book whose chapter structures differ, without pretending that equal filenames or title text establish correspondence.

What existing tools actually compare

Docusaurus document identity, localization, and versioning separate ID, slug, locale, and version tree; its heading guidance advises stable IDs for localized pages. VitePress constructs locale links from the current relative path in the inspected language helper and supports custom anchors, but that helper does not establish a semantic partner registry. Material uses mike version metadata and target sitemaps to find a corresponding URL; that confirms addressability, not semantic equivalence. These are useful identity and validation patterns, not evidence of native two-pane scrolling.

Read the Docs supplies direct fixed comparison evidence: its visual-diff documentation and Addons docdiff.js compare a rendered HTML body, mark changed DOM regions, and preserve a URL mode flag. This is a single-page rendered diff for review workflows. VS Code’s Markdown diff documentation and diffScrollSync.ts show two rendered previews with logical mappings and feedback suppression. They demonstrate that rendered comparison and mapped scrolling are feasible, while leaving OINK’s content identity and static-host constraints unresolved.

Sefaria explicitly distinguishes an independent Compare Text view from a shared-segment bilingual view: TextRange.jsx renders both texts inside a shared segment, while TextColumn.jsx keeps comparison columns independently scrollable. MediaWiki ContentTranslation’s alignSectionPair uses stable section IDs and height/margin compensation for paired translation regions in a single editing flow. OmegaT’s Align Files manual combines automatic matching with manual split, merge, move, and acceptance operations. Weblate’s Unit model keeps message IDs and context separate from text hashes. CodeMirror’s updateSpacers shows the geometry cost of aligned rows. Together they show why automatic similarity can suggest a relationship but cannot silently publish a paragraph map for arbitrary multilingual HTML.

Three reading semantics

The design must name three different behaviors. Independent scrolling gives each pane its own position and is the fallback for every valid pair. Anchor-linked scrolling keeps two independent panes and uses shared semantic anchors to estimate corresponding progress between anchors. It is a nearby section reference, not permanent paragraph or line alignment. Strict row alignment puts actual blocks into paired rows, uses the maximum row height and spacers for the shorter side, and needs one-to-many mapping, missing-block placeholders, and an explicit order policy. It is a separate later feature.

For OINK, the proposed default depends on mapping quality: enable anchor-linked scrolling only when the conservative conditions below pass, otherwise use independent scrolling. The reader can always turn synchronization off. A pair with zero or one valid internal anchor, duplicate explicit targets, missing explicit targets, or non-monotonic moved anchors stays independently readable. Ordinary unmatched sections are content gaps, not invalid targets. A direct “jump to counterpart” action can still work where continuous synchronization cannot.

Rendering and isolation finding

OINK’s v1.4.0 Docs shell, content rendering, Book ID handling, tabs, table reader, diagrams, and capability-selected scripts make arbitrary single-DOM body concatenation a large refactor. Two same-origin document frames preserve each page’s lang, dir, resource base, renderer context, IDs, and reader ownership. A frame is a document boundary, not an independent process or a security sandbox; same-origin content remains trusted content. See the iframe reference and same-origin policy.

The initially considered path used a prototype with ordinary eligible HTML pages in two same-origin frames and guards for navigation, keyboard shortcuts, analytics, comments, and recursive compare entry, then considered an optional content-only HTML view. The revised first phase keeps ordinary pages for the implementation too; a dedicated output is only a future optimization if measurements justify it. Hugo parameters alone cannot create an output format; any auxiliary output needs explicit output plumbing, Page Store/capability handling, relative-resource rules, and SEO policy.

Scroll model and bounded conclusions

The useful engine pattern is Joplin’s logical map and VS Code’s mapped rendered previews. Joplin’s scrollmap.js and VS Code’s diffScrollSync.ts support collecting layout-valid anchors, interpolating within intervals, and clamping positions. The revised translation MVP derives a strictly monotonic mapping from shared stable heading IDs; it needs no separately authored or reviewed pair map. Crossing or reordered anchors reject that map; the engine must not silently choose an LIS, drop moved anchors, or reorder the document. Geometry is invalidated when fonts, images, diagrams, tabs, details, or width changes alter layout. A state owner and sequence token prevent programmatic scroll events from echoing back. The user should keep focus and pane ownership; ordinary scrolling must not open hidden content or move focus.

An unmatched section is an ordinary content gap when the page and its surrounding anchors are valid. If valid anchors bracket it, the reader may label the interval approximate and interpolate through it. In a future manual-mapping feature, an explicit target that does not exist, is duplicated, or crosses another explicit target is an invalid mapping; it disables continuous synchronization for the pair rather than becoming an ordinal fallback. A direct explicit jump can report the invalid target.

The evidence supports a focused proposal, not an implementation claim. The upstream source investigation did not run the candidate comparison feature, a server, a browser, accessibility checks, or an eight-language consumer. It also did not prove that every framework lacks plugins or experimental comparison modes. Those limits are carried into the proposal’s acceptance matrix and keep the recommendation honest: first prove normal Docs/Book reading with two panes, then decide whether richer output or strict row comparison earns its maintenance cost.

Phase-one scope revision

Following the request to simplify on 2026-10-29, the companion proposal now assumes existing translation siblings with matching heading IDs. Its only site setting is params.ui.compare: true. Hugo supplies the existing translation links; the browser chooses one target and displays two ordinary pages in same-origin frames, with an on/off synchronization switch. The current language is fixed and only the target needs a selector.

The broader identity discussion above remains research for possible version comparison. It does not require phase-one compare sets, member IDs, manual anchor maps, a CLI, new layouts, new outputs, or prebuilt language pairs. Ordinary pages in frames are the recommended first implementation, not a necessary step towards a content-only output. The existing host remains behind the reader: two child documents plus that host means three documents, a cost to measure before adding another rendering path.

8.14 - CLI acceptance snapshot, 2026-09-29

Executed Starter, real-site, offline, upgrade, and reproducible-archive checks for the local CLI candidate.
Historical CLI acceptance snapshot (2026-09-29)

This page records the 2026-09-29 validation of the local 0.1.0-dev CLI candidate at commit e623d93. Current CLI behavior is defined in the CLI and result contract.

Inputs and method

The CLI belongs to the independent oink-cli Go repository. The CLI and result contract defines its accepted boundary. The CLI introduction gives reproducible user steps. Hugo remains an external renderer. Generated sites contain normal Hugo inputs.

Input Observed baseline
Host macOS, darwin/arm64
Go go1.27.1
Hugo 0.166.0+extended+withdeploy
CLI 0.1.0-dev, local commit e623d93d589c49e5c58b8fae1bd5db720fc904cb
Embedded Starter Commit 137843b25bacd76ddd1f7ce71330bf2e3155b954, complete licensed Git archive
Generated theme pin Public github.com/pgsty/oink v1.1.0, with recorded Go checksums
Documentation-site theme Local theme HEAD b0af631 plus uncommitted changes

The Starter archive hash is e55bde279715f6d8d19d3d88671a2cf7561b515be46915b0f12c640d0ce1d958. Its recorded projections select an existing language profile, pin OINK v1.1.0, and set enableGitInfo: false for a new directory. An observed failure required the last projection. The original enableGitInfo: true caused a warning-strict build to fail before the site’s first Git commit. No Git repository or commit was created to hide that failure.

Checks used disposable source copies, module/render caches, and output directories. Original Starter and consumer source trees were not written by the CLI checks. Existing unrelated theme and documentation edits were retained. The counts below describe those inputs and CLI revisions on 2026-09-29.

Starter and ordinary Hugo

All six ordinary-Hugo cases passed --environment production --panicOnWarning, with provisioned modules and isolated caches:

Language profile Root URL /manual/ subpath Reported Hugo pages
en Passed Passed EN 90
en,zh Passed Passed EN 91, ZH 89
all Passed Passed EN 91, ZH 89, FR 89

The tests checked the expected language roots and representative Docs, Blog, and Book outputs. They compared generated source bytes before and after Hugo. The public CLI’s init command also passed separately for all three profiles, returning zero diagnostics and 94 generated source files per profile. The profiles select different root configurations and disable untranslated sample files while retaining them in the snapshot.

Starter package unit, race, and vet checks passed. Failure cases cover nonempty and symlink targets, validation failure, and target replacement after planning. They also cover cancellation rollback, concurrent modification/deletion, and archive path rejection. The regeneration script reproduced the fixed archive, provenance, and license exactly.

Real-site inspection snapshot

Each run below returned CLI exit 0 with zero recorded diagnostics.

Site shape and theme source Files HTML files References Machine artifacts
Three-language Starter, public v1.1.0, release check at /manual/ 316 142 7,042 6
OINK documentation/regression site, local theme HEAD b0af631 plus dirty changes 1,127 506 72,562 8
PIG project site, root Docs/Blog route rewrites, public v1.1.0 1,392 424 64,440 4
Repository documentation with generated catalog, public v1.1.0 3,287 1,635 851,535 12

The last three are local consumer repositories: PIG and the catalog site validate published-pin resolution, while the OINK documentation run validates the local theme checkout.

The inspection covered HTML links, anchors, resources, and emitted machine artifacts. The completed Hugo manifest enumerated 261, 766, 662, and 3,192 output declarations respectively. Every supported enabled machine output was required by its actual language and URL. Before/after manifests compared all tracked and non-ignored untracked source bytes, modes, and Git status. All four sites were unchanged (94, 415, 858, and 2,294 source files respectively).

Two real regressions were fixed during this work. A NAVJSON template rendered only English. This previously hid the missing Chinese output. The check now returns policy exit 1 with the missing output location. The check initially treated PIG’s intentional build.render: link sidebar entries as missing pages. Hugo’s effective build parameters now exclude them. Direct and cascaded regression cases verify this behavior. A paired build of the bilingual Starter also proved all 223 ordinary artifacts byte-identical before and after adding the isolated probe.

Offline execution and upgrade

On macOS, a full check of an initialized bilingual Starter passed under sandbox-exec with (deny network*), after dependency provisioning. The result was exit 0, zero diagnostics, 223 files, 95 HTML files, 4,461 references, and four machine artifacts. A separate English init also passed under the same OS-level network denial, returning exit 0, zero diagnostics, and the expected 94 generated files.

A cold-cache fixture requiring example.invalid/[email protected] returned CLI exit 2 and retained Hugo’s original module lookup disabled by GOPROXY=off evidence. A missing dependency was therefore reported as incomplete work, without silently enabling resolution.

A separate temporary site exercised a real public-module upgrade from v1.0.0 to v1.1.0. The original consumer was not used as a write target:

Operation Observed result
Preview Exit 0; candidate validated; applied: false; plan named only go.mod and go.sum
--write --expect-plan Exit 0; the matching plan was validated and applied
Repeat the same target version Exit 0; candidate validated; no proposed changes and applied: false

All three operations preserved unrelated dirty README.md content and untracked user-note.txt. The preview and write used the same plan ID and before/after module-file hashes. Replacement, workspace, dirty-file, rollback, and failure-protection cases passed the final focused Go tests and race run. Only go.mod and go.sum changed on write; backup manifests retained original bytes. Preview and repeat executions preserved all source bytes.

Real thin-wrapper smoke tests also passed in a disposable initialized site. build --json returned 0 and produced index.html. dev --json served HTTP 200, forwarded SIGINT to Hugo, and closed the listener. Hugo exited 0. The canceled wrapper reported 2, as specified by the cancellation contract. These runs used provisioned local caches without --network.

Final make test (all packages plus vet), make test-hugo (ordinary Hugo, workspace/config precedence, output manifest, missing-language regressions), and go test -race ./... passed. All three public init profiles were rerun under OS-denied networking; the cold dependency fixture again returned 2.

Archive and installation preparation

One frozen CLI source snapshot produced four binary archives and one source archive, plus SHA256SUMS. Rebuilding independently from the source archive produced the same SHA-256 values for all five archives. The tested packaging input hash was:

b07c5b98ef787dfe9924ce7b50c57d018c6149ec493124bb0103551a01535547

This final snapshot supersedes the intermediate archive experiments. All five archive checksums were verified and reproduced from the extracted source archive. Both source and binary archives include the versioned JSON schema, licenses, dependency pins, and Starter provenance. Local make install into a temporary prefix and the installed binary’s --version succeeded.

Target Evidence
darwin/arm64 Compiled; host binary executed; local installation path exercised
darwin/amd64 Cross compiled only; not executed on that architecture
linux/amd64 Cross compiled only; not executed on Linux
linux/arm64 Cross compiled only; not executed on Linux

The archive builder records the toolchain, flags, source-input hash, and platform targets.

Reproduce the relevant checks

From a CLI checkout with dependencies already provisioned:

make build
make test
make test-hugo
go run scripts/snapshot-starter.go --source ../oink-starter

To repeat rendered-site checks in the sibling layout, keep JSON and logs outside each consumer’s source tree:

oink_acceptance_dir="$(mktemp -d)"
mkdir "$oink_acceptance_dir/reports"
./bin/oink init "$oink_acceptance_dir/my-docs" --languages all
./bin/oink check --site "$oink_acceptance_dir/my-docs" --release \
  --base-url https://example.org/manual/ --json \
  > "$oink_acceptance_dir/reports/starter.json" \
  2> "$oink_acceptance_dir/reports/starter.log"
HUGO_MODULE_REPLACEMENTS="github.com/pgsty/oink -> $(cd ../oink && pwd)" \
  ./bin/oink check --site ../oink.pgsty.com --json \
  > "$oink_acceptance_dir/reports/docs.json" \
  2> "$oink_acceptance_dir/reports/docs.log"
./bin/oink check --site ../pig.pgsty.com --release --json \
  > "$oink_acceptance_dir/reports/pig.json" \
  2> "$oink_acceptance_dir/reports/pig.log"
./bin/oink check --site ../repo.pgsty.com --release --json \
  > "$oink_acceptance_dir/reports/catalog.json" \
  2> "$oink_acceptance_dir/reports/catalog.log"

On a macOS host providing sandbox-exec, after initializing a bilingual site:

./bin/oink init "$oink_acceptance_dir/my-bilingual-docs" --languages en,zh
sandbox-exec -p '(version 1) (allow default) (deny network*)' \
  ./bin/oink check --site "$oink_acceptance_dir/my-bilingual-docs" --json \
  > "$oink_acceptance_dir/reports/offline.json" \
  2> "$oink_acceptance_dir/reports/offline.log"
sandbox-exec -p '(version 1) (allow default) (deny network*)' \
  ./bin/oink init "$oink_acceptance_dir/offline-en" --languages en --json \
  > "$oink_acceptance_dir/reports/offline-init.json" \
  2> "$oink_acceptance_dir/reports/offline-init.log"

The command reference describes preview, plan review, and explicit application. Use a separate review copy for write-path testing. For the archive experiment, keep the same Go toolchain and release version:

make release VERSION=0.1.0-dev DIST=dist/first
mkdir -p dist/rebuild
tar -xzf dist/first/oink_0.1.0-dev_source.tar.gz -C dist/rebuild
make -C dist/rebuild/oink_0.1.0-dev_source release \
  VERSION=0.1.0-dev DIST=dist
cmp dist/first/SHA256SUMS \
  dist/rebuild/oink_0.1.0-dev_source/dist/SHA256SUMS

Limits and delivery state

State At this snapshot
Local implementation Six first-stage commands and versioned result format exist
Executed validation The runs described above passed for their recorded inputs
Owning checks and documentation-site make check Passed after implementation and bilingual-document updates
Commit, tag, push CLI committed locally as e623d93; no tag, remote, or push. Documentation changes remain local alongside existing work
Public CLI release or distribution Not performed
Consumer source adoption or production deployment Not performed by these checks
Independent-user study or adoption No measured 4-of-5 / 15-minute study, retention, or independent-team adoption data

Raw JSON, logs, source-preservation manifests, upgrade recovery evidence, and archive-verification results are stored in the CLI checkout’s ignored tmp/acceptance/ directory, with release archives in dist/first/.

This first-stage candidate focuses on existing OINK sites; Docsy assessment and later migration, theme descriptor, version lifecycle, OpenAPI, MCP, and Studio remain tracked in the CLI roadmap.

8.15 - Component refinement, 2026-10-25

Local four-preset component validation, asset measurements, and separately reproduced gallery baseline failures.
Local acceptance record

Phases 0–3 and final acceptance in phase 5 are complete for this component change. The moving selection trial remains deferred.

Inputs and method

The final review used isolated sibling checkouts based on theme 7f9589f and documentation 855d890, with only this task’s source changes applied. Concurrent PlantUML, toolchain, and workflow work was excluded from the candidate and preserved in the shared worktrees. The accepted implementation is theme commit 15c39ef; guides, contracts, examples, and browser coverage are in documentation commit 81e2be9.

Validation used macOS ARM64, Hugo Extended 0.168.0 with built-in LibSass, Go 1.27.3, Node 26.12.0, and npm 11.20.0. Browser previews used the isolated sibling theme and hugo.yml,tests/fixtures/browser.yml, with both workspace mechanisms, watching, and live reload disabled. Screenshots came from actual documentation output. The bilingual comparison guide owns the reusable examples.

Executed validation

Check Result and scope
Theme component owners SCSS/compiler hooks, fonts, presets, content primitives, components, code blocks, and Landing passed. Invalid variants and inapplicable command strips warn and preserve content.
Theme shell/output owners Shell, actions, palette, keyboard, runtime isolation, and output checks passed. Output security passed on 501 fixture files with the fixture’s intentional third-party embeds enabled.
Real site make check passed all 64 non-browser tests, including bilingual headings, rendered Markdown, and internal links. Reviewed navigation/backlink additions account for the site’s Markdown golden changes.
Full browser suite make browser passed 409 Chromium tests. After the last correction to hide an empty command action column without JavaScript, all 20 presentation tests and the SCSS checker passed again against a fresh build.
Presentation coverage Four presets × light/dark × EN/ZH; 1440/768/390/320px layouts; literal clipboard text; independently operable native and full card links; native disclosures; no JavaScript; print; coarse pointers; reduced motion; forced colors; and Landing feedback width/contrast.
Additional engine review Chromium 151.0.7922.34, Firefox 153.0, and WebKit 26.5 passed 48 preset/mode/locale combinations covering Tabs, Fields, card links, and 1440/390/320px layouts. The final no-JavaScript command presentation also passed in all three engines.
Visual review Reviewed actual Paper, Slate, Ink, and Terminal cards, disclosures, Tabs, command strips, and field labels in light/dark and desktop/mobile output. Stable viewport captures preserve each preset’s geometry and reading hierarchy.
Production The final candidate passed a minified production build. Resource measurements below use the CSS linked by the generated page and the same documentation source for both builds.

The full suite’s A11Y_PATHS covered EN/ZH Presentation, Cards, Callouts, Tabs, Code, and Fields, plus English Badge and Kbd: 14 routes. The existing responsive accessibility matrix ran as well. Presentation axe scans included the article at 390px; the Landing check included its command box in all eight preset/mode combinations. Giscus requests were blocked as in the existing suites.

Asset cost

The exported theme base and the final candidate used the same documentation source and production build mode:

Asset Before After Change
Minified main CSS 528,665 bytes 539,450 bytes +10,785 bytes
Main CSS, gzip 79,541 bytes 80,887 bytes +1,346 bytes
Built JavaScript 39 files Identical hashes 0 bytes

These final measurements supersede the earlier 539,437-byte / 80,856-byte initial refinement measurement. No framework, font, remote asset, or JavaScript dependency was added.

Tab review follow-up

Maintainer review rejected the raised selected Tab. The accepted treatment keeps individual labels transparent at rest, supplies a subtle fill only on hover-capable devices, and uses link color plus a 2px bottom rule for selection. Labels retain the same medium weight and position. Keyboard focus has its own outline; coarse-pointer targets remain at least 44px high. Final engine review verified these states, arrow-key selection, and narrow layouts.

Field names and final corrections

Terminal field names now use the same unboxed, emphasized monospace treatment as the other presets. Both native Markdown tables and full Fields shortcodes were checked in EN/ZH and light/dark output. Ordinary prose code and keycap borders retain their separate role.

Final review reproduced and fixed two further edge cases:

  • A native card’s stretched title link intercepted a secondary link nested inside emphasis. Secondary controls now remain above that target; pointer checks verify both the nested link and the rest of the card navigate correctly. The title’s keyboard focus outline follows the card’s own shape.
  • A command strip retained a small empty action column when JavaScript was disabled. The wrapper now disappears until its copy control is available. In all three engines, the source column occupies the full 356px inner width of the 390px sample, while the normal enhanced copy control remains usable.

Baseline failures and limits

Two theme checks fail identically in the exported base and the component candidate:

  • check-namespace.py: committed blog gallery output uses unprefixed data-height, data-width, data-mode, and data-size, with corresponding unprefixed dataset reads.
  • check-goldens.py: the committed gallery’s prepaint condition, toolbar icon, and gallery markup are absent from the existing theme goldens. Comparing base and candidate with the checker’s normalizer found no additional difference across all 52 golden surfaces.

The component checker also includes a targeted correction: reject obsolete configuration keys rather than any occurrence of gallery, allowing the valid blog_gallery key.

Local acceptance covers this component change and its two final repairs. Ink and Terminal retain their experimental status. Runtime JavaScript is unchanged.

8.16 - Review repairs, 2026-11-06

Reproduced build, feed, navigation and interaction defects, bounded repairs, and remaining review work.
Development evidence

This record describes local changes after v1.5.0. It does not establish a new release, consumer upgrade, or deployment. The original review’s roughly 170 entries have not all been accepted or fixed.

Inputs and method

The review started from theme 84b93e4 and documentation a8eeb92. The candidate keeps Hugo Extended 0.168.0 and its built-in LibSass, with Go 1.27.3, Node 26.12.0, npm 11.20.0, and Python 3.14.8 on macOS ARM64. The Hugo 0.169.0 executable on the normal system path is outside this validation baseline. Its golden differences are not evidence of a defect on 0.168.0.

Build and output claims were checked with synthetic inputs in the owning theme checkers. Interaction claims were checked against the sibling documentation site through Playwright. Browser previews used the local theme replacement and hugo.yml,tests/fixtures/browser.yml, with both workspace mechanisms, watching, and live reload disabled. Existing passing snapshots were reviewed before recording intentional changes.

Confirmed defects and repairs

Area Confirmed behavior and repair Repeatable evidence
Invalid input Positional arguments reached map-only shortcode operations and failed the build. Named-parameter guards now warn and safely omit or fall back. Negative checks require exit status zero. check-content-primitives.py, check-book.py
Book numbering Invalid numbers produced empty targets such as fig-. Unnumbered content now retains readable output without target registration. check-book.py: HTML, print, Markdown, BookManifest and index rows, with valid-number controls
Nested components Independent Markdown documents and sibling shortcode containers reused local ordinals. Generated IDs and their references now include the containing scope. Authored code IDs are preserved. check-code-blocks.py: repeated nested code, fields, charts and FileTree in HTML and print
Feeds Weight-based order was limited before date sorting, undated items emitted year-one dates, and several components emitted raw Markdown. Both feeds now sort before limiting and omit unavailable dates; components use static HTML or their documented omission. check-content-primitives.py, check-book.py, RSS goldens
References and versions Missing manual references could fail Hugo; version links could repeat the deployment prefix. Shared resolvers now provide warning fallbacks and join version paths once. check-agent-indexes.py, check-actions.py
Navigation under subpaths Language-neutral navigation IDs and section-index keys retained the deployment prefix. A shared key resolver now removes deployment and language prefixes while published links keep both. check-agent-indexes.py: EN/ZH under root and subpath deployments, with and without a default-language directory
Landing Invalid record shapes and optional fields could break Markdown output. HTML and Markdown now share record and URL validation, preserve fragments and queries, and include standalone CTA links. Unsafe targets do not become empty links. check-landing.py
Blog navigation List pages inherited article-sequence navigation and English pagination. Localized semantic pagination now owns list navigation and head links. check-reading.py, check-shell.py, browser pagination regression
Focus and menus Native disabling removed focused controls; hidden self-links were unreachable; focus-opened menus reopened after Escape. Guarded aria-disabled controls retain focus, self-links remain reachable, and Escape restores focus before closing. JS units and browser code, shell, comparison and Expo suites
Mobile shell Navbar-only articles lacked mobile utilities, and closed sidebar drawers leaked a shadow. Site drawers now expose language, version and repository links; shadows appear only when open. check-shell.py, responsive browser regressions
Layout Book TOCs displayed two counters, prose margins affected component lists, Landing padding was overridden, and global link rules suppressed print underlines. The owning rules are now scoped correctly. Browser review regressions and SCSS checks
Locale and schema Pagination and breadcrumb labels were untranslated; several locale strings and the appearance legend were incorrect; the schema rejected language-code translation notices. Labels now cover all 32 locales and generated schemas match the resolver. check-i18n.py, generate-config-schema.py --check
Preset and alternate rendering Terminal’s current-row chevron selector was wrong; focus rings were translucent or clipped; forced colors hid current-state cues; the RTL artifact overwrote font roles. Targeted rules now retain these states. Repeated marquee rows are hidden from assistive technology. Preset/SCSS checks and browser accessibility coverage

Qualifications to the original review

The original report’s severity labels grouped build failures, accessibility defects, wording, and design preferences together. They should not all be treated as release-blocking failures. Reproducible build and output defects deserve the first repair batch; cosmetic consistency needs its own acceptance criteria.

“No TOC” does not mean “empty right rail.” Blog indexes can still contain author, category, series, and tag clouds. Removing the fallback control made that rail impossible to collapse and failed the existing RSS/browser regression. The final repair omits genuinely empty rails and labels populated non-TOC rail controls as sidebar actions. It preserves collapsing, focus restoration, and RSS access.

RSS fixes do not require every component to appear in feeds. Release assets keep their explicit omission. The Book checker now exercises the ordinary section feed instead of treating raw RenderShortcodes output as the RSS contract.

Different corner radii, duplicated template shells, and native/shortcode layout differences are maintenance or design concerns until a specific contract or user failure is demonstrated. Merging base templates solely because their bytes are equal can change Hugo lookup precedence. No such broad consolidation is included.

Validation

The theme’s focused checks, schema parity, 32-locale parity, 80 JavaScript tests, and 90 migration tests were run on the fixed toolchain. Output changes cover 52 HTML, print, Markdown, RSS, and LLMS golden surfaces. These checks are local unit and output evidence; the separate CI PDF/EPUB publication job is not claimed.

The documentation site’s final make check passed, including all 64 non-browser tests, with a larger Node heap for its rendered-link scan. A local production build also passed and generated 462 pages per language, with only the accepted upstream LibSass deprecation warning. The first browser pass completed all 30 accessibility tests; the responsive group passed 117 tests after retaining the taxonomy rail control. The other canonical browser groups also passed in their respective runs: keyboard 16, content components 70, code blocks and Landing 37, PRD5 8, theme color 10, community feedback 42, appearance 53, Expo 50, gallery 8, PlantUML 8, diagrams 19, table reader 15, standard comparison 19, and eight-language/RTL comparison 6. The canonical browser set totals 508 passed tests across these runs. A later focused accessibility run passed all 30 cases on the new research and blog pages. After the Escape correction, a fresh shell, blog and menu regression run passed 56/56. The final Landing checker passed after its metrics links were routed through the same URL policy.

The browser counts describe this repair candidate before separate comparison interface work appeared in the shared checkout. That concurrent work is outside this record’s browser acceptance. The completion audit additionally verified navigation keys under language/deployment prefixes and invalid Book numbers in HTML, print, Markdown, BookManifest, and the generated indexes.

Remaining work and order

This is a bounded repair batch. The following work remains outside its acceptance:

  1. Reader control over single-character shortcuts, command-palette handoff and localized error messages, and plural-aware contributor/search/code counts.
  2. Non-default-language Google search destinations and the documented meaning of relative content URLs.
  3. Remaining contrast cases and the previously recorded narrow, large-text footer overflow. These require their own rendered reproductions and browser checks.
  4. Geometry, interaction-state and overlay tokens, remaining manual-link owners, shared shell structure, and stylesheet size. These need bounded design decisions and measurements rather than a blanket replacement of literals.

The component, shell, architecture, and Landing contracts describe this batch’s development behavior. Historical release claims remain unchanged.

8.17 - Ink and Terminal need reading acceptance

Source review, bounded visual evidence, current failures and promotion limits for Ink and Terminal on 2026-10-26.
Pre-release research snapshot (2026-10-26)

This record preserves inputs and measurements from before the OINK 1.4.0 release preparation. At 320px with a 32px root/default font, footer links cause document overflow across all four presets. Ink and Terminal remain experimental; the stabilization proposal defines desired behavior and promotion gates.

Keep Ink neutral sans editorial and Terminal a readable engineering handbook. Both can become coherent official styles through their existing role system and shared shell. A new serif identity would weaken Ink’s distinction from a future Folio; a simulated terminal would weaken long-form engineering reading. The immediate work is shared text resilience, quieter hierarchy, and component consistency.

The evidence identifies a local snapshot

This 2026-10-26 review combines primary-source text/HTML/CSS inspection, an exported source snapshot, real documentation rendering, and a bounded injected CSS comparison. Theme HEAD was 7bc8658bc1be13ef0ad3050b9d9f6862f8f1f65f; documentation HEAD was 99751179eefada3fa7a91318c792ddac46d7e6bf. The snapshot also included uncommitted changes, including concurrent table work; the retained source manifest records that full state. Public tag lookup observed v1.3.2, peeled to bd2e856e6e2f7027a9189af009701f5b8cf562cf; documentation pinned v1.3.2. See the earlier experiment and component review for prior context.

The documentation server used the sibling snapshot with hugo.yml,tests/fixtures/browser.yml, both workspace mechanisms off, memory rendering, no watching/live reload, and enableGitInfo=false because the export lacked Git metadata. Tools were macOS ARM64, Hugo Extended 0.168.0, Go 1.27.3, Node 26.12.0, npm 11.20.0, and Playwright 1.62.1; engines were Chromium 151.0.7922.34, Firefox 153.0, and WebKit 26.5 (Playwright WebKit scope).

The reproducible method loads the same real route, language, mode, and preset at each width, compares baseline with the listed overlay, records full-document dimensions and computed styles, then captures relevant components. Source manifests, review-metrics.json, api-supplement.json, text-resize-findings.json, stress-metrics.json, reference-rendering.json, and screenshots are stored outside Git.

Whole-document overflow outweighs targeted passes

At 320px/32px root font, English Ink had scrollWidth=424 (+104px), Terminal 408 (+88px). Chinese Chromium overflow was +12px/+21px respectively; English Terminal also exceeded 768px by 11px. The overlay produced the same failures. Firefox’s font.size.variable.x-western=32 preference reproduced English overflow across all four presets; Paper reached 413px and Slate approximately 400px. Footer links including “Customization”, “Components”, and “Docsy discussions” exceed two narrow columns. This is a shared baseline blocker across all presets.

These probes exercise CSS root enlargement and native default-font preferences. Combining 320px width with enlarged text is a stronger stress condition than standalone reflow. Full manual 200% text enlargement and 400% browser zoom remain pending (Resize text, reflow).

Owning checks: check-presets.py passed text/link/accent checks over three surfaces, mode parity, frozen Slate, and configuration output; check-font-tokens.py passed.

Existing suites: 28 appearance-engine, text-reflow, and component tests passed. Their page-context/topline assertions missed the footer. The source-snapshot make check passed 64 non-browser tests before these documents were added. With the new documents, the site built and passed Markdown, bilingual heading, and internal-link checks; 63 of the 64 non-browser tests passed, with llms.txt golden differing only by the two new English document entries.

Main measurement matrix: Chromium: 11 valid routes × two presets × two modes × EN/ZH × 320/390/768/1440px × baseline/overlay. Firefox/WebKit: presentation/configuration/Book only at 320/1440px. Normal-size pages showed no document overflow.

Counting correction: The initial ledger’s 960 entries were computed-state observations. A mistaken API route produced 32 harness 404s; the corrected /docs/write/openapi/ supplement contributed 64 valid observations with HTTP 200 and no document overflow.

Additional stress: 64 simultaneous spacing observations used line-height 1.5, paragraph margin 2em, letter spacing .12em, and word spacing .16em; no page/heading overflow was observed. Sixteen 320px long-unbroken heading/Field-label probes preserved text without page overflow.

axe: 32 article scans at 390px covered presentation/configuration, both languages/modes/presets, and baseline/overlay. No violations were reported; all scans retained contrast incompletes on aria-hidden=true pager-arrow spans with non-text characters, which require manual graphic-contrast inspection.

Visual material: The archive contains 352 comparison captures, including Blog/Expo/Mermaid/ECharts scenes, plus eight external references, from which representative desktop/mobile and light/dark pages and controls were reviewed.

Long reading: The real EN/ZH /blog/oink/oink-implementation-diary/ article was checked in four selected combinations: Ink EN/1440/light, Ink ZH/390/dark, Terminal EN/390/light, and Terminal ZH/1440/dark. Baseline/overlay captures at top/middle/footer produced 24 additional images; normal-size document overflow was zero throughout. Eight representative images were inspected, including English before/after prose, Chinese prose, Terminal’s English mobile footer, and Ink’s English desktop opening.

The Chromium routes were home, Presentation, Configuration, Fields, Code, Table, Book structure, immersive-reading Blog, Expo studies, Mermaid, and ECharts, plus the corrected OpenAPI guide, with Chinese peers included. The capture pass also verified the first rendered Mermaid diagram and an ECharts canvas. The comparison gallery spans 11 scenes; seven control scenes cover both presets, modes, languages, and two widths. Offsite requests, including Giscus, were blocked in the main matrix.

The overlay tests a limited editorial change

Ink kept its palette/fonts while changing article h1 from 800/-.035em to 750/-.025em, h2/h3 from 750/-.025em to 700/-.012em, and its 2px emphasis top rule to a 1px existing strong-line rule. It removed enforced uppercase/tracking on minor/table/callout headings, used zero Chinese heading tracking, and compared native underlines at max(1px,.06em)/.22em, with Chinese .25em and skip-ink: none.

Terminal kept teal/mint and amber, used heading weight 600/zero tracking, removed generated heading prefixes and callout brackets, changed descriptive table headers to body 0.875rem/600 and search titles/excerpts to body, and reduced decorative code/tab/table/callout frames to the existing border role. Technical paths/controls stayed mono and Field names stayed unboxed. FileTree’s omitted literal 0.6rem radius became 0px/2px for Ink/Terminal. Flat Tabs, mobile targets, and vendor boundaries remained intact. The overlay tested CSS adjustments only, without adding new theme templates, fonts, runtime, or configuration.

Authored accent colors on actual pages were documentation blue #245f94/#5da2dd, Book orange #9a3412/#fb923c, and Blog violet #6d28d9/#a78bfa. Separately labeled palette probes reset only that authored accent to the preset default on both variants for controlled comparison. The architecture contract preserves overrides and the shared shell.

Palette calculations expose state risks

Opaque sRGB calculations and alpha compositing used source tokens and the WCAG luminance formula; displayed ratios are rounded while pass decisions use unrounded values (Contrast method, palette source).

Pair, light / dark Calculated contrast Implication
Ink accent #c8102e on white / #ff5c4d on #0b0b0b 5.88 / 6.46 Retain mode-specific red; keep red accents focused rather than repeating decorative red rules.
Terminal body on canvas 14.88 / 13.64 Strong neutral reading pair.
Terminal link on canvas / secondary surface 6.31 / 9.54; 5.75 / 8.73 Existing teal/mint supports these exact surfaces.
Terminal tertiary text on secondary surface 4.63 / 5.93 Light muted text has little margin for further tint/opacity.
Terminal amber on canvas 5.47 / 9.44 Amber remains a separate emphasis role.
Terminal 32%-alpha border on canvas 1.97 / 2.36 Suitable for decorative rules; insufficient if it alone identifies a required control or state.
Terminal 55%-alpha strong line on canvas 3.63 / 4.73 Candidate functional boundary on these canvases.
White on dark mint #4cc9bd 2.02 Avoid white labels on light mint fills.

Cross-mode reuse fails ordinary text contrast: mint on the light canvas is 1.85, dark teal on the dark canvas 2.79. Semantic tones, author accents, syntax comments, selected search excerpts, focus, and text-selection composites still require state-specific review. Non-text contrast applies to necessary identifying boundaries (WCAG 1.4.11).

Mature precedents support roles, not transplantation

All external references were accessed 2026-10-26. External Chromium rendering at 1440/390px returned HTTP 200 for Tufte, GOV.UK Headings, Effective Go, and A List Apart. Eight captures were saved, with visual review focused on Tufte desktop, GOV.UK mobile, Go mobile, and A List Apart desktop; the remaining precedents received source review.

Practical Typography. Puts body text first; prescribes Latin-oriented size, spacing, and measure. Its underlining advice opposes link underlines.

Review complete paragraphs before display titles, while keeping OINK’s bilingual rhythm and open-source font constraints.

Tufte CSS. Inspected desktop shows a narrow serif reading column and underlines. CSS declares ET Book, light #fffff8/#111, dark #151515/#ddd, and mobile note toggles.

Borrow proximity of explanation/figures and note hierarchy; leave serif/margin geometry to future Folio exploration.

GOV.UK Headings. Inspected mobile view has generous sans headings and underlined links; cookie banner was visible. Current type scale uses 19px/25px body sizing on small and large screens. Links distinguish prose from navigation; tables emphasize structure.

Strongest functional input for Ink’s sans hierarchy and persistent link cues, adapted to OINK’s bilingual scale and dark mode.

A List Apart: A Dao of Web Design. Inspected desktop distinguishes serif body from sans headings/controls. Current CSS uses Georgia 1.125rem/1.7, red #ba3925 h2, and blue links.

Separate reading/UI/code roles and keep adaptable content while keeping Ink’s sans-serif identity and restrained accent frequency.

Rust Book: Ownership. Source exposes numbered chapter structure, explanations, and code; CSS separates Open Sans prose and mono code.

Strong Terminal precedent for explanation/syntax separation and real chapter numbers, while keeping OINK’s mono headings and standard browser shortcuts.

Effective Go. Source/CSS separates platform sans and mono; inspected mobile TOC is dense and two-column.

Borrow straightforward technical hierarchy while keeping OINK’s responsive TOC.

man7 open(2). Stable reference sections, signatures, links, and preformatted text; (2) names a manual section.

Preserve predictable lookup and complete identifiers without forcing bilingual prose into fixed-width terminal cells.

CLI Guidelines. A navigable explanatory web guide recommends intentional, limited color.

Borrow restraint and clear labels while keeping standard web interaction semantics.

Paper’s warm general reading, Slate’s established technical presentation, Ink’s neutral editorial restraint, and Terminal’s technical role contrast remain distinct within the shared shell.

Language and accessibility need independent evidence

Actual Chromium per-glyph inspection on macOS found Inter for Ink Latin, IBM Plex Sans for Terminal prose, IBM Plex Mono for Terminal headings, and PingFang SC for Chinese in both. Windows and Android fallback rendering still require direct device verification (CSS font matching, Windows fonts, Android fallback).

Chinese underline clearance remains open. The CSS Text Decoration Working Draft explains Han collisions and fragmented ink skipping; CLReq’s Group Note Draft discusses interlinear marks without banning hyperlink underlines. Next steps should compare language-scoped text-underline-position: under with a small offset and initial skip-ink: auto, including Chinese inside English pages and mixed-script wrapped links (CSS draft, CLReq).

WCAG A/AA governs color-independent meaning, text/non-text contrast, keyboard operation, resize, reflow, spacing, language, and status announcements. OINK’s proposed 44px routine touch targets, 7:1 main text, and stronger 2px-area focus treatment are tracked as project targets above AA minima (WCAG 2.2, axe-core, focus appearance).

Still pending are actual Windows/Android loaded/blocked/system-font comparisons; branded Safari/iOS rendering; manual NVDA, VoiceOver, and TalkBack tasks; full manual 200%/400% zoom; and comprehensive keyboard, forced-colors, and state-contrast review covering navigation, Book numbers, table relationships, field errors, Chinese search input, status feedback, and dialog return focus.

Promotion should follow resilient reading

The footer overflow highlights the need for whole-document regression checks alongside article-top checks. Shared repair and whole-document regression should therefore precede preset promotion. FileTree’s radius leak and competing Terminal punctuation are bounded owner-level changes.

For 1.4, refine existing owners and promote Ink or Terminal independently once their acceptance gates close; otherwise retain experimental status. Folio (academic serif) and Canvas (creator geometry) remain deferred to avoid font/licensing and QA overhead in this cycle.

8.18 - OINK 1.5.1 readiness review, 2026-11-06

Three reproduced candidate regressions, complete browser acceptance, and remaining publication gates.
Local repair acceptance complete

The three reproduced regressions below have been repaired in the working trees and the targeted, theme, site, and browser checks pass. This dated review does not announce a release, consumer upgrade, or deployment.

Inputs and method

The review covered theme v1.5.0 (84b93e4) through c55849e: all six post-tag commits and 186 changed files. The documentation site was 43990ac. Theme main was three committed changes ahead of origin/main (d9ad654). Both working trees were clean before the initial review. Its original evidence is retained below; the later repair pass is recorded separately. No tag, push, consumer update, or deployment was performed.

The formal local toolchain was Hugo Extended 0.168.0 with built-in LibSass, Go 1.27.3, Node 26.12.0, npm 11.20.0, and Python 3.14.8 on macOS ARM64. CI uses Node 24. Supplemental Hugo 0.169.0 checks do not replace the pinned baseline. The accepted upstream LibSass deprecation remained visible.

Methods included implementation and contract inspection, the ordered theme CI commands, sibling-site checks, production builds, Chromium tests, and controlled minimal reproductions. Temporary fixtures and generated artifacts stayed outside Git. Local-theme and published-module checks used separate commands with both workspace mechanisms disabled.

Confirmed regressions

P2: RSS format restoration contaminates another render

The final assignment in layouts/_partials/content/rss-description.html restores a captured tdOutputFormat into the page Store, which shortcodes also read. In the reproduction, a summary render restores html while the page’s RSS shortcode render still uses that Store, producing mixed static and interactive output.

The formal bin/check-release-assets.py run failed because the RSS checksum table header disappeared and data-td-asset and <button appeared. A standalone rerun and eight single-page reproductions passed; rerunning until green does not resolve the original failure.

For a more reliable reproduction, expand that checker’s RSS fixture to 24 RSS-only pages, each with release-card and 20 release-assets blocks. Keep its custom layouts/docs/single.rss.xml, which sets tdOutputFormat to rss before .RenderShortcodes, and keep the ordinary home feed enabled. Build fresh output on Hugo 0.168.0 and inspect each page XML for interactive markers.

Three candidate builds all contaminated docs/rss-9/index.xml. One captured output had six static tables, fourteen interactive tables, and 28 buttons. The same fixture against published v1.5.0 passed three times. Overriding only the candidate summary partial to omit the final Store restoration also passed three times.

The confirmed scope is the custom RSS-page render exercised by the required checker, not every ordinary feed. Keep format state stable within its rendering context and add multi-page coverage while preserving HTML, Print, and normal RSS summaries. The temporary removal was a causal probe, not an accepted fix.

P2: Blog pagination duplicates Print aggregates

layouts/_partials/head.html calls shell/blog-index-state.html for every blog section, including Print. That partial calls .Paginate, so Hugo generates Print archive pages that each contain the entire section.

Use three dated blog posts, outputs.section: [HTML, print], and params.ui.blog_index_size: 1. The candidate generates _print/blog/index.html, _print/blog/page/2/index.html, and _print/blog/page/3/index.html; all three contain all three bodies. Overriding only head.html with its v1.5.0 version generates one aggregate. Both builds succeed on Hugo 0.168.0.

The documentation site’s production build also adds four duplicate aggregates across its English and Chinese blog roots and release indexes, totalling 1,120,141 bytes. Large archives amplify this waste. Limit blog-index pagination and its head links to HTML, then verify one Print aggregate and correct HTML pagination links.

P2: A stalled Duo View document never reaches Retry

assets/js/document-compare.js returns immediately for about:blank, including when its 15-second timeout calls ready(true). A pending main-document request therefore consumes the timeout without invoking failure handling. Loading and busy states remain without Retry or a direct-link fallback.

In the sibling site’s browser fixture, open /tests/compare-reader/ and hold /zh/tests/compare-reader/?oink_compare_pane=1 pending with a Playwright route. Open Duo View and wait 17 seconds. The source pane is ready, the target remains about:blank, and there is one loading note, zero failure panels, and zero Retry buttons.

This is not covered by the existing 404 and slow-image tests. Timeout expiry must fail a still-blank document while ignoring its initial blank load event and preserving parsed articles with slow images. Add the stalled-document case to the site’s comparison suite and retain the localized fallback promised by the shell contract.

Initial validation

Check Result and scope
Theme CI commands 48 of 49 runnable steps passed on Hugo 0.168.0. The release-assets RSS step failed; theme acceptance is not all green.
Theme tests 81 JavaScript tests, 90 migration tests, and 22 snapshot/consumer-tool tests passed. Locale parity, schemas, vendor inventory, output goldens, and Sass-boundary checks passed.
Site make check Passed, including 67 Node tests and source, translation, rendered-Markdown, and rendered-link checks.
Site make browser A single complete invocation passed 518 Chromium tests in approximately 23 minutes. A11Y_PATHS was unset: the sitemap scan was unrestricted.
Candidate production build Passed with the local theme and ordinary production configuration. Only the accepted LibSass warning appeared. Print duplication was inspected separately.
Publication isolation All three PDF safety tests passed with real Chromium, including remote CSS blocking and disabled scripts.
Publication smoke test Current-candidate EPUB/PDF generation and owning artifact checks passed: five chapters, 31 EPUB targets, and a 23-page PDF. Local Pandoc was 3.12.1. The CI-pinned Pandoc 3.10, Java 21, EPUBCheck, and subpath matrix were not rerun locally.
Published baseline Go proxy v1.5.0 resolved to 84b93e4 with the site’s recorded checksums. The release-pin check and production build passed with replacements and both workspaces disabled.

Browser groups passed 30 accessibility, 117 responsive-shell, 16 keyboard, 70 content-component, 37 code/Landing, 8 PRD5, 10 theme-color, 42 community-feedback, 53 appearance, 50 Expo, 8 blog-gallery, 8 PlantUML, 19 diagram, 15 table-reader, 26 standard comparison, and 9 multilingual comparison tests. The local sibling theme used hugo.yml,tests/fixtures/browser.yml and the separate eight-language comparison fixture. Firefox and WebKit were not rerun.

The suite at the initial review did not cover the additional stalled-request and Print cardinality cases above. The earlier review-repair record explicitly excludes later Duo View work from its 508-test result; this review supplies fresh evidence for the current candidate.

Repair verification

The repair pass changes the working trees based on theme c55849e and site 43990ac. The changes remain uncommitted and are not included in the remote CI runs linked below.

  • RSS summary rendering no longer restores the stale format value. The owning release-assets checker now renders 24 RSS pages with 20 asset tables each alongside the home feed, asserting every static table and checksum and the absence of interactive controls. A temporary override with the pre-fix partial fails this check; the repaired partial passes.
  • Blog pagination in the shared head is limited to HTML. The reading checker verifies one complete Print aggregate, three distinct HTML archive pages, correct HTML prev/next links, and no Print pagination links. A temporary override with the pre-fix head generates three Print aggregates and fails; the repaired head passes.
  • Duo View distinguishes document timeout from the initial blank load event. The new browser case holds the target document pending, checks the Retry label and direct link, and verifies that Retry restores the pane when the request can proceed. It passes with the repair. The earlier slow-image case continues to cover readiness without waiting for all resources.

The bilingual architecture and shell contracts and the theme’s Unreleased changelog accompany these fixes. The site’s LLMS golden gains only the new research-page entry; the output diff was reviewed before updating it.

Repair acceptance Result
Theme CI commands All 49 locally runnable steps pass on Hugo Extended 0.168.0, including 81 JavaScript, 90 migration, and 22 snapshot/consumer-tool tests.
Site make check Passes all source/rendered checks and 67 Node tests.
Site make browser Final complete invocation passes 519 Chromium tests: 510 in the main suite and 9 in the eight-language comparison suite. A11Y_PATHS was unset, so sitemap accessibility coverage was unrestricted.
Production build Passes with the local theme. Each EN/ZH blog and release index has one Print aggregate and no Print pagination links; all four duplicate aggregates are gone.

Browser acceptance uses the installed Playwright browsers without an executable path override, allowing the bfcache case to select full Chromium. That case and the new stalled-document Retry test also pass individually. These results use the same local tool versions recorded above; the publication-toolchain limits in the initial validation still apply.

All three reproduced regressions are locally resolved. The next release gates remain commit and push of the reviewed changes, green remote CI for that exact revision, then the separate tag, Go-proxy, consumer-pin, deployment, and production-identity states.

Publication and adoption

The latest observed public tag remains v1.5.0. The green theme CI run, including Book publication, belongs to d9ad654, not local c55849e. The green site checks and browser workflow also tested the remote theme available then. They do not certify the three later local commits.

A read-only bin/update-consumers.py v1.5.0 inventory found 50 primary checkouts: 42 current, three module consumers skipped for non-default branches, and five classic themes/oink consumers. All 45 module pins were v1.5.0. Four classic theme repositories were clean at the exact v1.5.0 tag. The remaining source copy matched sampled implementation files; that is not a full identity audit. No consumer was upgraded or deployed. The skipped branches and classic copies need individual handling during eventual adoption.

Release exit criteria

The three repairs, their owning checks, browser coverage, and bilingual contracts are present locally, and the working-tree acceptance recorded above is green. The next gate is green remote CI on the final release commit. Deferred design and accessibility work from the earlier review remains a separate backlog; this record does not claim every historical finding is fixed.

After code acceptance, prepare the 1.5.1 changelog and current version references, push reviewed commits, and verify CI for that revision. Tagging, push and Go-proxy verification, consumer pinning and appearance checks, deployment, and production identity are separate subsequent states. Those future steps are normal release preparation and remain distinct from local repair acceptance.

8.19 - Theme review, 2026-10-13

Reproduced image escaping and interaction defects, their repairs, and local theme and consumer validation.
Local review snapshot

This record describes local source and tests against the v1.2.0 consumer baseline.

Scope

The review began at theme commit f8f476e, with existing consumer-maintenance and compact-sidebar changes and an ongoing English documentation revision in the shared checkouts. Those edits were preserved. During the review, the existing sidebar repair was committed separately as 8f1f08d; its file contents remained unchanged.

Work covered the theme’s owning checkers, runtime unit tests, synthetic output fixtures, the real bilingual documentation site, and two different consumers: DDIA’s book and SILO’s large documentation tree. Source inspection focused on URL handling, image output, message boundaries, focus transitions, runtime isolation, and navigation. Visual review used real consumer pages and the documentation site.

Reproduced defects and repairs

Defect Reproduction and observed result Repair and regression
Image URL escapes its HTML attribute An ordinary image or Gallery URL containing a quote followed by an attribute-shaped query value creates an extra HTML attribute. An ampersand can also change the browser’s decoded URL. Escape URLs as HTML attributes after validation. check-media-primitives.py parses block and inline image attributes in HTML, Print, and RSS; check-gallery.py checks the quoted Gallery URL. The harmless extra-attribute probe failed before the repair.
Draw.io loses endpoint parameters and mishandles messages An endpoint with an existing query or fragment receives malformed embedding parameters. Null or malformed messages can throw; message handling does not require the configured origin. Build the URL with URL and searchParams; require the active iframe and configured origin; ignore malformed data; send to the exact origin and accept only PNG/SVG image export URLs. New Draw.io unit tests and the site’s editor integration tests exercise these paths.
Page Actions loses the keyboard interaction contract ArrowDown opens the menu before its CSS visibility transition permits focus. Tab can leave the disclosure while it remains open. Make visibility immediate, retain the opacity and movement transitions, and close on focus leaving the entire disclosure without reclaiming focus. Runtime and real-browser regressions cover forward and backward traversal.
Appearance clears a newly reopened dialog’s state Close and immediately reopen the dialog before its queued native close event arrives. The dialog stays visible while aria-expanded becomes false. Ignore an earlier close event while the dialog is open. Real-browser tests cover the race in Chromium, Firefox, and WebKit at desktop and phone widths.

The two taxonomy HTML goldens also needed the already accepted sidebar repair: 33 hidden-leaf markers in each snapshot were removed after reviewing the complete diff. The 52-surface golden gate then passed.

The behavior is recorded in the bilingual architecture and shell contracts. No configuration migration or new dependency is required.

Validation

Local tools were Hugo Extended 0.166.0, Go 1.27.1, Node 26.9.0, Pandoc 3.11, and Chromium 151.0.7922.34 for PDF generation.

Layer Evidence
Theme runtime All 52 JavaScript tests passed after the repairs. Python discovery passed 116 tests; the 90-test migration suite was also run separately.
Theme ownership Every bin/check-*.py checker was exercised, including explicit output-security arguments and packaged EPUB/PDF checks. Configuration schema generation was checked. Changed media, Gallery, output and golden owners were rerun after their repairs. Builds used warning-failure gates where the checker builds valid publishing output.
Documentation integration make check passed with the local theme replacement: source/rendered Markdown, bilingual heading coverage, internal links, alternate-site builds, favicons, output goldens and release-pin contracts.
Browser integration make browser passed 229 tests, including the full sitemap accessibility scan, six responsive widths, EN/ZH, navigation, search, components, code, community regressions and all four visual presets. The additional engine gate passed 6 tests across Chromium, Firefox and WebKit at 390 and 1440 px.
Publication fixtures EPUB: 5 chapters, 31 link targets, no internal-check errors; EPUBCheck 5.3.0 reported zero errors and warnings. PDF: 23 pages, all 5 expected titles, no internal-check errors; rendered pages were inspected.
DDIA sample Local-theme make check-local passed, including 14 translation chapters, 196 figure-layout checks and 38,170 internal references across 57 second-edition pages. Desktop, phone and dark reading views and the four-style menu were sampled.
SILO sample Local-theme make check passed, including 536,561 internal references across 1,552 HTML files. Desktop documentation and phone search results were sampled.

The initial broad run exposed the stale goldens. One standalone security invocation also lacked its required CLI arguments; its corrected invocation passed over 493 fixture output files. A new Print assertion initially omitted Print from the test page’s own output list; correcting that test setup produced a passing HTML/Print/RSS regression.

Performance observations

A strict, minified local production build of the documentation site was inspected. For /docs/customize/config/, the referenced local JavaScript totals 62,192 bytes gzip (about 61 KiB, including Lunr); the two stylesheets total 98,838 bytes gzip (about 97 KiB), excluding fonts, images, search indexes, and third-party service traffic.

The ordinary documentation page omits the large diagram bundles. The Mermaid sample adds a 976,006-byte gzip Mermaid dependency (about 953 KiB) plus its small page runtime. Runtime-isolation and output checkers passed.

Limits and delivery state

The accessibility suite excludes upstream Redoc and Swagger UI DOM under its existing policy. Consumer browser checks sampled key desktop and mobile routes across DDIA and SILO. The repairs were grouped into local theme and documentation commits.

8.20 - Give large tables room to read

Framework and component evidence, measured reading concepts, and a bounded direction for OINK technical tables.
Historical research; see the 1.4.0 decision

Research date: 2026-10-26. This study informed the table-reading design in OINK 1.4.0. The accepted decision and table guide describe the released behavior and supersede the entrance and scope recommendations below.

An explicit Read table action opening a large native dialog is the strongest candidate for further evaluation. It gives desktop tables more room while preserving text size, original table semantics, and a short return path. Inline widening remains sufficient for many tables; the measured package excerpt already fits that mode on desktop. On a 390px viewport, the dialog adds only 16px of width, so horizontal scrolling remains on narrow screens. Five documentation frameworks use native tables and overflow handling by default, while third-party table libraries add data operations alongside additional integration weight.

Evidence separates layout, content, and release state

The public tag snapshot was v1.3.2, with tag ref 68cfbbdc177064e2c28277c09c385d78e5363ffd. Research began at theme HEAD 7bc8658bc1be13ef0ad3050b9d9f6862f8f1f65f and site HEAD 99751179eefada3fa7a91318c792ddac46d7e6bf, with uncommitted changes in both working trees. The short .wide alias tested in this experiment was subsequently shipped in OINK 1.4.0 as documented in the component contract.

The local owners inspected were oink/layouts/_partials/content/table-render.html, table-body.html, assets/scss/td/_content.scss, _table.scss, the preset/font tokens, and the surface coordinator. .wide/.td-table--wide control intrinsic sizing and token wrapping; .full-width reaches the available article canvas. .matrix supplies first-column row headers and bounded two-axis scrolling, with existing sticky header/first-column CSS. That CSS gives each header top:0, without accumulated multirow offsets or a mobile first-column width guard. .fields emits a definition list. Ordinary captions belong inside the table; numbered Book captions belong to the outer figure (Table guide, output contract).

Selected consumer source Bounded sample and purpose
pigsty.cc/content/docs/infra/param.md, NGINX group Four columns × 14 body rows; linked parameter identifiers and descriptions
pgext/content/list/pkg.md, lines 44–69 Six columns × 24 body rows; package/version/repository/category/RPM/DEB comparison
pigsty.cc/content/docs/ref/linux.md, overview Eight columns × 14 body rows; OS/architecture and PG18–PG14 support cells
piglet.run/content/docs/reference/vscode/_index.md Two columns × seven body rows; small-table counterexample

Consumer snapshots were pigsty.cc at efaf7b19b442ddb284106418c78854552d949e9e, pgext at ab87fc7e5707d57f55129d3c45874abcc16fdef8, and piglet.run at 5a1572e6f9110cd5e8ef6e75cd50d9c4b6429f98; each pinned OINK v1.3.2. The separate 616-row extension catalog was left outside this prototype’s scope.

These examples distinguish many columns, many rows, long cells, and complex headers. Wider viewports primarily help the first; sticky orientation helps the second; wrapping helps the third. Multirow and merged headers need explicit associations and offset handling beyond wider layout. The selected prototype tables all have one header row and no merges. GFM pipe-table syntax itself defines a single header row and inline cell content (GFM tables, WAI multilevel headers).

Five frameworks make overflow the common baseline

The survey inspected official documentation and pinned default-theme source across five documentation frameworks. None of the five provides a built-in fullscreen table reader by default. Documentation links point to pages accessed on 2026-10-26; source links pin implementation commits.

Framework snapshot Default table behavior Optional/custom boundary
Material for MkDocs, 0f044dbe, 2026-10-24 Markdown tables; original table wrapped in local horizontal-scroll containers, with unwrapped fallback Sorting uses an opt-in Tablesort 5.3.0 recipe; no built-in table reader, sticky columns, or table copy (Guide, CSS).
Docusaurus Classic 3.10.2, f37f9035, 2026-07-10 MDX/GFM renders tables; Infima 0.2.0-alpha.45 applies display:block; overflow:auto Custom table views are built through MDX/remark/rehype (MDX mapping, Infima CSS).
VitePress 1.6.4, 1fc537b7, 2025-08-05; 2.0.0-alpha.21 snapshot d6d7a970, 2026-10-26 Both snapshots use block tables and horizontal overflow The 2.0 snapshot adds default tabindex="0"; Vue components handle custom behavior (1.6.4 CSS, 2.0 focus plugin).
Astro Starlight 0.42.7 snapshot af9557ea, 2026-10-24 Markdown table styling uses display:block; overflow:auto .not-content supplies a styling boundary; full-view and code-fullscreen features come from community plugins (CSS, directory).
Nextra 4.6.5 snapshot d6e80e1d, 2026-06-23 Official Table components wrap styled HTML with horizontal overflow Literal MDX <table> requires Table or the documented whitelist (Source, HTML boundary).

The inspected code licenses are MIT: Material, Docusaurus, VitePress, Starlight, and Nextra. Docusaurus documentation separately uses CC BY 4.0.

For static Hugo, the directly applicable patterns are semantic HTML, scoped scrolling, build-time focus attributes, and optional progressive enhancement. Material’s mounting code uses RxJS; Classic uses React/MDX, VitePress Vue/Vite, Starlight Astro, and Nextra Next/React.

Richer libraries add data operations and ownership

Current versions matter. DataTables 3.1.4 runs without jQuery, unlike 1.x releases. TanStack Table 9.3.1 uses constructTable, feature selection, and Store reactivity (DataTables v3 dependency boundary, TanStack v9 announcement).

Component Fit and available operations Integration and maintenance boundary
DataTables 3.1.4, released 2026-10-13; MIT, no required core runtime dependency Enhances HTML tables using an internal data model; core sorting/search/paging; optional Buttons, FixedColumns, FixedHeader, Scroller Closest candidate for later systematic table operations. Scrolling can duplicate or move headers; supports complex thead, not tbody spans (Release, package, span limit).
Tabulator 6.7.1, released 2026-10-22; MIT, no required runtime dependency Grid rendering, sorting/filtering, frozen columns, grouped columns, clipboard and virtual rendering HTML importer reads first-body td cells, dropping .matrix row-header th semantics, and does not preserve general caption/scope/headers (Release, package, importer).
TanStack Table core 9.3.1, released 2026-10-12; MIT, @tanstack/store ^0.11.2 Headless sorting/filtering/pinning/selection/spanning logic; vanilla integration is supported Maintainer owns HTML import, rendering, controls, styles, focus, export, and dialog; virtualizer is separate (Metadata, fixed package, vanilla guide).

DataTables’ FixedHeader/FixedColumns are optional extensions. Scroller requires equal-height rows, which conflicts with wrapped technical descriptions. Tabulator emits ARIA grid structures designed around cell navigation. TanStack’s spanning API requires explicit column definitions rather than importing arbitrary HTML merges. None of these packages includes a built-in fullscreen reading dialog (Tabulator’s printFullscreen targets print layout) (Scroller, Tabulator navigation, Print source, TanStack spanning guide).

Copy defaults also differ. Buttons 4.1.2 exports display data with current order/filter rules and span placeholders, without formula escaping by default. Tabulator 6.7.1 joins cell values with tabs/newlines without general quoting or formula neutralization. Tablesort 5.7.1 is a lightweight MIT, dependency-free sorting library that preserves table rows and handles Enter on headers without adding a reader, filter, or export layer (Buttons source, Tabulator Clipboard, Tablesort source).

Compare delivered bytes with their exclusions

Measurements used 14 fixed npm tarballs verified against registry integrity. Publisher-minified files were measured unchanged. Gzip used Python 3.14.8, zlib 1.2.12, gzip.compress(data, compresslevel=9, mtime=0); totals sum separately compressed files.

Measured delivery Minified bytes Gzip-9 bytes
DataTables 3.1.4 core JS + default CSS 153,523 46,181
Above + Buttons 4.1.2, FixedColumns 6.1.1, FixedHeader 5.1.2 JS/CSS 249,015 72,480
Scroller 3.1.1 JS/CSS, additional 13,300 4,389
Tabulator 6.7.1 full UMD JS + default CSS 483,872 107,512
TanStack 9.3.1 selected reader logic, local bundle 49,505 14,248
TanStack 9.3.1 all core exports plus bindings/render helper, local bundle 115,146 30,983
TanStack virtual-core 3.19.7, separate local bundle 32,872 9,745
Tablesort 5.7.1 core + number comparator 3,756 1,763

DataTables core alone is 123,516/42,338 JS bytes and 30,007/3,843 CSS bytes, minified/gzip respectively. Extension totals use the exact Buttons, FixedColumns, FixedHeader, and Scroller packages plus matching -dt CSS. Optional style-adapter JS adds 2,501/1,279 bytes to the four-package total; Scroller’s adapter adds 650/326. Initialization, dialog code, translations, JSZip/pdfmake, and source maps are excluded. Buttons copy resides in its main file, so the compatibility shim is not counted again. Tabulator’s full package includes all built-in modules; Tablesort supplies only sorting.

TanStack measurements come from local esbuild bundles. Node 26.12.0/npm 11.20.0 and esbuild 0.25.11 bundled core 9.3.1 with Store 0.11.2 using --bundle --minify --format=esm --platform=browser --target=es2020 --legal-comments=inline and production NODE_ENV. The selected entry exports constructTable, tableFeatures, sorting/filtering/pinning/spanning features, sorted/filtered row models, storeReactivityBindings, and FlexRender. The all-core entry exports the core namespace plus those two helpers; the virtual entry exports virtual-core separately. Metafiles found no external imports. The 14,248-byte gzip logic sample covers headless state management only, excluding UI, CSS, HTML import, accessibility controls, dialog, copier, and virtualizer (Core package, Store, Virtual).

The concept widens desktops much more than phones

The external prototype used a real sibling documentation-site Hugo build with an external content mount. PGEXT-specific shortcodes became explicit labels/links; parameter fragments resolved to their source URLs; support icons received “Supported” text alternatives. Added captions and .wide were experimental adaptations. Every reading mode reused the same generated table data. The build used the sibling replacement with both workspaces disabled and external destination/cache/resource directories.

The comparison shell used a 230px rail, 40px desktop main gutters, 68ch normal measure, and 1130px available canvas, styled with generated OINK CSS and fonts. A separate generated table-guide reference measured a 770px desktop / 358px mobile viewport.

Package-table scroll viewport Normal measure Inline widening Native dialog Separate page mode
Desktop Paper/Terminal 652.80px 1130px 1358px 1408px
Desktop Slate/Ink 686.38px 1130px 1358px 1408px
Mobile, all four presets 358px 358px 374px 374px

These are local qa.json measurements at 1440×1000 and 390×844, DPR 1; light/dark geometry matched within each preset. Text remained 16px and code 14px throughout. Mobile intrinsic table widths remained about 969–1009px. Desktop inline widening already fits the six-column excerpt; the dialog adds bounded height, persistent controls, and isolation from prose. Its desktop visible table height was 847.20px, versus 897.20px in page mode; mobile dialog heights ranged 711.02–741.20px as controls wrapped.

Inline widening has the lowest context-switching cost. The dialog gains desktop space while retaining a direct return to the article. The separate page gains only another 50px on desktop and no mobile width; its main advantage is reloadability and URL sharing, at the cost of losing article scroll/focus on return. None of these modes scales text or invokes the Fullscreen API.

Chromium 151.0.7922.34, through Playwright 1.62.1, checked 16 preset × color × device combinations, each with three reading concepts plus baseline. The package sample passed original-node identity, unique IDs, caption/header scopes, loaded styles/fonts, title initial focus, Enter open, Escape/Close return, both Tab boundaries, stable toolbar, separated control/table regions, and page-mode reload. No page overflow was recorded; three additional mobile samples and a 320px Terminal/dark overflow probe extended the scope. A separate inspection preserved link targets and selection and restored inline horizontal scroll to 180px. Screenshot review covered 48 concept captures and contact sheets, and a Paper/light/desktop dialog axe scan reported zero violations.

The parameter and version samples’ first columns occupied 59.3% and 58.3% of the 374px mobile reader, motivating an optional mobile width guard. Preset styling remained distinct: Paper’s Plex Sans and restrained framing, Slate’s Inter and rounded controls, Ink’s flat sharp geometry, and Terminal’s mono chrome with Plex Sans prose.

Reproduction uses the external builder, source manifest/hashes, generated reference output, QA/inspection JSON, and screenshot set with Hugo 0.168.0+extended+withdeploy, Go 1.27.3 on macOS ARM64, Node 26.12.0, npm 11.20.0, and Python 3.14.8.

This prototype scoped evaluation to Chromium desktop and touch emulation with single-row headers; Firefox/WebKit, screen-reader testing, forced-colors, 200/400% zoom, merged headers, coordinator integration, and print-while-open belong to implementation acceptance.

A small reader preserves more than a generic grid

The recommended first stage is an explicit Read table action, a native dialog, and one original-node move/restore lifecycle. Hover-only entry is undiscoverable on touch and keyboard; whole-table click competes with selection, links, and scrolling. A visible title/Close control, named scroll region, initial title focus, contained Tab navigation, Escape, and guarded focus/scroll return are core requirements. Reuse OINK’s surface coordination conventions. A near-full dialog is distinct from browser fullscreen, whose standard excludes <dialog> as the request target (APG dialog, Fullscreen Standard).

Retain caption/th/scope/headers and original IDs. Moving the original table avoids clone collisions and divergent state, while inherited styling, outer numbered captions, external ARIA references, and footnotes still need explicit handling. Native tables can contain links and sorting buttons without becoming ARIA grids. Start with single-row sticky headers; leave complex headers scrollable without stickiness until offsets are validated. Comfortable spacing is default; compact mode changes padding while keeping font size. Optional first-column pinning must leave useful mobile reading width (APG table, APG grid, header semantics).

Keep .wide/.td-table--wide layout-only, .full-width bounded by article canvas, .matrix semantics intact, and .fields ineligible. No-JS content remains readable; Print expands static tables, Markdown retains source, and RSS retains its static/summary boundary without leaking reading controls.

If TSV copy is added in the future, it should copy the whole eligible table, including offscreen rows/columns, in author order: links become labels, code text remains, hidden controls/decorative glyphs are excluded, and meaningful icons use explicit text equivalents. It should reject hidden data rows/columns, nested tables, unequal row lengths, multiple header rows, or any DOM rowSpan/colSpan other than 1 (including rowspan="0"), using TAB between cells, LF between rows, normalized in-cell whitespace, and a leading apostrophe for formula-like cells starting with = + - @ (HTML table model, DOM text, Clipboard 2026-06-24 Working Draft, OWASP spreadsheet-injection limits).

A focused native reader leaves data-grid adoption possible later while avoiding a second data model. See the accepted decision for the shipped implementation boundary.

Accepted direction after review

Maintainer review selected explicit {.wide .expand} composition and a direct corner action, revealed on hover/focus and visible on touch, omitting the above-table toolbar, ellipsis menu, and TSV copy. The accepted decision and current contract define the shipped behavior.

9 - Design proposals and PRDs

The canonical bilingual home for OINK PRDs and designs that remain under evaluation.
Non-normative material

A proposal describes behavior that may not exist. The contracts, accepted decisions, implementation, and owning checkers define current behavior. Never use a proposal as a configuration reference.

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

Active proposals

Proposal Current boundary
Backlinks and knowledge graph G1 (static backlinks) is accepted, implemented on the theme’s main branch, and ships with OINK 0.8.0; the local and global graphs (G2/G3) remain draft
Media convergence Partially implemented; the media-result contract and Landing resource metadata shipped, M3 resolved for native-image processing, retirement (M4) open
OINK CLI and the next product stage Independent Go repository and first-stage boundary accepted; local CLI candidate implemented, not publicly released; later theme, migration, adoption, versioning, OpenAPI, and platform stages remain proposals
Visual presets and appearance switching Paper/Slate ship in v1.2.0; Ink/Terminal ship as explicit opt-in experiments awaiting design acceptance; see the accepted decision and dated acceptance record

Component refinement, unified diagram reading and local search refinement ship in 1.4.0 and now live under accepted decisions. Translation comparison ships in 1.5.0 as an accepted decision; its draft is retired.

The table-reading draft is also retired: the accepted decision and component contract define the narrower, .expand behavior released in OINK 1.4.0.

The bulk agent-index proposal was retired after its outputs were released. Architecture defines the accepted behavior. Agent-ready output gives the user steps. The Book publication proposal was retired after BookManifest and the EPUB/PDF tools were released. The accepted behavior is documented in Architecture and Writing a book; dated downstream adoption evidence is recorded in Consumer evidence. Pending consumer adoption does not keep an upstream design proposal active. Git history retains both proposal drafts.

The generated-configuration-schema proposal completed its lifecycle and was retired: Configuration defines the required behavior, the generated configuration schema decision records the accepted rationale, and Git history retains the draft text.

CLI workspaces and adapters

Explicit workspaces and optional adapters remain in the current reduced CLI. The current contract defines the command boundary, and the R1–R8 and A18 record preserves the historical acceptance evidence. The finite maintenance roadmap remains retired from active navigation.

Where a new PRD goes

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

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

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

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

For a large experiment, you may add a dated page under ../research/. Keep temporary logs and generated artifacts outside Hugo content and Git.

Lifecycle

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

Acceptance does not make the PRD a second contract. Move accepted behavior to the owning contract, stable rationale to Decisions, and user steps to the applicable guide, then retire the proposal from active navigation.

Review gate

Before implementation, confirm that the proposal does not duplicate an existing shell, resolver, component family, or data authority. If the design changes during implementation, update this bilingual proposal before changing the code. Acceptance requires the focused theme checker and the real documentation site. It also requires rendered EN/ZH, applicable outputs, accessibility checks, and responsive review.

Read-only Studio candidate

Studio is removed from the current CLI on 2026-10-04. Use oink dev, an ordinary editor, and structured inspect/check reports. The R7 record preserves historical acceptance of the earlier browser implementation.

Reviewed editing

General source editing is removed from the current CLI. Guarded new, move, review records, and baseline plans remain. Old editing plans are rejected. The R8 record remains historical evidence rather than the current command API.

9.1 - Backlinks and knowledge graph

A draft three-stage design to generate backlinks and local or global graph views from ordinary Hugo links.
G1 implemented; G2/G3 remain draft

On 2026-08-27, all G1 open decisions were resolved and G1 (static backlinks) was accepted. The theme’s main branch implements G1, which is included in OINK 0.8.0. The local and global graphs (G2/G3) remain drafts until G1 supplies real-world evidence. Their names and configuration are not public API until acceptance.

Premise

Reverse navigation and a view of connected pages come from the link graph, independently of [[wikilink]] syntax. Hugo already accepts ordinary Markdown links and ref / relref, so OINK can derive a graph from content authors already write, without another parser, Goldmark extension, or authoring syntax.

The first value is backlinks, not visualization. A static inbound-link list is useful without JavaScript and remains readable in print and Markdown, making an interactive graph an optional enhancement to an already complete list.

Goals and non-goals

Goals:

  • derive one language-local link index per build;
  • show deterministic inbound links on a page;
  • optionally show a bounded local neighborhood;
  • optionally publish a whole-site view and a machine-readable graph;
  • preserve ordinary preview when an edited link is stale or incomplete.

Non-goals:

  • introducing [[wikilink]] syntax;
  • indexing external, mailto:, same-page anchor, or self links;
  • executing JavaScript to discover links already present in content;
  • turning a visualization into the only way to navigate;
  • promising perfect extraction from arbitrary shortcode parameters or raw HTML.

Delivery stages

Stage Deliverable Runtime Independent value
G1 Language-local link index and backlink list None Reverse navigation in HTML, Print, and Markdown
G2 Local graph around the current page Existing ECharts plus a small local runtime Spatial view with G1 as the accessible fallback
G3 Global graph page and graph data output Same runtime Whole-site exploration and machine-readable edges

Each stage requires separate acceptance. G1 does not depend on G2. G2 does not require every page to load graph code.

Extraction contract

The proposed index scans source content once per language and records one edge per source/target pair. After removing fenced code and inline code, it extracts ordinary Markdown links and ref / relref, resolves internal pages, and removes fragments for page identity. Self-links are excluded, and repeated references produce only one edge.

The implementation must test at least:

  • duplicate links collapse to one edge;
  • fenced and inline code produce no edge;
  • external, protocol-relative, mail, same-page anchor, and self links are excluded;
  • ref and relref are included;
  • each language produces an independent graph;
  • an unresolved derived edge warns or is reported by the focused checker without making ordinary hugo server unusable.

Raw source scanning has known omissions: it may miss a URL in a custom shortcode parameter or raw <a href>. These omissions must be documented rather than hidden behind a claim of a complete semantic graph.

G1 renders an aside group in the right rail beside the table of contents and taxonomy clouds, placing what points to this page beside what is on this page. The group is expanded by default and shows the first eight entries, with the rest behind a native disclosure so a heavily referenced page cannot occupy the entire rail. The site key params.ui.backlinks is a bare boolean, off by default. A page overrides it with the prefix-free front matter key backlinks, which a section can cascade. Entries sort by stable page path: a language-independent order that naturally groups related paths without a second ordering authority. The group uses ordinary links and is omitted when there are no inbound pages.

G1 silently removes derived edges that it cannot resolve. This is a documented limitation of its role as a local navigation enhancement: site-wide broken-link reports would duplicate existing warnings.

Print and Markdown retain the readable list. RSS omits the list unless feed-level research shows that backlinks improve article feeds without adding unnecessary site navigation.

Interactive graph boundary

G2 uses the locally vendored ECharts graph series, with the current page at the center and its direct inbound and outbound neighbors forming the default depth. A hard node limit prevents unreadable or expensive views. Keyboard focus, text alternatives, reduced motion, forced colors, narrow screens, and print are acceptance requirements rather than later polish.

If JavaScript or ECharts is unavailable, G1 remains complete and visible. Only pages that render a graph load the runtime. The runtime must use the existing feature-bundle key to prevent asset-cache collisions between pages with different features.

Global output

G3 may add a dedicated graph page and an opt-in JSON output. The proposed JSON schema contains a version, language, nodes, and directed edges with stable URLs. It would not expose local file paths or unpublished pages. Generate this output from the same index as G1 and G2 so all three representations remain consistent.

Compatibility and migration

Ordinary Markdown remains unchanged and needs no content migration. Configuration names remain undecided until a prototype proves the minimum required surface. Every interactive or global output is off by default. A static backlink list may be considered separately because it supports local navigation without network access or browser state.

Acceptance criteria

Acceptance requires a focused graph checker, extraction fixtures, and HTML/Print/Markdown goldens. It also requires strict-build negative cases, browser accessibility and responsive tests, and a real bilingual-site build. Measure performance on a representative large site.

Open decisions

All G1 questions are resolved (see the decision log). G2/G3 must resolve these remaining questions:

  1. Does the local graph expose one depth or a tightly capped second depth?
  2. Which page metadata, if any, is useful enough to enter graph JSON?
  3. Is G3 useful enough to justify a new output format before G1 and G2 have production evidence?

Decision log

  • 2026-08-19: Drafted the three-stage design.
  • 2026-08-27: Resolved and accepted G1, scheduled for OINK 0.8.0. G1 is opt-in: the site key params.ui.backlinks is a bare boolean, off by default, and pages override it with backlinks. Shell types do not restrict this policy because it belongs to the site and page. A single stable-page-path sort replaces the section → weight → title chain: one deterministic authority is enough for reverse navigation, while a multi-level sort would introduce a second navigation authority. Unresolvable edges are silently removed, without warnings, as a documented limitation. G2/G3 and graph data output still require production evidence.
  • 2026-08-27: Design review moved the block from the page end to the right rail. Backlinks are page metadata and belong beside the table of contents, while the page end is the reader’s completion zone: share, feedback, provenance, pager, and comments. The rail group limits visible entries to eight, with the rest behind a native disclosure.

9.2 - Media convergence

A draft for the remaining convergence between content images, numbered figures, Landing media, and featured-image selection.
Partially implemented

The theme’s main branch implements M1 (the shared media-result contract) and M2 (Landing resource metadata). M3 is resolved as option 2. Only native Markdown images support processing. The full fig source form remains a container. Its parameter list deliberately excludes command/options. M4 (compatibility retirement) remains open until consumers are inventoried. The sections below retain the original design record.

Current baseline

The content image hook, numbered fig, cards, and galleries resolve local page resources, section resources, global assets, static files, and explicit remote URLs through content/image-resolve.html. Raster resources can supply intrinsic dimensions and processed derivatives. data-td-image-zoom marks HTML Zoom eligibility, and the build-time detector checks only this theme-emitted marker.

Standalone Markdown images can combine a caption or Book numbering with processing and a link. Numbered image figures share td-figure and td-book-figure semantics. Landing media uses the shared URL trust policy, while featured images deliberately use a ranking resolver because they select a representative image rather than render one explicit source.

Remaining problem

The shared safety boundary is stronger than the shared media model. Landing media does not obtain the same page-resource metadata and processing result as body images. Featured-image selection and explicit image resolution return different result shapes, some compatibility class names remain in markup, and Book’s full fig form cannot express every processing option that the native image hook supports.

The design question is therefore no longer “replace seven image entry points,” but whether the remaining surfaces can share a small result contract without erasing their different semantics.

Goals and non-goals

Goals:

  • define one normalized media-result shape for URL, source URL, dimensions, alternative text, attribution, processability, and external status;
  • let explicit content images, Landing media, and representative images reuse that shape where their source semantics overlap;
  • keep figure markup and Zoom eligibility single-owned;
  • decide whether the full fig form needs processing or whether authors should use the native image form for processed numbered images;
  • retire compatibility markup only after consumer evidence and a release note.

Non-goals:

  • adding a third-party lightbox or remote image service;
  • changing image Zoom from opt-in to site policy by accident;
  • giving galleries a new caption, sequence, or carousel model;
  • merging non-image Book targets such as tables, equations, and examples into an image-only base class;
  • making featured-image ranking identical to explicit image resolution.

Proposed phases

M1 — Result contract

Document the fields that the content and representative-image resolvers return, then extract their shared fields into one internal media-result contract. Source ranking stays in the featured resolver and source resolution in the content resolver. This internal refactor must preserve output bytes.

M2 — Landing resource metadata

Allow Landing items to resolve eligible local resources through the media contract, gaining intrinsic dimensions and the shared URL/security decision. Explicit width and height in Landing data retain precedence. Remote and static sources remain valid without claiming metadata for a processable resource.

M3 — Full figure capability decision

Choose one of two answers:

  1. add processing arguments to the full fig source form and normalize them through the same processing helper; or
  2. keep processing exclusively on native Markdown images and document full fig as the container for arbitrary numbered block content.

No implementation should leave both options half-supported. In both forms, Markdown/LLMS must consistently link to the documented source or derivative.

M4 — Compatibility retirement

Before removing old image-element classes or attributes, inventory downstream CSS and JavaScript. If a compatibility name is still used, retain it for a documented release window. Alternatively, migrate the owning site in the same release.

Safety, output, and accessibility

  • Image URLs keep the shared scheme and remote-host policy.
  • Missing required alternative text warns and renders a decorative fallback only where the current contract permits it.
  • Width and height never claim metadata that an SVG, static file, or remote source did not provide.
  • Linked images are not Zoom targets; the runtime preserves dialog focus, keyboard close, reduced motion, and narrow-screen containment.
  • Print, Markdown, RSS, and LLMS strip interaction markers while retaining the intended image, caption, attribution, number, and link.

Acceptance criteria

For each phase, collect byte-level HTML and Markdown evidence. Run content and Landing resolver tests, URL/security checks, image-processing tests, and Book target checks. Run gallery/Zoom browser tests and real-site EN/ZH narrow-screen review. Acceptance requires an explicit M3 capability choice.

Open decisions

  1. Is one shared result struct enough, or would a common lower-level URL/resource record keep resolver ownership clearer?
  2. Should Landing consume resource attribution, or only dimensions and URL?
  3. Does full fig processing solve a real consumer need now that native images support numbering, captions, links, and processing together?
  4. Which emitted compatibility names are still used by real consumers?

9.3 - OINK CLI and the next product stage

The accepted independent CLI boundary and local first-stage scope, with later adoption, theme, migration, and content-model work still proposed.
Local first-stage candidate; later roadmap remains draft

The independent Go repository pgsty/oink-cli and first-stage development were authorized on 2026-09-29. Its six commands now have a local 0.1.0-dev implementation, with final local acceptance recorded separately. Current behavior belongs to the CLI decision and result contract and CLI introduction. Theme 1.2, its tooling descriptor, Docsy migration, version lifecycle, OpenAPI, MCP, and Studio remain proposals.

Record Value
Status Repository choice and first-stage scope accepted. Local candidate implemented and validated. Later roadmap remains draft
Owner OINK maintainers
Date 2026-09-29
Scope OINK theme, independent CLI, existing Starter, and documentation site
Affected contracts Architecture, configuration/diagnostics, outputs, migration, and later version navigation/API content
Source snapshot Theme HEAD 3a18234, documentation HEAD 85f16bf, Starter HEAD 137843b, plus the explicitly identified local work below

Recommendation

Create a separate oink-cli repository, publish one executable named oink, and keep OINK as the single product identity. The theme renders content. The CLI helps users initialize, inspect, validate, upgrade, and eventually migrate their sites. The documentation site continues to own public guides, bilingual design records, and integration acceptance.

The CLI contract owns first-stage behavior, while the dated acceptance record lists executed checks and remaining limits. This roadmap stays active for its later stages and adoption targets.

The first release should improve the path from an existing repository to a reliable publication. Its four main workflows are doctor, check, init, and upgrade. dev and build may provide small, transparent Hugo shortcuts. A supported Docsy migration path follows evidence from actual input repositories. Version lifecycle and OpenAPI generation come after that first usable release, with one major content-model project active at a time.

Keep the theme usable without the CLI. Commit or otherwise deliver generated Hugo inputs. After you remove the CLI, ordinary Hugo must still be able to build the site. Regenerating those inputs remains a separate operation.

Product position and target user

Recommended public description:

OINK is a local-first documentation toolkit built on Hugo, publishing engineering knowledge for readers and agents.

Retain “Hugo theme” in installation and discovery pages because it describes what users install, while “knowledge compiler” describes the internal architecture. A new name should keep the current Markdown/Hugo workflow clear.

Prioritize Git-oriented maintainers of open-source infrastructure, developer tools, and multilingual technical documentation. They need to get a site working, diagnose failures, upgrade safely, and move content without losing URLs or meaning.

For the first stage, non-goals include a visual CMS, hosted accounts, a deployment control plane, a package marketplace, an LLM runtime, a semantic-search service, and a new rendering engine. Books, blogs, and landing pages remain supported, but their feature catalogs do not drive this roadmap.

Evidence and changes to the research recommendation

This proposal considers the supplied strategy report and checks it against the local implementation, bilingual Design section, Starter, and current primary documentation.

Observation Product consequence
OINK already has a public Starter, generated configuration schemas, migration scripts, publication tools, and focused theme checkers Provide selected workflows as product features. Do not create a second implementation of every tool
The front-matter schema deliberately omits type constraints Strict checks must follow the owning resolvers and actual Hugo output
Existing version support includes a cross-site menu, archive banners, and optional path concatenation Focus on lifecycle and reliable page correspondence
Current version documentation explicitly uses independent Hugo builds Preserve that model initially. Do not silently add a multi-version renderer to one build
OpenAPI widgets become specification links outside HTML and have documented accessibility exclusions Static, accessible endpoint content is a concrete future improvement
Backlinks are implemented. G2/G3 remain draft Graph visualization remains a draft proposal
bin/update-consumers.py exists in this working tree as local maintenance tooling Its release-resolution and preservation rules serve as design input for oink upgrade

The supplied report emphasizes adoption and an optional tools layer. Four changes make its recommendations implementable:

  1. Put safe upgrades alongside initialization and diagnosis. Existing users have an immediate, testable maintenance need.
  2. Separate maintainer regression checkers from consumer checks. A synthetic-fixture checker is not automatically a general-purpose site validator.
  3. Treat migrations as supported input profiles with explicit boundaries rather than complete Docsy or arbitrary MDX conversion.
  4. Replace the simultaneous versioning/OpenAPI/graph/platform program with sequential decisions.

Existing tools illustrate the workflow tradeoffs. Mintlify’s CLI exposes preview, validation, and link checking. Nimbus combines scaffolding and agent-readable output while remaining pre-1.0. Docusaurus makes version snapshots explicit and warns about their maintenance/build cost. Copying Nimbus’s full source-owned UI model would move upgrade work to OINK consumers. Use that pattern for small generated recipes. Keep the upgradable theme module.

Why a separate repository

Option Benefit Cost Decision
Extend Python scripts under theme bin/ Fastest small maintenance improvements. Tests accompany the change Difficult installation and distribution. No unified public command contract Retain for internal and historical tooling
Put cmd/oink in the theme’s root Go module One checkout and atomic source edits Mixes a Hugo asset module with application dependencies, binary releases, and consumer support Do not choose for the public CLI
Use an isolated Go submodule in the theme repository Atomic repository changes without sharing Go dependencies Separate module tags and releases still need management. Code can more easily depend on unpublished theme internals Viable fallback for a prototype with a fixed time limit. Not the preferred product repository
Create pgsty/oink-cli Clear executable boundary, independent releases, no need for users to clone theme internals Requires explicit compatibility and cross-repository acceptance Accepted. Local Go repository created

This decision assigns release and maintenance responsibilities rather than claiming that a monorepo is technically impossible. A nested module can isolate dependencies, and separate repositories still require coordination: a renderer change may need two pull requests, paired contracts, and a compatibility test. OINK already operates a theme/site/Starter split, so that cost is acceptable if the public boundary stays small.

Theme and CLI releases must not share a forced version number. A proposed oink CLI 0.1.x should work with a tested OINK 1.1.0 baseline and the next supported theme release. Declare compatibility per capability. Report unsupported functionality. Do not assume that every schema from the newest theme is valid for every older site.

Do not create separate repositories for the linter, migration engine, OpenAPI generator, or a shared SDK now. They can begin as internal CLI packages. The binary can be built in Go without importing Hugo’s internal Go packages or making the theme module depend on the CLI.

Responsibility map

Surface Owner Boundary
Layouts, components, style, navigation, search, accessibility, output semantics pgsty/oink Executes inside Hugo and the static site
Theme defaults, owning resolvers, generated schemas, output schemas pgsty/oink Authoritative theme behavior and its projections
Theme implementation checks and narrow invalid-input fixtures pgsty/oink Remain maintainer tools, even if implemented in Python or JavaScript
Environment diagnosis, consumer checks, initialization, upgrade; later migration transformations pgsty/oink-cli Initial commands implemented locally; migration remains proposed
OpenAPI parsing and generated source, later version snapshot orchestration Proposed later pgsty/oink-cli capabilities Produces ordinary Hugo inputs; does not own final rendering
Small official site skeleton and language profiles pgsty/oink-starter Single source for CLI initialization. Pinned snapshots can be embedded in CLI releases
Guides, examples, PRDs, accepted rationale, EN/ZH integration/browser review pgsty/oink.pgsty.com Continues as the canonical public documentation and regression site
Hosting credentials, account setup, deployment authorization Consumer workflow Existing CI/provider tools. The first CLI release does not deploy
                          optional oink CLI
                  init / doctor / check / upgrade
                      later migrate / generate
                               |
                               v
              user-owned Markdown + Hugo config + data
                               |
                     Hugo Extended + OINK theme
                               |
               HTML / Print / Markdown / search / indexes
                               |
                  readers / agents / optional adapters

The CLI reads Hugo’s effective configuration, the resolved theme’s published contract artifacts, and rendered outputs. It must not guess the final page tree from filenames or maintain a second navigation resolver. Hugo config exposes effective configuration. Module inspection must also account for replacements, workspaces, and vendoring.

Next theme release: proposed OINK 1.2

This section remains draft. The local CLI candidate works against published OINK v1.1.0. The first-stage CLI decision neither accepts nor requires a 1.2 release or a new tooling descriptor.

Set an adoption objective for this release: a site can explain its configuration and output capabilities to tools, and upgrade without adopting a new authoring model. The release should be small enough to ship independently of the broader roadmap.

Priority Requirement Acceptance
P0 Package a small, versioned tooling descriptor beside existing schemas, describing available schema/output contracts and supported toolchain boundaries Check the descriptor against its owning implementation. The CLI can inspect it from the resolved module. No extra per-page output or runtime request
P0 Make selected high-value configuration diagnostics actionable: parameter, invalid value, expected form, fallback, and owning guide Cover actual onboarding failures such as Goldmark/output/language configuration. Retain ordinary preview warnings and strict publication failure
P0 Preserve one navigation and Markdown authority across reader and machine outputs Existing output and navigation checks continue to cover language, ordering, subpath, and opt-in behavior. No duplicate CLI renderer
P0 Release with a tested Starter snapshot and a reviewed downstream adoption record Validate published module resolution separately from sibling replacement builds. Record consumer pins and deployments independently
P1 Add stable identifiers to the small set of diagnostics consumed by tooling, if the prototype shows they are necessary A focused owning checker verifies each identifier. The CLI never depends on parsing all human warning prose

The descriptor contains release metadata without becoming a configuration authority. Configuration schemas remain generated from current authorities, whose resolver/checker continues to own optional shape validation. A generic renamed-key registry would conflict with the current diagnostic decision. Migration transformations therefore belong to explicit CLI profiles rather than a permanent compatibility path in templates.

No new visual component family is required for 1.2. Correctness, accessibility, and already-demonstrated regressions can still justify changes. Existing media work keeps its own acceptance scope. This roadmap does not require every draft to be complete before release.

First CLI release: proposed 0.1

The commands below are implemented in the local 0.1.0-dev candidate. Their current flags, result semantics, and limits are defined by the CLI contract and CLI introduction.

Command User outcome First-release boundary
oink doctor Understand why the site cannot run or why its environment differs from CI Inspect Hugo Extended/version, module pin and effective source, Starter/toolchain requirements, essential configuration, and enabled outputs. No repair by default
oink check Know whether a publication build and its local references are valid One strict build into isolated output, then check local links/anchors/assets and enabled machine outputs. Report coverage and unsupported checks
oink init my-docs Start a small, neutral site that can be maintained without the CLI Generate from a pinned Starter snapshot into a new/empty target. Select the supported language profile and explicit theme pin
oink upgrade --to <tag> See the exact changes needed for a theme upgrade Preview first. --write applies a reviewed scope after validation. Protect unrelated module dependencies, user changes, and vendored output
oink dev / oink build Use a memorable entry point without learning a second build system Thin Hugo invocations with visible effective arguments. build uses publication strictness. Direct Hugo remains fully supported

check is the single quality entry point. Avoid separate overlapping lint, validate, audit, and check products in 0.1. Later --scope options can separate source hints from rendered-output validation when users need the distinction.

Diagnosis and quality scope

Start with failures that users can act on and that checks can identify reliably: wrong toolchain, unresolved theme, malformed required configuration, missing local link targets/anchors/assets, and inconsistent enabled output references. Resolve routing and anchor truth from Hugo’s output, including language and base-path handling. Do not label a valid custom front-matter key as invalid merely because an editor schema does not list it.

Disabled optional outputs are not missing-output errors. The local candidate does not check translation completeness. Any future completeness rule must use the site’s declared languages and coverage policies. Duplicate titles, orphan pages, missing descriptions, prose style, and freshness remain later optional observations after real false-positive review. Browser accessibility and interaction checks remain in the site Playwright/axe suite.

The local candidate freezes oink.result/v1. Structured diagnostics have stable rule IDs, severity, known locations, explanations, actions, and explicit coverage. JSON stdout contains only the result. Logs go to stderr. No command waits for input. Exit meanings are 0 for completed work with no blocking findings, 1 for policy findings, and 2 for required incomplete work. Required unsupported checks cannot succeed. The result contract owns the detailed fields. Build-derived findings never receive invented line numbers.

Keep raw Hugo errors available as subprocess evidence. A future SARIF export can project from the same result without changing rule semantics.

Upgrade and file preservation

The existing consumer-upgrade script provides local precedents: distinguish declared pin from resolved version, disable both workspace mechanisms for release verification, recognize module replacements, and inspect _vendor. Port those behaviors with focused tests inside the standalone Go binary.

For 0.1, upgrade one explicitly selected site. Multi-site fleet discovery stays with the maintainer script until a consumer need is demonstrated. A normal check may examine an intentional local theme replacement. check --release must verify the declared published release without those replacements. It should report a conflicting go.mod replacement rather than edit it away.

Preview the proposed touched files and verify the prospective upgrade before applying it. Back up only those files, refuse changes to files that changed since the preview, and preserve unrelated dirty work. A failed operation must describe what was and was not applied, with a recovery path that does not overwrite subsequent edits. A dirty repository is not a reason to block read-only diagnosis. Refreshing vendor content requires a separate explicit action.

Do not commit, push, deploy, alter global agent settings, or install system packages as side effects of initialization or repair. Initialization creates the requested named directory. Changes to existing files default to a preview.

Distribution and offline behavior

The local candidate currently provides a tested source/Make installation path and archive preparation on macOS arm64, with other archive targets cross-compiled. A published Homebrew formula and public download/tag installation remain future distribution work.

Use a Go executable with release archives/checksums and a Homebrew installation path. Initially qualify macOS and Linux on tested architectures. Mark other targets experimental until you validate their filesystem and process behavior. The installed CLI itself needs no installed Go toolchain, Python, Node, or account. Hugo remains an external renderer. Initial module resolution still needs the site’s documented Git/Go/Hugo toolchain.

Embed or ship an exact, licensed Starter snapshot for deterministic initialization. Do not fetch a moving main branch on every invocation, and do not maintain handwritten CLI copies of Starter configuration. Check embedded/template drift during CLI release.

Distinguish a cold installation from offline operation. Downloading Hugo, the theme, or an uncached template requires connectivity unless supplied locally. Once dependencies are present, local diagnosis/check/build paths must work without external services. On a cache miss, an offline request must fail clearly without fetching silently. External URL checking, remote specifications, and other network actions are separate opt-ins. No default telemetry or background update check is required.

Migration: the first expansion

Start with a documented Docsy input profile selected from actual candidate sites, reusing the current migration fixtures and report model as evidence. Validate configuration, navigation, assets, languages, and routes as well as Markdown syntax.

Proposed workflow: oink migrate --from docsy --source <site> --output <new-site>. Assess the migration before writing. Apply it only with an explicit flag and a separate destination. Every source item receives one primary status: unchanged-compatible, transformed, manual-review, or unsupported. Counts must reconcile, with reasons and source locations. Custom templates and dynamic behavior remain visible manual work.

Acceptance means source preservation, idempotent supported transforms, no edits inside literal code examples, valid local references, and an explicit old-to-new route report. Prefer unchanged URLs. URL changes require a redirect plan for the hosting target.

Arbitrary JSX, imports, and embedded React/Vue are programs. Do not execute untrusted source to infer their meaning or silently drop unsupported constructs. Start a second framework only after the first profile is reused successfully without maintainer rescue. Full MDX migration is a later product investment.

Next content capability: version lifecycle

After the first CLI is useful, version lifecycle is the default next candidate because it extends OINK’s existing independent-build model. Move OpenAPI ahead only if real API users provide the stronger repeated need. Do not implement both foundations simultaneously with one primary maintainer.

Theme responsibilities: consistent version identity in the reader surface, reliable page switching, archive status, and correctly scoped search/machine outputs. CLI responsibilities: inspect/list versions, prepare a snapshot, validate page correspondence, and change declared lifecycle state. Use oink --version for the executable. A future oink docs version ... namespace would distinguish documentation versions.

Prefer a small version manifest with version label, source reference, base URL, status, and default selection. Keep independent per-version builds and existing external archives. CLI-managed manifests may produce checked-in Hugo configuration; in that mode, authors edit the manifest and configuration becomes a checked projection. Existing manually managed params.versions remains supported. The initial prototype must settle this projection before freezing its format.

Page correspondence needs a logical page key scoped by documentation family, language, and version. Reuse a suitable existing translationKey or explicit stable key before inventing universal UUIDs. You should disclose missing peers and link them to a defined version/section landing page. You should not fabricate an equivalent page or concatenate an unchecked URL. Route aliases handle moves separately from page identity.

Distinct historical content should ordinarily keep its own canonical URL. Do not point every old page at the newest version. Language alternates must refer to genuine translated peers in the same version. Default search and agent bundles stay inside the selected language/version. A cross-version collection, if later needed, is explicit. Archiving preserves the source and records how the built artifact is retained. It does not delete the source or silently redeploy an immutable archive.

NAVJSON v1 currently has closed object schemas. Adding version or identity fields therefore requires an explicit new schema/output contract or a separate artifact, not a supposedly harmless addition to v1. No change to current page identity is justified merely to reserve space for a future graph.

Following capability: static OpenAPI reference

The first OpenAPI product should be a read-only static reference generator. The CLI parses a local specification and supported local references, emits ordinary Markdown/Hugo data, and records source provenance. The theme supplies accessible semantic presentation and the existing output pipeline. Ordinary Hugo then builds HTML, Print, Markdown, search, and agent indexes from those generated pages.

Start with operations, parameters, request/response bodies, and linked schema descriptions. After a parser prototype, explicitly declare supported OpenAPI versions and constructs. Unsupported constructs cannot disappear silently. Scope operation identity to the API/specification. If operationId is missing, the generator can derive a method/path key and warn about identity changes. Reused operationId values across different APIs must not collide.

Keep human-authored guides separate from generated facts. Generation must be deterministic, record source hashes and generator version, detect stale output, and refuse to overwrite unexpected human changes. Check generated source into the site, or supply it as a versioned build input, so rendering itself remains CLI-independent. Resolve remote references in an explicit preparation step. Normal generation must not follow arbitrary external URLs.

Acceptance requires a real user specification in addition to a toy example, complete accounting of supported operations, cyclic-reference handling, stable routes, semantic content in all selected outputs, and accessibility checks with no inherited Swagger/Redoc exclusion for the new static renderer. Measure a representative large specification before promising a throughput target.

Keep existing Swagger/Redoc integrations compatible. Interactive requests, credential handling, SDK generation, mock servers, and an API testing platform are outside this first compiler increment.

Architecture and compatibility rules

Keep CLI internals small: command handling, Hugo/process integration, diagnostics, template loading, and bounded file changes. Add migration and OpenAPI packages when their stages begin. This is a suggested decomposition, not a plugin ABI or public SDK.

Three boundaries need versioning: the CLI’s machine result format, the theme’s public schema/output contracts, and each supported migration/generation input profile. Prefer capability checks over a single “requires newest OINK” rule. A newer unsupported schema must produce a useful compatibility diagnosis.

The CLI cannot import a sibling theme’s private Python modules, depend on a local checkout layout, or download executable checks at runtime. Port selected consumer operations and test their behavior. Keep template-internal checkers in the theme, and make future changes to exposed consumer rules update their owning contract. Keep existing scripts available during the transition. Remove duplication only after the replacement covers supported cases.

No CLI configuration file is required initially. Hugo retains rendering configuration. If repeated usage later justifies a tool-policy file, it may hold ignored paths, rule severity, or a reviewed baseline, but must not mirror params.ui, navigation, languages, or module pins. A reviewed lint baseline cannot suppress a failed Hugo build, an unreadable input, or an unsupported required check.

Roadmap and staffing assumption

Stages 0 and 1 have a local first-stage candidate, with validation details in the acceptance record. The 8–12 week first-stage planning envelope below assumes roughly one full-time implementation owner plus part-time documentation/review help. Toolchain qualification, recruitment, and bilingual review take time; reduce scope before adding parallel work.

Stage Timing from approval Deliverable Exit evidence
0: establish the boundary Weeks 1–2 Accept repository choice; collect failure examples; define result format and supported baseline; prototype read-only doctor/check against current 1.1.0 Starter plus at least three varied real repositories; failures and coverage omissions recorded
1: complete the daily workflow Weeks 3–6 Doctor/check, pinned init, thin dev/build; prospective single-site upgrade and file-preservation tests New users can diagnose a seeded failure; ordinary Hugo still builds generated sites; no unexplained source changes
2: release a bounded product Weeks 7–12 Proposed theme 1.2 + CLI 0.1; compatibility record; docs; qualified installation; limited Docsy migration assessment/pilot First-run study and repeat upgrade use; migration limitations are explicit; published pins and consumer adoption checked separately
3: validate migration and one content model Months 4–6 Harden the first migrator; choose version lifecycle or OpenAPI based on users; propose theme 1.3 / CLI 0.2 as needed At least two real repositories use the chosen workflow; accepted contract precedes compatibility promises
4: earn expansion After month 6 The other content capability, then optional recipes/provenance or agent transport where justified Repeated use and maintenance capacity

If stage 2 overruns, remove migration writing from that release and keep its assessment report. Do not cut upgrade preservation, truthful diagnostics, or independence from the CLI. If no independent team wants the migration profile, stop expanding framework coverage and investigate onboarding/positioning instead.

Freshness/ownership is a later optional quality feature, initially a report whose findings users actually act on. A modification date must never be presented as verification. Ship a handful of useful official page recipes before a registry. Graph G2/G3, MCP, analytics adapters, executable examples, Studio, and managed services each need a specific user problem and capacity decision; this roadmap assigns them no delivery dates. Existing static agent outputs make MCP less urgent than adoption.

Acceptance and product measures

Area Initial target or required property
First successful use With prerequisites already installed, at least 4 of 5 unfamiliar target users reach local preview and a passing strict check within 15 minutes without maintainer intervention; Record cold installation separately
Maintenance value At least three real sites use diagnosis/checks and repeat a supported upgrade; Every failure has an actionable report
Diagnostic precision Triage all blocking findings in the pilot; aim for less than 5% false positives in an explicitly counted labeled sample
Integrity Zero silent content loss; every migration input is accounted for; repeat transforms have no diff; user edits and unrelated dependencies survive
Independence Initialized/generated sites build through ordinary Hugo with provisioned dependencies; optional CLI and output features remain optional
Offline behavior Run the qualified local workflow with outbound access denied after provisioning; record cache misses and explicitly networked features separately
Compatibility Current tested theme baseline and candidate release, pinned site regression toolchain, root/subpath, and EN/ZH cases
Adoption Seek five independent pilot teams within the first stage, and track which reach production and continue using the result at 30/90 days

Use independently maintained production sites as the main adoption measure, verified through public references or voluntary user confirmation. A stable documentation site should not stop counting merely because it has no commit in 60 days. Track theme upgrade recency separately from retention. Stars, download counts, internal consumer count, and agent-generated volume serve as supporting signals.

Track time to first local success, time to production, upgrade effort, and manual migration effort separately. Do not add default telemetry to obtain these measures.

Implementation ownership and validation

Change Owning validation
Tooling descriptor and schema compatibility A focused theme descriptor check plus generate-config-schema.py --check and relevant parameter checks
Diagnostics exposed to consumers Owning resolver/checker cases; CLI diagnostic result/exit-code tests
Existing output behavior check-agent-indexes.py, output/security/navigation checks appropriate to the changed surface
Init and upgrade CLI tests against pinned Starter snapshots and repositories with replacements, vendor content, unrelated dependencies, and dirty target files
Migration Ported/extended transform cases, source-preservation and repeat-run checks; reviewed real-site route/content evidence
Future version/API presentation Theme output checks plus bilingual documentation-site integration, browser, accessibility, responsive, and visual review

Run the smallest owning check first. Public behavior changes still require implementation, checker, and both language contracts in one coordinated delivery. Use the sibling site’s make check, make browser, and make dev workflow for actual integration and visual acceptance.

For a release, separately record local checks, commits, tags, published module/binary resolution, consumer pins, and deployment. Theme release adoption continues through the maintained consumer inventory procedure. Use a coordinated issue/checklist to connect the repositories.

Open decisions and stop conditions

Repository selection and first-stage implementation are settled locally. Remaining release decisions include qualified platforms, the public distribution channel, compatibility claims justified by executed evidence, and independent pilot recruitment.

Result and exit semantics are frozen for the local candidate in the CLI contract. The minimal theme descriptor and stable theme warning identifiers remain separate proposals. Before a versioning beta, settle manifest projections, archive retention, and page correspondence. Before an OpenAPI beta, settle the supported spec subset and generated-source ownership.

Reconsider the separate CLI investment if pilots only need a tiny maintenance script, if rules must repeatedly duplicate template semantics, or if maintaining distribution consumes more effort than the measured user benefit. Keep successful standalone scripts in that case. If evidence changes, reorder versioning and OpenAPI. Do not expand the total concurrent scope.

Decision log and sources

Date Record
2026-09-29 Draft created from the supplied strategy research and local source review. Recommends a separate optional CLI, a small adoption release, bounded migrations, and sequential content capabilities.
2026-09-29 Subsequent user authorization accepted the independent Go repository and first-stage development. A local 0.1.0-dev candidate implements doctor/check/init/upgrade/dev/build. Stable behavior moved to the CLI decision and usage guide. Local acceptance passed for CLI commit e623d93.

Local authorities consulted: Architecture, generated schema decision, migration boundary, version behavior, OpenAPI limits, and graph proposal status. The source inspection also covered theme bin/, schema/nav.v1.schema.json, the existing Starter, and documentation-site build/check commands.

External primary sources were checked on 2026-09-29: the linked Mintlify command reference, Nimbus repository, Docusaurus versioning guide, and Hugo config/module documentation.

9.4 - OINK CLI maintenance roadmap

Historical R1–R8 requirements for documentation maintenance and Oink Studio, distinct from acceptance evidence and the current reduced CLI contract.
Implemented requirements record

This dated requirements record preserves the original R1–R8 planning scope and anchors. Current CLI behavior belongs to the CLI contract and CLI introduction, and historical acceptance evidence belongs to the 2026-10-04 supplement. Conditional extensions E1–E4 remain inactive.

The proposed product should complete documentation maintenance before adding a local visual interface. It should help maintainers check changes, understand their effects, review safe modifications, and publish the exact artifact that passed checks. Studio should expose those same capabilities.

Record Value
Status Implemented locally for R1–R8 and A18
Owner OINK maintainers
Date 2026-10-03
Baseline Local CLI 0.1.0-dev, commit e623d93. Hugo Extended 0.166.0 and Go 1.27.1 on macOS arm64
Completion scope R1–R8 and the acceptance cases below. Conditional extensions have separate entry criteria
Affected surfaces CLI command/result contract, Starter projection, consumer CI, translation policy, maintenance operations, local Studio, EN/ZH guides
Schedule assumption One full-time developer with scheduled documentation and review support

Background and evidence

The original CLI roadmap accepted an independent Go executable and narrowed the first implementation to doctor, check, init, single-site upgrade, dev, and build. This proposal adds a maintenance program with a defined scope. Docsy migration, version lifecycle, OpenAPI generation, and theme 1.2 retain their own scopes.

The 2026-10-03 local audit reran the Go suite and actual Hugo integration tests. A bilingual initialized site passed checks over 223 files and 4,461 references. The PIG consumer site passed over 1,392 files and 64,440 references, with 858 source files and its Git state unchanged.

The audit also reproduced four limits. A missing rendered link failed check while build succeeded. Ordinary HTML references outside the configured base path were marked untested. doctor --release accepted a Starter still using https://example.org/. Both embedded deployment workflows called Hugo without the CLI’s additional checks. Translation completeness and readable upgrade diffs were absent. These findings define the first changes.

Product goal and users

Prioritize maintainers of multilingual engineering documentation and small teams maintaining several Hugo sites. Their recurring jobs are reviewing translations, preventing broken publications, updating dependencies, and reorganizing content without losing references or public URLs.

The product succeeds when an ordinary consumer repository can use one quality entry point locally and in CI. Maintainers must be able to inspect affected pages and apply reviewed changes while preserving unrelated work. CLI, Studio, and Agent callers must receive the same findings and change plans.

Feature selection

Capability from the supplied design Decision Delivery
Links, anchors, attachments and machine outputs Strengthen existing checks and explain uncovered cases R1–R3
Environment diagnosis, preview and strict builds Complete release diagnosis and add opt-in verified builds R1, R3
Translation completeness and protected structure Build as a primary product capability R2
Initialization and CI configuration Extend the fixed Starter and manage reviewed CI changes R3–R4
Native content rules and project style Implement a small deterministic core. Optional general tools R2, R6
New content, snippets and editor setup Implement ordinary Hugo inputs with overwrite protection R4
Safe upgrades and migration preflight Add diffs and candidate comparisons. Framework migration remains separate R4
Page moves, renaming and impact analysis Implement after page relationships and change plans are dependable R5
Issue panels and translation comparison Build a read-only local Studio first R7
Multiple sites Add an explicit site registry over the same single-site engine R6
EPUB, PDF and offline packaging Conditional adapter to distributed publication tools E1
Executable documentation examples Conditional, explicit execution profiles E2
Agent inspection, impact and context Implement deterministic local operations R5
AI translation and semantic review Conditional proposals after deterministic maintenance works E4
Sources, evidence and knowledge dependencies Limit this program to build/review provenance and observed page relationships Wider knowledge management deferred
Rich editing, live collaboration and native desktop apps Deliver safe Markdown editing only. Defer the broader platform R8. Remainder deferred

Scope and non-goals

R1–R8 define this PRD’s finite completion scope. Each stage can deliver value and be accepted separately. Suggested CLI versions 0.2, 0.3, and 0.4 identify release candidates. They do not require public tags or theme versions.

The program does not include a renderer, universal migration engine, hosting account manager, deployment API, built-in LLM, vector database, remote editor, real-time collaboration, native desktop shell, or full WYSIWYG editor. Existing provider workflows perform deployment. Publication permissions and credentials remain consumer-owned.

Shared project facts and check policy

This scope is accepted locally. The original requirements below are retained as proposal history. Current behavior and flags belong to the CLI contract.

Extend the existing isolated Hugo analysis. Do not introduce a second configuration parser or navigation authority. Proposed internal facts include page identity, language, publication state, actual output URLs, known source files, translation relationships, and observed rendered references.

Use Hugo’s public Page.Translations and Page.OutputFormats for relationships and outputs. Page.File can provide provenance, but some pages have no backing file. Such findings must retain an output location and unknown source state. Any temporary probe must leave ordinary published outputs unchanged after its removal.

Use oink.yaml only for check selection, severity, translation policy, reviewed exclusions, and tool/workflow options. Hugo continues to own languages, titles, menus, URLs, and site configuration. Module files own theme versions. Initially provide check links, check translations, and check style over one shared analysis. Keep --json. --format json may be an additive alias.

Report blocking errors, warnings, and suggestions through the existing error, warning, and info severities. Unsupported required tools or input shapes remain exit 2. Policy cannot turn failed builds, unreadable inputs, or incomplete required checks into success. Source locations need reliable mapping. Otherwise report the actual output and pointer.

Translation maintenance

This scope is accepted locally. The original requirements below are retained as proposal history. Current behavior and flags belong to the CLI contract.

Support filename languages, language-specific content directories, and translationKey relationships as resolved by Hugo. Coverage policies select required languages for an explicit content scope. Disabled languages and intentional localizations must not become missing-translation errors. Check duplicate identities and configured draft/publication requirements. If a production build omits a source needed to assess policy, use an explicit analysis view. Do not confuse that view with publishable output.

Provide two policies: strict correspondence for manuals, and localized content for blogs or product pages. Strict policy can require explicit IDs, declared placeholders, selected code blocks, and necessary fields to agree. Localized policy checks only declared shared constraints. Heading counts and all code blocks must not become universal requirements.

Propose translations status, translations diff <page>, and an explicit review-record operation. A versioned review record binds the translation to a source content hash or Git revision, plus the translation hash and declared source language. A missing record means unknown. A changed hash means changed since review, not automatically a bad translation. Recording review requires a user-requested write and must never happen just because a checker ran.

Native content rules and baselines

This scope is accepted locally. The original requirements below are retained as proposal history. Current behavior and flags belong to the CLI contract.

Start with a small catalog of high-confidence rules drawn from actual consumer failures: malformed supported component/attribute usage, conflicting explicit IDs, known deprecated forms, and configured protected content. Respect the syntax boundaries of code, inline code, shortcode bodies, raw HTML, and attributes. Do not apply regular expressions without regard to these boundaries.

Use the effective theme version’s contracts. An editor schema that omits types is not a complete strict validator. Missing compatible metadata must produce explicit limited coverage rather than validate against the latest theme. Do not require a future theme release to finish basic checks.

A visible versioned baseline can acknowledge existing findings with stable fingerprints, reasons, and review metadata. Reports show acknowledged and new findings separately. Baseline updates are explicit and reviewable. They cannot hide required incomplete work. Formatting and prose suggestions are optional. Automatic fixes first produce a diff, then validate a candidate before applying a narrow set of files.

Verified publication and CI

This scope is accepted locally. The original requirements below are retained as proposal history. Current behavior and flags belong to the CLI contract.

Preserve the current transparent build default. Add an explicit managed build --check workflow. Run one strict Hugo build. Run selected checks on the same output. Export only that verified artifact to a new or empty destination. Do not delete arbitrary directories or mix stale files into a verified tree. Default build must continue to report when extra checks did not run.

A local versioned manifest records the source revision and dirty state when known. It also records the source-input hash, effective theme identity, Hugo/CLI versions, build settings, base URL, check coverage, and file digests. Secrets and machine paths must not be copied into public metadata. If a public build marker is enabled, it contains only the minimum identity needed for verification. Artifact changes after validation invalidate the recorded result.

Propose ci init github-pages and ci init cloudflare-pages --mode direct-upload. Generate local configuration only, explain variables and permissions, and record template provenance. Detect existing workflows, preview diffs, preserve unknown modifications, and require explicit application. Both use the same quality engine and upload the verified output without another Hugo build. Before a public CLI release, templates must accept a documented immutable source/archival input rather than assume a nonexistent download tag.

Extend release diagnosis with an example-address warning, a release-policy error when publication checks require a real address, effective local source commit/dirty state when available, and comparisons with supported generated CI settings. Unknown custom CI is reported as unknown. A local checkout’s commit does not attest to a published module. Vendor byte identity remains separate.

Propose verify --site URL --manifest FILE with explicit network permission. Check representative pages, languages, resources, search/Markdown outputs, canonical addresses, and artifact identity. A generic fallback with HTTP 200 must fail identity checks. Timeout, authentication, rate limiting, or an absent required identity produce unknown/incomplete results, not invented success. Local HTTP fixtures test this without deploying to a provider.

Authoring and upgrade assistance

Add new, a small snippet catalog, and explicit editor-schema setup. Create page bundles, selected translation drafts, and ordinary front matter while refusing existing files. Translation drafts are not completed translations. Editor hints follow the effective theme and preserve existing editor settings.

Extend init with docs, blog, book, and project profiles by composing one licensed Starter source. Do not maintain four copied template trees. For existing projects, provide diagnosis and reviewed proposals. Do not replace their configuration.

Keep the explicit-tag, single-site upgrade protections. Add readable unified diffs and baseline/candidate route and capability comparisons. Report removed URLs, changed aliases and missing previously enabled outputs. A clean candidate build alone does not prove compatibility. Proposed configuration migrations need a documented transform and tests. Otherwise return a manual action. Conflicting replacements and vendor refresh remain explicit owner operations.

Impact analysis and safe content changes

This supported scope is accepted locally. The original proposal requirements below remain as history. Current behavior, limits and flags belong to the captured-facts contract and move contract.

Provide inspect <page>, impact --since <ref>, and context <task> over the shared facts. Inspect shows provenance, publication state, references, translations, and outputs. Context packages relevant local material with versions, paths, selection reasons, and size limits. No vector service or LLM is required. Document content is data. It cannot authorize command execution.

Initially check --since may still perform a full check and say so. Later optimization must include changed targets, their inbound references, translations, and derived outputs. Deleting B must still inspect unchanged A that links to B. Configuration, templates, navigation, or uncertain dependency changes expand the scope to a full check. Cache data is disposable evidence. It is not an authority.

Propose move <source> <target> as preview by default. A plan contains touched files, readable diffs, base hashes, translations, attachments, route changes, and an alias recommendation. Rewrite only links whose meaning and ownership are known. Ambiguous template/shortcode references require review. Apply verifies bases, validates an isolated candidate, protects concurrent edits, and retains recovery information. A failed or stale plan must not partially overwrite user work.

Workspaces and optional tools

An explicit workspace registry names selected site directories. It reuses the single-site engine, reports per-site results and aggregate completion, and allows writes only to explicitly selected sites. It must not discover and upgrade every sibling repository automatically or duplicate Hugo settings.

Optional markdownlint, Vale, and lychee adapters use explicitly configured, already provisioned tools and normalize their findings. Required missing tools return 2. Optional omissions remain visible. If the adapter cannot understand syntax, exclude it. Do not rewrite it. Ambiguous external-link failures require a network-status distinction. Tool installation and network access are separate actions, and generic formatters never overwrite content by default.

R6 accepted local boundary

The explicit registry and optional adapters are accepted locally in supported R6 scope. Stable fields and limits are documented in the registry contract and tool contract. The accepted R7/R8 boundaries below retain their own evidence and limits.

oink.workspace/v1 names 1–64 literal directories in one regular YAML file bounded to 256 KiB, without duplicating Hugo settings or discovering siblings. Exact names, canonical root identity, registry-order selection, per-site 0/1/2 parity and explicit-name saved-plan application are the supported workspace boundary. Already provisioned markdownlint-cli 0.49.1, Vale 3.24.0 and lychee 0.24.2 extend each site’s policy, with captured configuration and typed protocol/source/network coverage. They do not install or format tools/content. Lychee needs explicit network consent. Ambiguous external failures remain unknown rather than definite broken links.

Frozen Go/vet, actual Hugo/pinned-tool, and owning race gates have passed. The exact binary also passed four-site direct/aggregate diagnostic/coverage/exit parity and all source byte, full-mode, Git, ignored-input, and directory guards. Initial preparation failures remain excluded, and the receipt-driver-only command metadata correction is recorded without a CLI runtime correction or rerun. Guarded canonical EN/ZH source/rendered checks passed, and supported R6/A07/A15 scope is accepted locally in the R6 record. Current A18 runtime/archive qualification passed. Darwin amd64 remains experimental/unverified.

Read-only Oink Studio

Build a local web interface with project overview, issue panel, translation comparison, page relationships, and publication panel. These views use the same core results as CLI/CI. Support filters, known-source navigation, actual Hugo preview, change comparisons, and copying proposed actions. A large graph or embedded editor is not needed for this acceptance.

Default to loopback and an explicit site allowlist. Separate untrusted rendered content from the management origin. Handle Host/Origin checks and session authorization before adding write APIs. Ship prebuilt UI assets with the CLI. Node is a contributor build dependency, not a consumer runtime requirement. Cover keyboard operation, screen-reader labels, mobile layouts, light/dark themes, and readable long diagnostic lists.

R7 candidate boundary

The read-only Studio candidate now serves an embedded five-view browser and an authenticated literal-loopback API over the same native checks and captured Hugo facts. Stable candidate boundaries are in the contract. Explicit existing-site/registry selection, typed paginated findings, source/diff/hash states, actual production preview and separate optional analysis coverage preserve the CLI authority.

Frozen native/browser/core-case and exact-binary four-consumer receipts now qualify the supported read-only scope, including explicit partial-preview incompletion. They exercise native 0/1/2 parity, keyboard/mobile/light/dark flows, literal source data and separate-origin preview attacks. R7/A16 passed guarded canonical promotion/rendered gates and is accepted locally. R1–R8 supported scope and current A18 runtime/archive qualification passed.

Safe Markdown editing

After the read-only interface is accepted, add Markdown editing, front matter forms, selected component insertion, and attachments. Reuse the CLI change-plan engine and actual Hugo preview. There is no second save/validation mechanism.

An unchanged open/save cycle must preserve bytes. Updating one field preserves unknown fields, comments, order, encoding, and unrelated whitespace. Detect external-editor changes and refuse stale saves. If a front matter form cannot preserve a construct, keep it editable as text and explain the form limitation. Do not round-trip the whole document through a generic serializer.

Writes need an authorized local session, an allowed directory, base verification, and a visible diff. Reject path traversal, symlink escapes, and requests from untrusted preview content. Attachments must not overwrite existing files. Publishing a static site never adds these management APIs to it.

R8 accepted editing boundary

R8 now has one source-preserving proposal engine for CLI edit text, field, snippet and attachment, and the explicit studio --edit flow. Default Studio remains read-only. Known site-owned Markdown, exact source hashes, supported top-level YAML scalars with text fallback, original catalog byte-boundary insertion and new-only leaf-bundle attachments share the same saved plans and guarded writer. The complete visible review binds plan, file, and full-mode identities. Candidate HTML comes from actual selected nonpublishable Hugo analysis, with native findings and required view incompletion kept distinct.

The accepted local interface is documented in the contract. Corrected frozen public/Go/race/vet, actual/ordinary Hugo, Editor browser accessibility/mobile and exact-binary four-consumer preservation gates passed. R8/A17 supported local scope also passed guarded canonical source/render gates and is accepted in the R8 record. R1–R8 supported scope and current A18 runtime/archive qualification passed. Darwin amd64 stays experimental/unverified.

Delivery sequence and schedule

The following estimate assumes one developer. T0 is the implementation start after scope approval. Dependencies are sequential acceptance gates, which additional staff can support through independent tests and UI work.

Stage Effective weeks Delivery Acceptance gate
R1 1–2 Shared facts, check policy, focused scopes, trustworthy locations Hugo owns routes/relationships. Required incomplete checks cannot pass
R2 3–5 Translation policy/review state, native checks, visible baseline Three language layouts. Strict/localized cases. Reviewed fixes preserve files
R3 6–8 Verified build artifacts, CI init, release diagnosis, deployed-site verification One checked artifact is uploaded. Stale bytes and HTTP 200 fallback are detected
R4 9–11 New content, profiles, snippets/editor setup, upgrade diffs/comparisons Ordinary Hugo build. Dirty/replaced/vendor and route-regression cases remain safe
R5 12–15 Inspect, impact, context, move and shared change plans Unchanged inbound links and translations are included. Stale plans cannot write
R6 16–17 Explicit workspaces and optional check adapters Per-site parity. Required unavailable tools are incomplete. No implicit installs
R7 18–20 Read-only Studio and its security boundary Five useful views. CLI/UI findings agree. Accessibility and preview isolation pass
R8 21–24 Safe Markdown/forms/attachments with conflict review No-op save has zero diff. Comments/unknown fields survive. Concurrent saves fail safely

Allow another 4–6 weeks for integration, false-positive review, cross-platform execution, and repairs, distributed across the gates. The total planning range is 28–30 effective weeks (or roughly twice that elapsed calendar time at half-time availability).

R1–R3 yield a proposed 0.2 quality/publication candidate around weeks 9–10 including early reserve. R4–R6 yield a proposed 0.3 maintenance candidate around weeks 19–20 cumulatively. R7–R8 yield a proposed 0.4 local Studio candidate around weeks 28–30 cumulatively.

Conditional extensions

Extension Entry criterion Proposed boundary Separate estimate
E1 Publication exports At least two maintained books need a recurring export workflow Reuse distributable EPUB/PDF tools and package local artifacts. Declare external dependencies 1–2 weeks after R3/R4
E2 Executable examples Explicit owners identify runnable examples and disposable test environments Reviewed execution profiles, time/resource limits, offline default. Never execute discovered prose automatically 3–5 weeks after R5
E3 MCP An existing Agent integration needs capabilities beyond invoking JSON CLI results Thin adapter over inspect/check/impact/context/plans. Same permissions and diagnostics 1–2 weeks after R5
E4 AI review and translation Deterministic translation maintenance works and a reviewed evaluation corpus exists User-selected provider, explicit network/cost settings, proposals bound to source hashes. No automatic source writes 3–6 weeks for a limited experiment after R5

The R1–R8 total excludes these estimates. Activate an extension only for its stated use case. A future need is not an unfinished core milestone. Remote Studio, live collaboration, native shells, general knowledge provenance, vector retrieval, and universal framework migration require separate PRDs and evidence.

Architecture and compatibility

Use Go for core operations. Use subprocesses for Hugo and optional tools. Extend existing packages when they own the behavior. Add a package only with its capability. Do not create a generic plugin platform, public SDK, or shared service layer before an actual consumer needs it.

Preserve oink.result/v1, exit meanings, and the default thin wrappers. New diagnostic details and command data may be additive. Changed field semantics need a new result version. Version review records, baselines, plans, build manifests, and workspace registries independently. Detect supported capabilities from the actual theme. Do not require all users to install the latest release.

Read/check/preview, local file application, networking, example execution, and deployment have separate side effects. No telemetry, background updater, credential discovery, arbitrary directory cleanup, global configuration change, commit, push, or deployment happens as a maintenance side effect. Read-only consumer trials preserve sources, replacements, workspaces, and vendor bytes.

Acceptance cases and owning checks

Case Required outcome Primary owner
A01 JSON and completion One JSON result on stdout. Clean stderr separation. Findings 1, required incompletion 2 internal/report, internal/app, Schema
A02 Hugo truth Slug/url/permalinks/aliases, custom mounts, unlisted pages and language roots follow actual Hugo results internal/site, internal/outputcheck, actual Hugo fixtures
A03 Subpaths A definite project-local missing route fails. Outside-origin/path references remain classified honestly. Declared external scopes avoid false positives Output checker and policy tests
A04 Translations Filename, directory and translationKey layouts. Duplicate/missing/draft cases. Strict/localized policy Translation engine and public-command tests
A05 Review state No record is unknown. Changed source hash is visible. Mtime never determines review state Translation/review-record tests
A06 Content syntax Fences, inline code, shortcodes, HTML, attributes, custom fields and configured protected text do not generate invented findings Native-rule tests and real content corpus
A07 Baselines and adapters Acknowledged findings remain visible. New findings fail policy. Unavailable required tools cannot pass Policy/adapter tests
A08 Artifact identity Modify a file after check and manifest verification fails. Provider upload uses the same exported tree without rebuilding Managed-build and workflow tests
A09 CI preservation Both templates, existing customized workflows, permissions/variables, preview/apply conflict and provenance Starter/CI tests and local workflow rehearsal
A10 Public verification HTTP 200 fallback, wrong language/build, missing resource, canonical mismatch, timeout/auth/rate limit Local HTTP fixtures, no required cloud account
A11 Initialization and authoring Supported profiles/languages. Empty-target protection. Generated sites build with ordinary Hugo. Editor config preserves unknown settings internal/starter, authoring and Hugo tests
A12 Upgrade Readable diff, old/new routes, dirty files, both workspaces, replacement/vendor, failure recovery and concurrent edits internal/upgrade, public-command/Hugo tests
A13 Impact Deleted B finds unchanged A. Translations/attachments/derived outputs included. Global changes expand scope Impact and Git-baseline fixtures
A14 Change application Candidate validation before apply. Hash conflicts and failed writes preserve subsequent edits. Ambiguous references are not rewritten Shared plan/apply and move tests
A15 Workspace and context Per-site results match direct invocation. Selected writes only. Bounded context gives paths/versions/reasons without executing content Workspace/context tests
A16 Studio parity Five views show the same results as CLI. Usable keyboard/mobile/light/dark flows and source/preview separation Studio browser/accessibility tests
A17 Editor preservation No-op save is byte-identical. YAML comments/unknown values/order survive. Stale saves and attachment collisions are rejected Editor/browser and shared apply tests
A18 Runtime and recovery Test actual declared macOS/Linux targets. Signals stop child processes. Cached operations work offline. Unsupported inputs remain explicit Process/integration/installation tests

Run the smallest owning tests before broader integration. Keep Go unit fixtures offline. Repeat actual Hugo tests after parser, snapshot, probe, initialization, or upgrade changes. Keep focused checks. Do not require consumers to run theme internals or a browser suite for every document change.

For each candidate, record tool versions and source identities. Then test the Starter and three distinct maintained sites without writes. Compare source bytes, modes, and Git state before and after. Tests for new native rules need a reviewed valid/invalid corpus. Fix false positives before enabling a blocking default. Before promising incremental speed, measure full-build time against the same current-site baseline. Functional correctness takes priority over check counts.

Completion and release evidence

For each stage, record implemented behavior, known limits, focused tests, and actual integration results. Provide updated EN/ZH contracts/guides and a reviewable diff. Track individual requirement/case statuses. This PRD is complete only when R1–R8 and their required acceptance cases are satisfied.

After supported behavior is accepted, move it into the owning CLI contract, usage guides, and durable decisions. Retire the corresponding proposal sections through the existing lifecycle.

Decisions and stop conditions

Confirm staffing and start date before turning relative weeks into calendar dates. Decide supported runtime targets, review-record storage details, initial native-rule catalog, and precise additive command flags in R1. These are bounded implementation choices within this scope, not reasons to reopen the product boundary or wait for an entire theme release.

If preservation or correctness work exceeds a stage estimate, move its optional convenience work later. Never remove stale-write protection, truthful completion, or ordinary-Hugo compatibility. If repeated corpus review shows that a rule is unreliable, keep it advisory or remove it. If a form cannot preserve source bytes, keep that syntax in text mode. Interest in implementing a conditional extension does not add it to the critical path.

Decision log

Date Record
2026-10-03 Created from the current CLI audit and the supplied feature goals. Proposed R1–R8, optional extension gates, resource assumptions and executable acceptance cases.
2026-10-03 R1 shared Hugo facts and check policy passed local owning/actual-Hugo checks. Stable behavior moved into the CLI contract. The acceptance record tracks final refreshed reports and rendered EN/ZH evidence separately. R2–R8 and conditional extensions remain open.
2026-10-03 R2 translation scopes/hash reviews, syntax-bounded native rules and visible baselines now use shared guarded file plans. Local owning, actual-Hugo and focused race gates passed. Final refreshed consumer and EN/ZH documentation acceptance remains pending in the record. Implemented behavior is in the contract. R3–R8 remain open.
2026-10-03 R2 final corpus and bilingual documentation gates passed. R3 one-render checked export, exact file identity, guarded CI plans for both providers, release diagnosis and explicit-network HTTP verification passed their scoped local gates, including custom-workflow discovery. Stable behavior moved to the contract. Exact evidence and A08–A10 outcomes belong to the maintenance record. R4–R8, final A18 runtime/archive refresh and Darwin amd64 remain open.
2026-10-03 R4 supported local scope passed frozen Go/vet, actual Hugo/race and exact-binary read-only Starter/docs/PIG/repository gates. One unchanged licensed Starter composes all profiles/languages. Ordinary new/editor/snippet flows and source/external-input guards passed, as did readable bounded upgrade views and alias/output regression protection. Stable behavior belongs to the contract. Exact A11/A12 evidence and remaining limits belong to the record. R5–R8, final A18 runtime/archive refresh and Darwin amd64 stay open.
2026-10-03 R5 corrected frozen Go/vet, actual Hugo/race and exact-binary four-consumer read-only gates completed. Inspect/context complete for all sites. Historical impact and move blockers remain explicit. Guarded canonical source/rendered gates and stage acceptance are pending. Stable behavior belongs to the contract. The record identifies A13/A14/context evidence, the cached-module correction and exact preservation receipt. R6–R8, workspace A15 and final A18 remain open.
2026-10-03 R5 supported inspection/impact/bounded-context and guarded move scope is accepted locally after corrected frozen owning gates, exact-binary four-consumer preservation and first-promotion canonical source/rendered gates. The production translation owner retains only its known draft-release omission. Separate nonpublishable analysis passes all owners. Stable behavior belongs to the contract and command reference. The record retains exact outcomes and the separate post-render evidence boundary. A13/A14 supported CLI scope passed. A15 context passed while workspace/direct parity remains R6. R6–R8 and final A18 remain open.
2026-10-03 R6 explicit registry and bounded optional-tool candidate implemented. Focused workspace and corrected actual-protocol trials passed, with preparation failures kept separate. Final runtime/corpus/canonical gates and A07/A15 stage acceptance remain pending in the R6 record. R7/R8 and final A18 remain open.
2026-10-03 R6 frozen Go/vet, actual Hugo/pinned tools, owning race and exact-binary four-consumer direct/aggregate parity/preservation qualified. The completed receipt records six original operations, existing repository duplicate-ID findings and a driver-only command-summary correction over unchanged raw outputs. No CLI/Hugo rerun or runtime fix was needed. Canonical source/render checks and explicit R6/A07/A15 stage acceptance remain pending in the record. R7/R8/final A18 remain open.
2026-10-03 R6 supported explicit-registry and optional-tool scope is accepted locally after frozen Go/vet, actual Hugo/pinned tools, race, exact-binary four-consumer parity/preservation and guarded canonical source/render gates. A07 adapters and A15 workspace/direct/context supported scope passed. The R6 record separates first-promotion rendered bytes from this post-render status/evidence amendment. R7/R8 and final A18 remain open.
2026-10-03 R7 read-only embedded Studio candidate and authenticated loopback views implemented. Frozen core/browser and exact-binary four-consumer qualification completed within the declared scope. Guarded canonical promotion/render and explicit R7/A16 acceptance remain pending. R1–R6 remain accepted. R8/final A18 open.
2026-10-03 R7/A16 supported read-only Studio is accepted locally after frozen cumulative executed-case/browser proof, exact-binary four-consumer parity/preservation and guarded canonical source/render gates. First-promotion rendered bytes remain distinct from this post-render status amendment. Whole invocation failure and explicit partial-preview incompletion stay visible. R1–R7 accepted. R8/final A18 open.
2026-10-03 R8 CLI/opt-in Editor source-editing candidate implemented. Default Studio remains read-only. Pure-core/streaming-output focused evidence is recorded and failed browser trials retained. Final frozen public/browser/consumer/canonical gates and A17 stage acceptance remain pending in the R8 record. R1–R7 remain accepted. R8/final A18 open.
2026-10-03 R8/A17 reviewed CLI/opt-in Editor supported local scope is accepted after corrected frozen whole owning/browser gates, exact-binary four-consumer proposal parity/source preservation and guarded first canonical promotion/actual rendering. R1–R8 are accepted locally. The R8 record separately binds first-rendered and current status bytes, retaining every failed trial, native finding and required partial-preview incompletion. Final A18 current Linux/archive qualification remains open.
2026-10-04 Current backend integrity correction, refreshed owning/Hugo/race, carried unchanged-runtime four-consumer preservation and three declared runtime/archive qualifications passed. See the dated completion supplement. Finite R1–R8 implementation is complete locally. Retain this requirements record and anchors, retire it from active navigation, and keep stable behavior in the contract/guide. E1–E4 have not been invoked.

9.5 - Visual presets and appearance switching

Paper and Slate ship in 1.2.0; Ink and Terminal are explicitly enabled experiments awaiting design acceptance.
Phase 1 released in 1.2.0; Ink/Terminal opt-ins available

Paper, Slate and the Appearance menu ship with OINK 1.2.0. The architecture contract, accepted decision and acceptance record own phase-one behavior and evidence. A subsequent Ink/Terminal experiment provides actual selectable output; this proposal remains active for their design acceptance. The October 4 injected screenshots are research prototypes; they are distinct from the October 5 screenshots of actual theme output.

Status and surface

Field Value
Status Phase 1 released in 1.2.0; Ink/Terminal explicit opt-ins
Owner OINK maintainers
Date 2026-10-04
Baseline OINK v1.4.0 theme and documentation site; this row preserves the proposal’s October 4 research starting point
Affected contracts Architecture: Trust, CSS, and accessibility (font roles, accent roles, inline-code colour), Shell (theme control), Landing, Configuration decision, Brand guide
Phase 1 Paper preset, Slate preset, default changed to Paper, reader switching between Paper and Slate
Later phases Ink/Terminal design acceptance; Folio and Canvas names reserved only

Context and evidence

The baseline and limitations below record the October 4 research input, before phase 1.

OINK ships one visual identity, referred to here as Slate: a cool blue-grey canvas (#f1f4f8 / #0b1119), navy text, steel-blue links (#245f94), copper accents, Inter for interface and prose, Chakra Petch for display and wordmark, IBM Plex Mono for code and technical labels, a blueprint grid and glow on the Landing hero, and a crimson inline-code pair. It is defined by Bootstrap custom properties in assets/scss/td/_brand.scss, shell tokens in assets/scss/td/shell/_tokens.scss, and font roles in assets/scss/td/_tokens-typography.scss.

PG.CENTER, an independent site, has a warm editorial reading style that maintainers want as the future OINK default. Its presentation tokens live in media/css/pgsql.css of that project. Measured on its local preview (2026-10-04, light and dark, home, Docs index, long manual page, component manual):

Role Light Dark Note
Canvas #f7f6f3 #161513 warm white / warm black
Raised surface #ffffff #1d1c19 cards, code blocks
Secondary surface #efede8 #262420 table header, hover
Ink #21201c #ece9e3 body text
Secondary text #56534c #b6b1a7
Lines and washes ink at 4.5–22 % alpha light ink at similar alpha no tinted greys
Radius 12 px / 8 px same
Shadow 0 2px 10px rgba(33,32,28,.07) black-based warm, soft
Motion 160 ms cubic-bezier(.2,.7,.2,1) same

Typography is IBM Plex Sans (variable, 400–600) for interface and prose, IBM Plex Mono for code, dates and versions, and Chakra Petch for the wordmark only. The component-manual pages are the best long-form model: lead paragraph 17 px capped at 70ch, h2 followed by a hairline that runs to the edge, framed tables with a header band and no zebra, monochrome callouts with a 3 px rule.

The following PG.CENTER elements are site identity, not reusable reading rules: the PostgreSQL brand blue #336791 family, wine content links, version-state colours, release strips, search-kind badges, wiki tones, the duotone hero, and the 144-character measure of the imported PostgreSQL manual. Two values fail WCAG AA (muted text 3.67:1, link hover 4.22:1) and are corrected below rather than copied.

Measured OINK docs typography for comparison: 16 px / 1.7 body, ≈ 76ch measure, h1 36 px / 700, h2 24 px / 600, code 14 px. PG.CENTER Docs index: 15.5 px / 1.7, ≈ 120ch.

Current limitations

  • Colours are tied to data-bs-theme only. No attribute selects a second palette, and several surfaces bypass tokens: the Landing primary button (#2f6793 with navy glows), the grid, scrims (rgba(4,10,18,.45)), print colours, asciinema surfaces, and the giscus stylesheets.
  • About 85 literal border radii and several literal shadows make a flat preset impossible without a radius and shadow scale.
  • The light/dark control expands on hover or focus. Touch readers cannot reach “follow system”; the trigger mixes aria-pressed and aria-expanded; Esc does not close it. The Landing mobile drawer has no theme control.
  • contrast-on-canvas.html hard-codes Slate canvas luminance for the theme_color warning.
  • dark_mode is opt-in (false by default), so the palette and its menu are absent unless a site enables them.

Goals and non-goals

Goals:

  • one site key selects the default visual preset; Paper becomes the default;
  • Slate remains available and reproduces current output for sites that choose it;
  • readers can switch Paper and Slate instantly, without reload, independent of light/dark/system mode;
  • the configured default renders without JavaScript and with storage unavailable;
  • presets share templates, components, and layout geometry; they change paint and type;
  • local fonts only, ordinary Hugo build, no new runtime framework or required build tool.

Non-goals:

  • implementing Ink, Terminal, Folio, or Canvas in phase 1;
  • copying PG.CENTER brand colours, version UI, or page structures;
  • per-page or per-section presets (section colour remains theme_color);
  • changing layout geometry, density, or navigation structure per preset in phase 1;
  • theming Swagger UI, ReDoc, or third-party embeds beyond their existing light/dark handling.

Preset model

This table and the phase-one configuration below retain the original scope. The later experiment adds explicit ink/terminal configuration and menu-list entries; true still offers the stable set plus the site default. The architecture contract owns current behavior.

Preset Direction Phase 1 Reader menu
paper Warm editorial minimalism Implemented, default Yes
slate Technical minimalism (current OINK) Implemented Yes
ink Typographic minimalism, Swiss-inspired Spec + research prototype No
terminal Terminal-inspired utilitarian Spec + research prototype No
folio Academic / book publishing Name reserved No
canvas Playful geometric / creator Name reserved No

Reserved names are rejected by validation until implemented, with a warning that names the stable presets.

Configuration

params:
  ui:
    preset: paper        # paper | slate        (theme default: paper)
    preset_menu: false   # false | true | [paper, slate]
  • preset selects the site default. Invalid or reserved values warn through the existing validation path and fall back to paper. Publishing gates turn the warning into a failure.
  • preset_menu controls the reader choice. false renders no style group and emits no preset-init script; true offers every stable preset; a list offers a subset that must contain preset. Following the dark_mode precedent, the default is false; the documentation site enables it; starter adoption is outside this change.
  • preset is site-level only. Page and section overrides are not supported: switching identity per page would break reader expectation and the stored choice.
  • The Appearance menu exists when either dark_mode.show_menu or a style choice is enabled. A site with dark_mode: false and preset_menu: true shows only the Style group.

Relationship to existing keys

Precedence, lowest to highest:

  1. Slate base tokens on :root / [data-bs-theme] (unchanged selectors).
  2. Preset tokens on [data-td-preset=X].
  3. params.ui.typography: system — collapses font roles to system faces after the preset blocks, so it still requests no brand font in any preset.
  4. params.ui.fonts — emitted inline after the stylesheet at :root; equal specificity and later source order beat preset font roles. Explicit fonts always win.
  5. theme_color / theme_color_dark — page and section accent backgrounds only. They override the preset accent; they never touch links or inline code.
  6. Site _styles_project.scss — last in the bundle.

typography: technical remains the name for “use the preset’s bundled faces”. The preset decides which bundled faces those are (Paper: Plex Sans; Slate: Inter + Chakra Petch).

Reader state

Two independent dimensions:

Dimension Attribute Storage Values
Style data-td-preset on <html> localStorage['td-preset'] stable preset names
Mode data-bs-theme (+ .dark-mode, vendor data-theme mirror) localStorage['td-color-theme'] light, dark, auto
Situation Result
First visit Server renders data-td-preset="<site preset>" and data-td-site-preset; no script needed
Reader chooses a preset Applied at once, stored, td-preset-change dispatched
Reader chooses the preset marked “Default” Storage key removed; future site default changes reach this reader
Next page, refresh, other language Inline head script applies the stored value before first paint
Stored value no longer offered Removed; site default used
Storage unavailable Choice applies to the current page; the menu states that it will not persist
JavaScript disabled Site default preset renders in its light palette, as the current theme does without script; no style or mode control is usable
Style change Never writes td-color-theme; mode change never writes td-preset
Other tab changes the value storage event applies it

The inline script runs before the stylesheet, beside the existing dark-mode script. It validates the stored value against the allowed list embedded at build time, sets the attribute, and updates the theme-color meta and the pre-paint canvas colour for the preset and mode. It is emitted only when the menu offers more than one preset. Independently of the menu, the static pre-paint <style> and the resolved theme-color meta in head.html are rendered from the site default preset’s canvases instead of the current hard-coded #0b0d12, #ffffff, and #000000.

On switch the runtime sets data-td-preset-switching for one frame to suppress colour transitions, records the first visible heading or block as a scroll anchor, applies the attribute, and restores the anchor offset, again after document.fonts.ready because Plex Sans and Inter have different metrics. Focus, open menus, and form state stay untouched. Phase 1 uses no cross-fade or View Transition.

Appearance menu

Three options were compared:

Option Assessment
Keep the hover menu, add a style row Keeps the touch and keyboard gaps; hover-only discovery
Separate style and mode buttons Two icons in a crowded navbar; mobile drawer gets longer
One Appearance disclosure with two radio groups Chosen: one entry point, works with touch and keyboard, scales to more presets

Behaviour:

  • Trigger: one icon button (aria-expanded, aria-controls, label “Appearance”). It replaces the current theme button in the navbar and in the shell footer line. Sun means the current light state; moon means dark. The t shortcut keeps toggling light/dark.
  • Panel: a non-modal popover containing two native fieldset radio groups. The October 5 revision uses Style: icon-and-name buttons in two columns, with a preset-colored icon and no preview letters or experiment badges. The site default is identified by its tooltip and accessible name. Light: a segmented Light / Dark / System control. Selection applies immediately and the panel stays open so readers can compare.
  • Keyboard: Enter/Space or ArrowDown opens and focuses the checked radio; arrow keys move within a group (native radio behaviour); Tab moves between groups; Esc closes and returns focus to the trigger; focus leaving the panel or an outside click closes it.
  • Feedback: the selected option has a tinted background and accent border; keyboard focus has a separate outline. Changes are announced through native radio semantics; no extra live region.
  • Restore default: selecting the site’s default preset clears the stored choice. No separate reset button is needed.
  • Mobile (< 768 px): the trigger stays in the compact header and is also offered in the docs drawer footer and in a new row of the Landing mobile drawer. The panel opens as a bottom sheet with 44 px targets, the same two groups, and a close button. The sheet is a modal <dialog> opened with showModal(), so it lives in the top layer: the prototype showed that the sticky header’s backdrop-filter otherwise becomes the containing block of a position: fixed sheet and the drawer’s stacking context hides it.
  • Command palette: a switch_preset action next to switch_theme.

dark-mode.js keeps its storage key and attributes. It must sync the checked state of the Light radios and listen to their change events instead of the current aria-pressed buttons.

Token architecture

All presets compile into the single existing main.css. Fonts are declared with @font-face and are downloaded only when a rule uses them, so offering a preset costs CSS bytes but no font bytes until it is selected.

// Slate: existing selectors and values, unchanged
:root, [data-bs-theme='light'] { … }
[data-bs-theme='dark'] { … }

// Every other preset
[data-td-preset='paper'] { /* light tokens + font roles */ }            // (0,1,0)
[data-td-preset='paper'][data-bs-theme='dark'],
[data-td-preset='paper'] [data-bs-theme='dark'] { /* dark tokens */ }   // (0,2,0)

// Then: [data-td-typography='system'] font block (moved after presets)

Rules:

  1. Token parity. Each dark block redeclares every token of its light block, so Slate dark never leaks into another preset. A checker enforces it.
  2. Dark islands. The descendant form covers nested data-bs-theme="dark" islands (Landing code plate, previews).
  3. Font roles only at (0,1,0), so params.ui.fonts keeps winning.
  4. Accent indirection. Presets set --td-preset-accent (and -rgb, -hover); --td-accent defaults to it. theme_color keeps writing --td-accent and therefore overrides the preset in both modes.
  5. Slate stays attribute-free. data-td-preset="slate" matches no override block, so current site overrides of brand tokens behave exactly as today.
  6. Geometry is shared. Presets do not change grid columns, sidebar width, or breakpoints in phase 1.
  7. Preset-specific rules are few and scoped to [data-td-preset=X] in one partial per preset. Anything two presets need becomes a token.

New shared tokens required before Paper (phase 1): --td-shell-scrim, Landing --td-grid / --td-glow / primary-button tokens, --td-callout-tint, --td-code-inline-bg, --td-hairline, and a brand font role (--td-brand-font-family, default var(--td-display-font-family)) so the wordmark can keep Chakra Petch while Paper’s display headings use Plex Sans.

The original phase-two plan proposed global radius, shadow and density scales. The October 5 experiment instead scopes those changes to owned components; a wider token refactor is not a prerequisite for trying the designs.

Contract change: the architecture contract currently fixes inline code to a crimson pair. This proposal makes --bs-code-color a preset token (Slate keeps crimson, Paper uses an ink chip). theme_color still never touches it.

Fonts

Preset UI / body / heading Display Brand (wordmark) Meta Code New bytes
Paper IBM Plex Sans IBM Plex Sans Chakra Petch IBM Plex Sans IBM Plex Mono Plex Sans
Slate Inter Chakra Petch Chakra Petch IBM Plex Mono IBM Plex Mono none
Ink Inter Inter Inter Inter (tabular) IBM Plex Mono none
Terminal Plex Mono chrome, Plex Sans prose IBM Plex Mono IBM Plex Mono IBM Plex Mono IBM Plex Mono none after Paper

Paper vendors @fontsource-variable/ibm-plex-sans (OFL-1.1) into third_party/ with a VENDOR.json entry: Latin, Latin Extended, Cyrillic, Cyrillic Extended, Greek and Vietnamese subsets, normal and italic, weights 100–700. PG.CENTER’s normal-only 400–600 subset is 40,240 B (latin) + 25,868 B (latin-ext); exact sizes are recorded at vendor time. Italic is required because OINK prose uses emphasis and PG.CENTER’s synthesized italic is not acceptable. The full small subsets preserve the existing locale coverage; the browser loads only the ranges actually used. All 12 font files are recorded in VENDOR.json.

Chinese, Japanese and Korean use system stacks placed after the Latin face: -apple-system, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans CJK SC', 'Noto Sans SC', sans-serif. IBM Plex Sans SC was rejected because its files are megabyte-scale. Monospace stacks insert CJK sans families before the generic monospace keyword so mixed code keeps a predictable CJK face.

typography: system continues to request no brand font: the system block follows every preset block and resets all roles, including brand.

Serif. Phase 1 uses no serif. Latin serif headings beside CJK sans headings look inconsistent, Windows’ default CJK serif renders poorly at heading sizes, and a serif costs another font. A later opt-in display-only serif can be reviewed with the side-by-side mockup produced for this proposal.

Preset specifications

Shared foundation

Belongs to every preset, not to Slate:

  • layout geometry, breakpoints, sidebar/TOC widths, ≈ 76ch prose measure;
  • body 1rem / 1.7 for prose, 0.875rem for chrome, 0.8125rem for meta;
  • type scale ratios (h1 2.25rem, h2 1.5rem, h3 1.25rem, h4 1rem) — presets tune weight and tracking, not size, in phase 1;
  • focus ring: 2 px accent outline with 2 px offset, never removed; forced-colors fallbacks unchanged;
  • semantic status colours (note, tip, important, warning, caution) keep their hue; presets change tint strength and frame;
  • syntax highlighting keeps the existing light/dark Chroma palettes in phase 1;
  • motion tokens 100/150/250 ms; prefers-reduced-motion disables transitions;
  • WCAG AA: 4.5:1 body, 3:1 large text and UI boundaries, in both modes.

Paper

Warm editorial minimalism. Warm paper, ink text, quiet hairlines, soft shadows, and generous but not loose reading rhythm. It serves long-form reading: lower blue light on large canvases, less chrome contrast, and a typeface (Plex Sans) with open counters that reads well at 16 px.

Token Light Dark
Canvas --bs-body-bg #f7f6f3 #161513
Raised --td-brand-elev, --td-pre-bg #ffffff #1f1e1a / #121110
Secondary surface #efede8 #1f1e1a
Body #21201c (15.09:1) #ece9e3
Secondary text #56534c (7.10:1) #b6b1a7
Tertiary text #6b665d (5.27:1) #958f84 (5.68:1)
Border ink 12 % light ink 13 %
Link / hover #2b5f8c (6.23:1) / #1d68a5 (5.43:1) #7db5e6 (8.36:1) / #a3cdf3
Accent (copper) #9c5530 (5.17:1) #d99a6c
Inline code ink on ink-6 % chip light ink on 8 % chip
Shadow sm / md 0 2px 10px / 0 14px 38px ink 7 % / 13 % black 35 % / 50 %
Radius code 12 px, cards 12 px, controls 8 px same

Rules specific to Paper: headings Plex Sans 600 with −0.006em (h1 −0.012em); h2 followed by an edge hairline; framed tables (radius 10, header band, no zebra); callouts with a 4 % (dark 6 %) semantic wash and a single 3 px rule; hairline blockquote; Landing without grid or glow, primary button from tokens with a warm shadow, hero title 600 / −0.025em; selected navigation rows on a warm neutral ground with 9 % (dark 12 %) accent mixed in. Links remain blue: a reading convention, not decoration. Motion 160 ms ease-out for hover and popovers; no movement on scroll.

Slate

Technical minimalism. The current OINK appearance, unchanged: cool blue-grey canvas, navy ink, steel blue and copper, Inter body, Chakra Petch display, Plex Mono labels and metadata, blueprint grid and hero glow, crimson inline code, 8–12 px radii. Selecting preset: slate must reproduce v1.1 token values; a checker compares them. Grid, glow, Chakra display headings, mono metadata and crimson inline code are Slate identity. Layout, focus, status colours, and the shell structure are shared foundation.

Ink

Typographic minimalism, Swiss-inspired information design. Black, white and neutral grey; one red accent; hierarchy carried by size, weight and alignment rather than colour, shadow or rounded surfaces.

Token Light Dark
Canvas #ffffff #0b0b0b
Body #141414 #ededed
Secondary / tertiary #474747 / #636363 #b5b5b5 / #8f8f8f
Surface #f4f4f4 #161616
Link ink, underlined; hover red light ink, underlined; hover red
Accent #c8102e (5.88:1) #ff5c4d
Radius / shadow 0 / none 0 / none

Differences from Slate: no tinted canvas, no blue, no grid texture, no shadows, no rounded corners; links are identified by underline, not hue; headings use Inter 700–800 with tight tracking instead of Chakra Petch. Differences from Paper: neutral not warm, flat not soft, ruled not hairline, underline links not blue. Distinctive rules: 2 px black rule above h2; h1 800 / −0.035em; uppercase tracked h4, table headers and callout titles; selected navigation row marked by a 3 px red bar, not a fill; tabular numerals.

Terminal

Terminal-inspired utilitarian design. Structure and information expression, not CRT effects: monospaced chrome, command and path notation, compact controls, strong panel borders, amber or teal accents.

Token Light Dark
Canvas #f4f5f2 #0c0f0e
Body #1d211f #d3dbd6
Secondary #4a514d #9aa59f
Surface #e9ebe6 #141a18
Link (teal) #0a6560 (6.31:1) #4cc9bd
Accent (amber) #935400 (5.47:1) #f0a73a
Radius 2 px 2 px

Mono scope: navigation, headings, labels, metadata, breadcrumbs, buttons and code use IBM Plex Mono. Prose paragraphs, lists and table bodies use Plex Sans with platform CJK fallbacks, because long monospaced paragraphs and mixed CJK/Latin mono lines read poorly. Distinctive rules: ## prefix before headings rendered with content: '## ' / '' so assistive technology ignores it; bracketed callout labels ([NOTE]); the selected navigation row is inverted with a ▸ marker; 1 px strong panel borders; static ▍ caret in the hero. No scanlines, glow, blinking, or typing animation.

Difference matrix

Paper Slate Ink Terminal
Temperature warm cool neutral neutral-green
Canvas light #f7f6f3 #f1f4f8 #ffffff #f4f5f2
Canvas dark #161513 #0b1119 #0b0b0b #0c0f0e
Prose face Plex Sans Inter Inter Plex Sans
Heading face Plex Sans 600 Inter 600–700 Inter 700–800 Plex Mono
Display / wordmark Plex Sans / Chakra Chakra / Chakra Inter / Inter Plex Mono
Link signal blue steel blue underline + red hover teal
Accent copper copper red amber
Radius 8–12 8–12 0 2
Shadow soft warm navy-tinted none none
Section rule h2 trailing hairline none 2 px top rule ## marker
Selected row warm tint accent tint red bar inverted + ▸
Inline code ink chip crimson ink chip ink chip, bordered
Landing texture none grid + glow none none
Chrome density standard standard standard compact

Page density

Density follows the task, not the preset: the Landing hero allows the largest display type and brand expression; Docs prose keeps 1rem / 1.7 and ≈ 76ch; sidebar, TOC, parameter tables, search results and the command palette keep compact rows (0.875rem, 1.4–1.5 line height). Presets may change paint inside these zones but not their spacing in phase 1. Terminal’s compact chrome is a phase 2 density token.

Runtime surfaces

Surface Phase 1 impact
Blog, Book, taxonomy Tokens only; Book captions keep the prose face
Search dialog and command palette Scrim tokenized; selected row uses --td-shell-primary-dim
Mermaid, ECharts Colours baked at init on data-bs-theme. Add a data-td-preset observer only if charts take preset colours; phase 1 keeps mode-only chart palettes
asciinema Surface tokens; re-mount only if the code face changes (not in phase 1)
giscus Needs one stylesheet per preset and mode, re-posted on td-preset-change
Swagger UI, ReDoc Keep vendor styling and current light/dark handling
Print Tokenize navy and cool greys; print always uses a light palette from the active preset
404 Its own <html> must carry the new attributes

Accessibility, security, and output

  • Every preset palette passes WCAG AA for body, secondary and tertiary text, links, and accents in both modes (values above). theme_color contrast warnings compute against the active site default preset’s canvases.
  • The menu uses native radios; no role="menu". Focus is never trapped except in the mobile bottom sheet, which is modal and restores focus.
  • prefers-reduced-motion and forced colors keep current behaviour.
  • The init script is inline, static, and derived from validated configuration; the stored value is matched against a build-time allowlist before use.
  • No external font or script request is added. Output adds two <html> attributes, one inline script, and CSS.

Compatibility and migration

Changing the default to Paper changes every site that does not set preset.

  • Sites that want the current look add params.ui.preset: slate; the upgrade note leads with this one line. Slate output must equal v1.1 tokens.
  • Sites with custom brand overrides in _styles_project.scss: light overrides on :root keep working under Paper by source order; dark overrides on [data-bs-theme='dark'] are outranked by Paper’s dark block. Such sites should choose Slate or move overrides to [data-td-preset='paper'][data-bs-theme='dark']. The upgrade note and brand guide document this.
  • theme_color, typography, and fonts keep their meaning and precedence.
  • Sites with dark_mode: false still get one light palette, now Paper.
  • The release that changes the default must state it as a visible change. Whether that release is a minor (1.x) or major version is an open decision.
  • A consumer inventory should report sites with brand overrides before the default change is published.

Implementation plan

Phase 1, in dependency order. Each step names its owning checker.

  1. Tokenize Slate leaks. Landing primary button, grid, glow, scrims, print colours, asciinema surfaces; add --td-preset-accent, brand font role, and per-preset canvas luminance in contrast-on-canvas.html. Slate output must stay byte-for-byte equivalent in computed colour. Checkers: check-landing.py, check-output.py, check-font-tokens.py.
  2. Vendor IBM Plex Sans. third_party/, VENDOR.json, licence file. Checker: check-vendor.py.
  3. Preset tokens. New assets/scss/td/_presets.scss (imported after _brand.scss); the implementation keeps Paper in that file instead of a separate presets/_paper.scss. Place preset font roles before the system typography reset. Checkers: extend check-font-tokens.py (Plex Sans family, system block order, token parity between light and dark blocks).
  4. Configuration. hugo.yaml defaults (preset: paper, preset_menu: false); a resolver partial used by validate.html, document-attrs.html, layouts/404.html, and head.html (init script, theme-color, pre-paint canvas). Regenerate the schema. Checkers: check-params.py (accepted, invalid, reserved), generate-config-schema.py --check, check-namespace.py.
  5. Appearance menu. Shared partial used by navbar.html, shell/footer-line.html, and the Landing mobile drawer; preset.js runtime (or a section of dark-mode.js); dark-mode.js radio sync; palette action switch_preset; i18n strings in all 32 catalogs. Checkers: check-shell.py, check-actions.py, i18n checker, tests/js/preset.test.js, tests/js/dark-mode.test.js.
  6. Third-party surfaces. Per-preset giscus stylesheets and re-post.
  7. Documentation. EN/ZH architecture, shell and landing contracts; brand guide (presets, migration, fonts); configuration reference; changelog and upgrade note.
  8. Site validation. make -C ../oink.pgsty.com check, browser (add preset switching, persistence, storage failure, no-JS, EN/ZH, desktop/mobile, light/dark cases), and dev for visual review.

Acceptance criteria

The following are the original acceptance targets. Executed checks and remaining limits are recorded separately in the October 5 acceptance record:

  • With no preset key, output carries data-td-preset="paper" and renders Paper with JavaScript disabled.
  • preset: slate produces computed colours and font roles equal to v1.1 across the checker fixtures.
  • Switching style never changes td-color-theme; switching mode never changes td-preset; both survive navigation, reload, and language switch.
  • Invalid stored values are removed; storage failure leaves the page usable and shows the non-persistence note.
  • No first-paint flash between presets in Chromium, Firefox and WebKit at normal and throttled CPU.
  • Scroll position after a switch stays within one line of the anchor.
  • typography: system triggers no font request in any preset; params.ui.fonts overrides preset faces.
  • theme_color overrides the accent in both modes under Paper and Slate.
  • The menu is fully operable with keyboard, touch, and screen readers; axe reports no new violations.
  • All palettes meet the contrast table in both modes.
  • Presets add no external font or script dependency; explicitly configured services such as Giscus remain separate.

Open decisions

  1. Resolved for phase 1: preset_menu: false; the docs site enables it.
  2. Target resolved for release preparation: 1.2.0, with a prominent Paper-default notice and the preset: slate compatibility setting. Published in 1.2.0.
  3. Resolved for phase 1: the wordmark role is brand.
  4. Whether a display-only serif becomes a Paper option after phase 1.
  5. Whether charts (Mermaid, ECharts) should take preset colours in phase 2.

Ink and Terminal backlog

Implemented experimentally: both palettes, existing font roles, prose link and selection signals, heading treatments, scoped geometry, compact Terminal navigation, Giscus palettes, print and the existing switching mechanism. No new font file, animation or runtime is added. See the experiment record for actual output and verification.

Before stable promotion, review long-page red accent density and CJK underline weight in Ink; numbered headings, mono wrapping and dense parameter tables in Terminal; Windows/Android fallback faces and manual screen-reader speech. Mermaid/ECharts and API vendors remain mode-only for this experiment. Wider geometry/density tokens and preset-colored charts require a separate decision.

Decision log

Date Change
2026-10-04 Draft created with Paper/Slate phase-1 scope, Ink/Terminal research specs, Appearance menu choice, and token architecture
2026-10-05 Phase 1 implemented locally; defaults, brand role and mode-only chart scope accepted
2026-10-05 Subsequent explicit Ink/Terminal experiments implemented; stable menu policy retained; design acceptance remains open
2026-10-05 Release preparation targets 1.2.0; simplified Style/Light controls and current-state icons replace the earlier swatch proposal

9.6 - Stabilizing Ink and Terminal for reading

A conditional stabilization plan for two distinct reading styles, with a shared footer blocker and explicit bilingual accessibility gates.
Draft — promotion blocked

Enlarged text overflows the shared footer. At 320px with a 32px root/default font, English Ink reaches 424px document width and Terminal 408px. The comparison overlay does not repair this shared failure. Neither prototype is stable or accepted for promotion.

Status, ownership and scope

Status and date: Draft, 2026-10-26; proposed design direction, not an implementation contract

Accountable owner: OINK maintainers; separate recorded acceptance for each preset

Delivery owners: Theme maintainers own CSS, resolvers and focused checkers; documentation maintainers own bilingual contracts, real-site fixtures and browser review; accessibility reviewers own manual task evidence

Baseline: OINK v1.4.0; local source identity and dirty-snapshot limits are recorded in the research

Affected surfaces: Architecture, Components, Shell, Landing and the visual preset decision

Release intent: A later release, subject to refinement and independent acceptance; no new preset recommended

Context and evidence

Ink and Terminal already exist as explicit experiments. Their shared shell is an advantage: readers retain navigation, search, appearance controls and content semantics when changing style. Their remaining problems are repeated decoration, typography outside ordinary prose, inconsistent owned geometry, and incomplete acceptance. Ink is already neutral sans editorial; making it serif would consume Folio’s separate territory. Terminal should become a readable engineering handbook, retaining mono technical roles alongside proportional explanations.

The dated research distinguishes source facts, measurements, design judgments and a limited CSS overlay. Normal-size measurements, spacing probes and focused checks are encouraging, but the whole-document footer failure survives them. Manual 200% text-resize and 400% browser-zoom checks remain separate from the 32px font-preference probe.

Goals and explicit exclusions

Preset Audience and primary task Distinct identity within the same shell
Paper Broad documentation readers; guides and sustained reading Warm Plex Sans reading surfaces and restrained rounded components; remains the default
Slate Existing technical/product sites; reference navigation and product presentation Established cool palette, Inter/Chakra/Plex roles and richer Landing presentation; compatibility choice
Ink Editors, authors and readers of essays, design rationale and long documentation Neutral Inter/CJK sans, square flat surfaces, visible prose underlines and sparse red or authored accents
Terminal Engineers and operators; procedures, configuration lookup and code explanation Plex Sans explanations, mono headings/controls/identifiers, teal/mint links, amber emphasis and flat 2px geometry

Both candidates must work across Docs, Book, Blog, galleries, Expo and Landing in EN/ZH, light/dark and narrow/wide views. Neither is a separate shell, accessibility mode or table-density mode. Exclude new renderers, global spacing changes, font downloads, runtime dependencies, terminal effects, moving selection tracks, raised Tabs, boxed Field names and Paper heading tails.

Two optional concepts remain outside 1.4 scope:

Concept Distinct future purpose Cost and disposition
Folio Academic/book publishing: serif reading roles and scholarly captions/notes, sans navigation/search, mono code Requires a matched EN/ZH serif strategy, licensing, local font payload and fallback/print/device acceptance. Keep the shared shell; no imported margin-note column. Credible future study, not an Ink replacement.
Canvas Playful geometric presentation for creators: existing sans faces, controlled lilac/ochre accents and a few geometric markers No inherent font cost, but added palette/state/shape rules, asset guidance, menu and full regression coverage. Evidence is weaker and overlap with Slate is substantial. Defer until creator tasks justify it.

Proposed behavior and boundaries

Preserve the palette, assign each role

Retain these source colors initially. Values below are light/dark pairs, not a new configuration authority; preset SCSS remains the implementation owner. Refine repetition before changing hue.

Role Ink light / dark Terminal light / dark
Canvas #ffffff / #0b0b0b #f4f5f2 / #0c0f0e
Body #141414 / #ededed #1d211f / #d3dbd6
Emphasis #000000 / #ffffff #111713 / #edf4ef
Secondary text #474747 / #b5b5b5 #4a514d / #9aa59f
Tertiary text #636363 / #8f8f8f #606b63 / #8b9990
Secondary surface / code header #f4f4f4 / #161616 #e9ebe6 / #141a18
Tertiary surface #ffffff / #161616 #f8f9f6 / #18201c
Code block #fafafa / #111111 #ffffff / #0a0d0b
Link #141414 / #ededed #0a6560 / #4cc9bd
Hover link #c8102e / #ff5c4d #084f4b / #7de0d7
Default accent #c8102e / #ff5c4d #935400 / #f0a73a
On-link foreground #ffffff / #0b0b0b #ffffff / #0c0f0e
Ordinary border Body RGB at 24% / 24% Body RGB at 32% / 32%
Strong line Body RGB at 55% / 50% Body RGB at 55% / 55%
Inline code Body foreground; body RGB fill 5% / 6% Body foreground; body RGB fill 5% / 7%

Success, warning, error and information retain their semantic tones, icons and labels. Red is not every Ink status; mint is not every Terminal status. Keep neutral badges distinguishable from success. Decorative separators may remain subtle; required control boundaries need independent contrast measurements.

Authored theme_color remains authoritative for accent surfaces. Actual documentation uses blue #245f94/#5da2dd, Book orange #9a3412/#fb923c, and Blog violet #6d28d9/#a78bfa. These do not replace the link/code text roles. Review both authored accents and preset defaults.

Keep reading roles and verify actual fallback

Role Ink default Terminal default
body Inter + platform sans IBM Plex Sans + platform sans
ui Inter + platform sans Code role: IBM Plex Mono + mono fallbacks
heading Body role UI role
code IBM Plex Mono + mono fallbacks IBM Plex Mono + mono fallbacks
display Heading role Heading role
meta UI role UI role
brand UI role UI role
print Body role Body role

Book captions, table descriptions and human-readable search titles/excerpts use the body role. Authored chapter numbers retain their meaning and follow their heading’s role. Technical paths, command controls and identifiers remain mono in Terminal. Field names stay unboxed, at weight 600. Descriptive Terminal table headers move to body 0.875rem/600; ordinary prose retains 1rem/1.7 and the shared reading measure. Display titles retain page-specific scale and wrap; do not shrink mobile prose to accommodate mono chrome.

The existing sans fallback order is -apple-system, BlinkMacSystemFont, PingFang SC, Hiragino Sans GB, Microsoft YaHei, Segoe UI, Roboto, Helvetica Neue, Arial, Noto Sans SC, generic sans-serif and emoji. The mono list follows IBM Plex Mono with SFMono-Regular, Cascadia Code, Roboto Mono, Menlo, Consolas, Liberation Mono, Sarasa Mono SC, Noto Sans Mono CJK SC and generic monospace. Listed names do not install fonts. YaHei precedes Segoe and can supply Latin too. Chinese glyphs need not occupy Latin mono cells. Preserve language metadata, typography: system, explicit roles and legacy Sass precedence; inspect loaded, blocked, system and overridden font conditions on actual Windows/Android. (Font matching)

Compare Ink article h1 at weight 750/tracking -.025em, h2/h3 at 700/-.012em, and a 1px strong-token top rule instead of the current heavier rule. Chinese headings use zero tracking. Remove enforced uppercase/tracking from minor headings, table headings and callout titles. Terminal headings use 600/zero tracking; remove generated ##/### and callout brackets while preserving authored Book numbers, semantic labels and heading anchors. No fake prompts, blinking cursor effects or decorative heading tails.

Ink prose links remain natively underlined at rest, including lists, notes and citations. Terminal retains a persistent non-color link distinction; verify its existing semibold cue in real prose and use native underlines where that cue is insufficient. Navigation relies on its location and persistent current-state marks. Hover must not change layout, weight or hit area. (GOV.UK links)

Underline geometry remains a review decision. The overlay uses max(1px, .06em) thickness, .22em offset, with a Chinese .25em/skip-ink: none comparison. A blanket .25em rule is not accepted. Compare English .12–.18em and Chinese text-underline-position: under with only 0–.06em extra offset, starting with skip-ink: auto. Scope by actual language, including Chinese blocks inside English pages. Test mixed glyphs, punctuation, descenders, inline code and wrapped links; no line may collide with glyphs or adjacent lines. (CSS Text Decoration draft)

Make component states coherent

Owned component corner radii: Ink 0px, Terminal 2px, no elevation shadows; include FileTree’s currently hard-coded 0.6rem corner radius. Preserve image, avatar, status-dot and vendor geometry.

Current/selected: Ink keeps a static accent rail; Terminal keeps neutral inverse rows/marker. Programmatic state remains. Hover, selection and keyboard focus stay distinct; no traveling pill.

Focus: Immediate static indicator, independently measured on every adjacent surface, visible in forced colors; no global outline reset.

Text selection: Start from current authored-accent fill at 22% light/35% dark; measure composited text/inline-code pairs. Change through the owning role if needed; do not assume the opacity passes.

Tabs: Flat labels, static bottom selection rule, separate focus; no raised active tab. Preserve keyboard, hash/storage behavior, long labels and touch hit areas.

Fields and inputs: Unboxed technical Field names; descriptions remain prose. Actual input controls retain persistent labels, identifiable boundaries and associated error text; placeholder alone is insufficient.

Code and tables: Quiet single frame; preserve syntax semantics, comments, copying, captions, header associations and numeric alignment. Descriptive headers can wrap; no whole-table uppercase. Preserve authored width/overflow policy and local scroll access.

Notes, quotes, footnotes: Keep essential text visible; restrained semantic marker/rule, close attribution and usable reference/backlinks. No oversized quote ornaments, blanket Chinese italics or added margin column.

Cards, steps, badges, disclosures: Stable labels and geometry; distinguish clickable from static content, keep real step numbers, native disclosure semantics and labeled states.

Search and appearance: Body-role result titles/excerpts, mono technical paths; readable matching/selected/muted text. Preserve dialog focus/return, IME editing, loading/error/no-results feedback and reachability with a mobile keyboard.

Landing, Blog/gallery, Book, Expo: Preserve existing composition and media behavior; fit display titles, captions, bylines and utilities into each reading task. Do not turn image surfaces into squared global resets.

Preserve output, vendor and security boundaries

Mermaid/ECharts remain mode-only; API widgets retain vendor palettes and their existing mode behavior. Do not add preset recoloring inside vendor DOM. Giscus automatic palettes follow preset and mode; explicit overrides remain authoritative, but blocked remote frames are not accepted by this review. Print keeps the light preset on white paper; no-JavaScript output keeps the site-default light palette and readable content. Markdown/RSS preserve semantic content without decorative prefixes or control leakage. Keep existing escaping, validated font/color inputs, local assets and appearance storage behavior; no new network permission or script dependency.

Compatibility and migration

Keep preset names, independent mode/style state, shell columns, breakpoints, content syntax and author overrides. Retain Paper as default and maintained consumers’ explicit [paper, slate, ink, terminal] menu. A refinement can ship while a preset remains experimental.

Promotion changes the meaning of preset_menu: true: it offers stable presets plus the site default, so promoting either experiment expands that automatic set. Make that change explicit in layouts/_partials/preset-config.html, its checker and bilingual configuration/release guidance. Explicit lists retain their chosen membership. Promotion requires per-preset maintainer acceptance, not a status-label edit. Preserve reserved Folio/Canvas warning/fallback behavior.

Implementation and owning-checker plan

Stage / owner Work and evidence
Shared repair / shell maintainer Fix footer shrink/wrap behavior at its owner; add whole-document scroll-width and visible-content assertions through the footer for all four presets. Avoid clipping or hiding overflow as a remedy.
Refinement / theme maintainer Implement reviewed changes in existing preset, typography and component owners. Start with bin/check-presets.py, bin/check-font-tokens.py and affected component/output checks; preserve frozen Slate.
Integration / documentation maintainer Extend appearance, font, component and text-reflow suites on real EN/ZH pages; include full-page checks and annotated visual review. Run sibling-source make check, make browser, and make dev review.
Promotion / maintainers and reviewers Close the gates below; update owning implementation/checker and affected EN/ZH contracts together, then record durable rationale and user-facing migration guidance.

Runtime edits additionally require node --test 'tests/js/**/*.test.js'; schema edits require python3 bin/generate-config-schema.py --check.

Acceptance gates and open decisions

Distinguish accessibility requirements from project targets

WCAG 2.2 A/AA is the baseline (references accessed on 2026-10-26).

Gate Required assessment
Text and controls Normal text 4.5:1; qualifying large text 3:1 (24px regular or 18⅔px bold, equivalent CJK sizing). Required control/state cues 3:1 against adjacent colors; decorative dividers are different. Include code comments, placeholders and every selected/hover state. (1.4.3, 1.4.11)
Reflow and resizing Independently test 320 CSS px reflow, manual 200% text enlargement and 400% browser zoom from a 1280px viewport. Necessary two-dimensional regions require individual justification; code/tables are not blanket exemptions. Also close the separate 320px/32px-font stress blocker. (1.4.10, 1.4.4)
Spacing Tolerate simultaneous line-height 1.5, paragraph-after spacing 2em, letter spacing .12em and word spacing .16em without loss. These are user overrides, not default typography; assess applicable Chinese/mixed-script properties. (1.4.12)
Keyboard and meaning Visible focus; focused controls not entirely obscured by authored content; non-color state cues; correct language, headings, labels and table relationships. Character shortcuts need disable/remap/focus-only handling, not merely suppression in text inputs. Announce applicable search statuses without moving focus. (2.4.11, 2.1.4, 4.1.3)
Target minimum AA uses 24×24 CSS px or a qualifying exception. For its spacing exception, a 24px-diameter circle centered on each undersized target must intersect neither another target nor another undersized target’s circle; inline, equivalent, user-agent and essential exceptions also exist. (2.5.8)
Proposed stronger targets Routine touch controls 44×44px; main text 7:1; whole focused control/ring visible; static indicator at least a 2px-perimeter area with 3:1 change at the same pixels, plus adjacent-color contrast. These go beyond AA and need explicit adoption; they do not imply whole-page AAA. (2.5.5, 1.4.6, 2.4.13)

Record complete tasks before promotion

Require both languages and modes at 320/390/768/1440px, with normal, enlarged and overridden text. Review long pages at top/middle/footer, heading/Book numbering, URLs, Fields, tables, code, search, appearance, media and Landing. Inspect rest/hover/current/selected/focus/text-selection, forced colors, reduced motion and no-JavaScript/print/Markdown/RSS. Record actual color pairs and human review of axe incompletes.

Actual Windows Chrome/Edge and Android Chrome font/rendering work remains pending, as do branded macOS/iOS Safari checks. Record device/OS/browser/font conditions. Pending manual tasks use NVDA on Windows, VoiceOver with actual Safari, and TalkBack on Android: traverse headings and meaningful numbers, read tables/field errors, search with Chinese input, hear concise status feedback, open/close dialogs and regain focus.

Open decisions are the Chinese underline treatment, stronger project targets, any state-specific color repair, and the promotion of each preset. If gates remain incomplete, retain experimental status or defer refinement; unrelated 1.4 work need not wait for new styles.

Decision log

Date Proposed decision and status
2026-10-26 Keep Ink neutral sans editorial and Terminal a readable engineering handbook; preserve current palettes and author accents. Direction recommended; no stability acceptance.
2026-10-26 Prioritize shared enlarged-font footer repair; keep flat Tabs, unboxed Fields and no Paper tails. Remove decorative Terminal punctuation through existing owners.
2026-10-26 Chinese underline alternatives and stronger accessibility targets remain review decisions; exploratory probes do not close promotion gates.
2026-10-26 No new preset for 1.4; Folio/Canvas remain distinct future concepts. Per-preset promotion and automatic-menu expansion require explicit acceptance.