docs: rewrite developer guides and simplify the documentation site

.codex/skills/write-oliphaunt-docs/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: write-oliphaunt-docs
+description: Write, rewrite, audit, or redesign Oliphaunt developer documentation. Ground polyglot SDK examples and behavior in implementation, keep generated reference data synchronized, and verify the rendered Fumadocs site. Use for public docs and SDK READMEs, not release operations or historical architecture records.
+---
+
+# Write Oliphaunt docs
+
+Help a developer choose an SDK, run a query, and ship a working integration. Use this workflow for the requested scope; a small correction does not need a whole-site audit.
+
+## Establish the facts
+
+- Read the affected pages completely, then follow the exported API through its implementation and focused tests. Existing prose is a claim to verify, not authority.
+- Use [source-map.md](references/source-map.md) to locate SDK contracts, generated inputs, and checks. Inspect the current files; the map is a starting point, not a frozen API specification.
+- Distinguish implemented behavior, released package availability, and future intent. Repository version metadata alone does not prove registry publication. Browse primary sources when documenting external installation requirements or current releases.
+- For a rewrite, inventory every authored page and generated route. Record each file's purpose, accuracy findings, source evidence, and disposition in a maintainer audit under `src/docs/maintainers/`. Preserve useful behavior details when removing noise. Keep historical design records outside the public navigation.
+- Resolve uncertain behavior before presenting it as fact. Put remaining uncertainty and unrun checks in the audit or handoff, never in public TODOs, speculative promises, or invented output.
+
+## Organize around the developer's task
+
+Use [research.md](references/research.md) when changing information architecture or the authoring workflow. Its recommendations are adaptations of inspected primary sources, not instructions to install other projects' skills or services.
+
+- Start: explain the product in a short paragraph, help choose language/runtime, and lead directly to a first query.
+- SDK quickstart: requirements → install → complete first query → expected result → persistence → next task. Show the code early. Include imports, required setup, parameter binding, and cleanup.
+- SDK guide: recipes for persistent storage, transactions, backup/restore, extensions, errors, and shutdown where supported. Link the quickstart instead of repeating it.
+- API reference: exported entry points, options/defaults, parameter and return types, errors, and lifecycle constraints. Use implementation-derived declarations when available; edit generator inputs rather than generated output.
+- Shared guides: explain common concepts once. Keep language-specific differences next to the affected example. Do not imply that shared PostgreSQL semantics mean identical SDK APIs, concurrency, storage, or runtime support.
+- Prefer one coherent sidebar and shallow groups. Confirm that new pages are actually navigable and searchable. Preserve URLs where possible and verify changed anchors and incoming links.
+
+## Write and build
+
+- Use direct sentences, sentence-case headings, descriptive links, and language-tagged code fences. Begin sections with the information needed to act. Remove marketing claims, repeated summaries, maintainer commands, release-pipeline details, and implementation vocabulary that does not affect an integration decision.
+- Use `{{release:product-id}}` for public install and release versions. Generation maps product IDs through `release-please-config.json` to `.release-please-manifest.json`, pairing examples with the checkout API. Keep completed GitHub releases separate; an older published package must never relabel a newer API example. Preserve the build's `docs-version.json` when archiving it. Do not invent a shared SDK version or hosted historical versions. See the [docs README](../../../src/docs/README.md).
+- Apply the `better-writing` skill for prose reviews: put the developer's action first, remove internal design explanations, and make prerequisites explicit before the first runnable example.
+- Make examples idiomatic for each language. Verify names, overloads, imports, ownership, async behavior, storage types, package coordinates, and failure handling separately for every SDK. Do not translate examples mechanically.
+- Explain prerequisites before commands. Distinguish a complete program from a fragment that uses an existing `db`. Show expected output only when supported by execution or an unambiguous deterministic expression.
+- Keep warnings next to actions that can lose data or block an integration. Do not hide mandatory steps in tabs or disclosures. Use tabs only for interchangeable choices, such as package managers.
+- Reuse Fumadocs and its accessible primitives before adding components or dependencies. Use the available `better-interface` skills for layout, writing, typography, color, UI, and accessibility; use the React/Next.js skills when changing site code.
+- Follow the [design grounding](../../../src/docs/DESIGN_GROUNDING.md) for the site's dark default, constrained typography, spacing, and illustration style. Keep decorative artwork in the site shell rather than the exported developer instructions.
+
+## Verify the actual result
+
+1. Check the source-backed claims and example assumptions again after editing. A snippet marker, keyword match, successful MDX build, or AI review is not evidence that the example runs.
+2. Run the existing docs checks from [source-map.md](references/source-map.md). When changing a checker, retain route, metadata, link, release-data, and API invariants; replace obsolete prose/design assertions with checks of observable behavior. Do not weaken a real check just to make a rewrite pass.
+3. Execute representative complete examples against temporary databases using available runtimes. Type-check other changed examples where possible. Record each SDK as executed, compiled/type-checked, source-reviewed, or blocked with a concrete reason. Never describe source review as execution. Keep backups/restores isolated from user data.
+4. For UI work, inspect actual browser screenshots on desktop and narrow mobile, in light and dark themes. Check navigation, search, keyboard focus, code copying, tabs, long tables, and horizontal overflow. Correct defects and inspect the affected screen again. Use existing browser tools; do not add a second UI stack for review.
+5. Read as a newcomer using only the rendered docs: Which package fits my app? What do I install? Where does the code run? What result do I get? How do I keep data, handle failures, and close the database? Missing answers are docs defects. For lookup pages, test whether a reader can locate a specific option or method directly.
+
+Finish with the changed scope, checks that actually ran, and material limitations. Follow the user's existing authorization; this skill adds no permission or publishing workflow.

.codex/skills/write-oliphaunt-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Write Oliphaunt docs"
+  short_description: "Source-grounded SDK docs and visual review"
+  default_prompt: "Use $write-oliphaunt-docs to improve Oliphaunt developer docs, verify examples against the SDKs, and review the rendered site."

.codex/skills/write-oliphaunt-docs/references/research.md

@@ -0,0 +1,62 @@
+# Research: AI-assisted developer documentation
+
+Inspected 2026-09-08. These are primary project instructions, implementations, product documentation, and one empirical paper. They describe observable workflows; they do not establish that AI-generated prose is accurate or that a particular tool improves productivity. GitHub links track their named branches and may change.
+
+## How projects use AI to write and maintain docs
+
+| Inspected source | Observed practice | Adaptation for Oliphaunt |
+| --- | --- | --- |
+| [Supabase authoring guide](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md) | Ships separate agent skills for planning, architecture, drafting, editing, execution, and review. Defines four document types and sources reference parameters from code. | Keep the stages distinct within one small local skill; avoid a network of skills for a site this size. |
+| [Supabase write-the-docs](https://github.com/supabase/supabase/blob/master/.agents/skills/write-the-docs/SKILL.md) | Reads product intent and implementation before drafting, distinguishes generated reference from authored guides, wires navigation, and removes internal planning notes. | Code establishes behavior; the user's request establishes the rewrite's purpose. Explicitly track source uncertainty outside public pages. |
+| [Supabase test-the-docs](https://github.com/supabase/supabase/blob/master/.agents/skills/test-the-docs/SKILL.md) | Classifies complete examples, setup-dependent snippets, illustrative fragments, and deferred checks; executes in disposable environments and reports results. | Run Oliphaunt examples on temporary roots. Record execution versus type-checking versus source review per SDK. Its Supabase Docker stack is not applicable here. |
+| [Supabase edit-the-docs](https://github.com/supabase/supabase/blob/master/.agents/skills/edit-the-docs/SKILL.md) | Gives existing-page restructuring its own workflow, separate from inventing a new product story. | Preserve useful integration facts while rebuilding hierarchy and prose. A rewrite is not permission to infer capabilities. |
+| [Next.js update-docs skill](https://github.com/vercel/next.js/blob/canary/.agents/skills/update-docs/SKILL.md) | Maps source changes to docs locations, checks existing coverage, and handles shared content and examples. | Maintain a local source map; search all affected SDK pages when a common contract changes. Do not copy Next.js-specific paths or per-edit approval steps. |
+| [Cloudflare agent instructions](https://github.com/cloudflare/cloudflare-docs/blob/production/AGENTS.md) and [agent style reference](https://github.com/cloudflare/cloudflare-docs/blob/production/.agents/references/style-guide.md) | Give agents the real content pipeline, component rules, validation commands, and a distilled reference linked to the authoritative style guide. | Put stable workflow in `SKILL.md`, repository details in a linked source map, and reuse the installed UI skills. |
+| [Cloudflare docs review bot](https://github.com/cloudflare/cloudflare-docs/blob/production/.flue/AGENTS.md) | Separates code, conventions, and style review; validates findings against repository context. Structured results feed controlled publishing code. | Review correctness, discoverability, and writing separately. Require source evidence for findings. A bot service and automatic publishing are unnecessary for this rewrite. |
+| [GitHub documentation-writer skill](https://github.com/github/awesome-copilot/blob/main/skills/documentation-writer/SKILL.md) | Uses reader goals and Diátaxis to distinguish tutorials, guides, reference, and explanations. | Give each page a clear job, rather than adding the same summary and reference block everywhere. |
+| [GitHub docs-sync-audit skill](https://github.com/github/awesome-copilot/blob/main/skills/docs-sync-audit/SKILL.md) | Compares docs with code, reports drift with evidence, distinguishes confirmed findings from inference, and records checks not run. | Keep a file-by-file audit. Check generated sources and all plausible locations before declaring information missing. Its read-only scope does not apply to an authorized rewrite. |
+| [Anthropic doc-coauthoring skill](https://github.com/anthropics/skills/blob/main/skills/doc-coauthoring/SKILL.md) | Gathers context, iterates on structure, and tests whether a reader without prior context can answer likely questions. | Perform a newcomer task review from the rendered docs. Its interview-heavy process is excessive when source and task intent are already available. |
+| [Mintlify authoring skill](https://github.com/mintlify/docs/blob/main/skill.md) | Describes navigation, MDX components, concise writing, examples, and validation for its documentation framework. | Prefer shallow navigation, concrete prerequisites, and sparse callouts. Use Fumadocs APIs here; do not import Mintlify syntax or leave uncertainty as public TODOs. |
+| [Mintlify agent](https://www.mintlify.com/docs/agent) | Searches docs, connected code, and web context; plans, edits, validates, and submits changes according to configured review settings. | Adopt research → source-grounded edits → validation. A subscription or connector is not required to perform these steps locally. |
+| [GitBook agent](https://gitbook.com/docs/gitbook-agent) and [Git Sync](https://gitbook.com/docs/getting-started/git-sync) | Offer agent editing and repository-synchronized documentation workflows. | Keep reviewable docs-as-code changes in the existing repository; preserve the current site stack. |
+| [GitLab documentation workflow](https://docs.gitlab.com/development/documentation/workflow/) | Couples docs to feature changes and expects technical and writing review, including for AI-assisted content. | Run source and editorial review as distinct checks. Do not transplant another organization's approval policy. |
+
+The common useful pattern is constrained drafting with repository context and explicit verification. Large prompts, fluent language, and a passing site build do not establish SDK correctness. The [study of 1,997 agent/human documentation PRs](https://arxiv.org/abs/2601.20171), submitted January 2026, reports limited human follow-up on agent edits in its sampled repositories. That is evidence about review activity in the sample, not a measurement of Oliphaunt's quality or proof that agent edits are wrong. It reinforces our decision to retain independent, deterministic checks.
+
+## How polyglot SDK docs arrange the learning path
+
+| Inspected source | Pattern worth using |
+| --- | --- |
+| [DuckDB client overview](https://duckdb.org/docs/stable/clients/overview) | Start with language/client choice and distinguish support levels while sharing database concepts. |
+| [Turso SDK introduction](https://docs.turso.tech/sdk/introduction) | Choose a package by language and use case; runtime choice matters as much as language. |
+| [Supabase JavaScript installation](https://supabase.com/docs/reference/javascript/installing) and [reference introduction](https://supabase.com/docs/reference/javascript/introduction) | Provide installation commands and concrete examples; organize lookup material around API operations. |
+| [Diátaxis introduction](https://diataxis.fr/start-here/) | Separate first learning, task instructions, technical lookup, and conceptual understanding. Apply the distinction without forcing four duplicate sections into every page. |
+| [shadcn/ui tabs](https://ui.shadcn.com/docs/components/radix/tabs) | Use an accessible primitive for interchangeable choices; retain predictable focus and keyboard behavior. |
+| [Fumadocs UI](https://www.fumadocs.dev/docs/ui) | Reuse the documentation framework's navigation, code blocks, search, and content components. |
+
+For Oliphaunt, this becomes: product and SDK choice → SDK installation and first query → common application tasks → deeper concepts and API lookup. Native and WASIX variants need explicit runtime labels. Quickstarts need full examples; conceptual pages need only examples that explain the concept. One shared concept page is preferable to eight repeated introductions.
+
+## AI authoring versus documentation for AI consumers
+
+These are different deliverables. The local skill teaches an agent how to change this repository. Public Markdown exports and search help an agent consume the product documentation. [Mintlify's skill.md documentation](https://www.mintlify.com/docs/ai/skillmd) describes a product-facing skill alongside its documentation index; that does not make a public authoring checklist necessary. Keep Oliphaunt's existing Markdown exports accurate and navigable, and keep maintainer authoring instructions local.
+
+## Decisions for this rewrite
+
+- Use one repository-local skill with two references, not copied external skill bundles or new paid services.
+- Audit every public page and all generated routes. Keep the audit and this research out of the public docs.
+- Replace duplicated landing summaries and hidden API links with a clear SDK quickstart, task guide, and visible API reference.
+- Generate version/catalog facts from existing authoritative metadata; verify published package claims separately.
+- Preserve important runtime and data-safety differences. Remove build-pipeline narration from developer pages.
+- Use real code examples and honest verification levels. Preserve meaningful checks while removing assertions tied only to the old wording or layout.
+- Reuse Fumadocs and its Radix-based components; review desktop/mobile screenshots and keyboard behavior after implementation.
+
+## Rebase review — 2026-09-29
+
+Revisited the requested examples against their current public docs:
+
+- [Turso TypeScript quickstart](https://docs.turso.tech/sdk/ts/quickstart): installation, connection, and a working SQL example precede optional synchronization. Adaptation: start with one complete query, then persistence and application recipes.
+- [PGlite getting started](https://pglite.dev/docs/): host-specific setup stays next to code; filesystems, workers, tools, and upgrade guidance have separate destinations. Adaptation: keep browser headers and mobile seeds mandatory in quickstarts, and put placement choices in guides.
+- [Supabase React quickstart](https://supabase.com/docs/guides/getting-started/quickstarts/reactjs): follows a framework-specific path from setup to a rendered application. Adaptation: say where code runs and link the next application task rather than explaining SDK implementation layers.
+- [Motion React docs](https://motion.dev/docs/react): short installation and import path, examples, then individual feature guides. Adaptation: compact introductions, task headings, and visible API navigation without decorative diagrams.
+
+These are structural observations, not borrowed prose or claims that Oliphaunt supports their features. The installed `better-writing` skill governs the edit. Current source APIs and centralized checkout versions stay paired; completed publication is recorded separately.