Skip to content

Release published docs to main - #306

Open
lucas-tortora wants to merge 123 commits into
mainfrom
published
Open

lucas-tortora wants to merge 123 commits into
mainfrom
published

Conversation

@lucas-tortora

Copy link
Copy Markdown

Summary

  • Promotes the published branch to main, replacing the legacy docs site with the current published Pear docs platform.
  • Merged main into published with all conflicts resolved in favor of published.
  • This PR is intended to entirely overwrite main with published content.

Conflict resolution

Three modify/delete conflicts were resolved in favor of published (legacy files kept deleted; content lives under the new content/ IA):

  • guide/making-a-bare-mobile-app.md
  • guide/making-a-pear-desktop-app.md
  • guide/starting-a-pear-desktop-project.md

What's included

  • Complete information architecture reorg (getting-started, how-to, reference, explanation)
  • Pear book integration and route aliases
  • @tetherto/docs-seo-* end-to-end (metadata, sitemap, robots, JSON-LD, OG)
  • Docs lint CI (internal links, Vale prose linting)
  • Link checking, review fixes, and example annotation tooling
  • Publish and preview GitHub workflows

Test plan

  • Verify PR shows as mergeable into main
  • Confirm CI checks pass (docs lint, build)
  • Spot-check key pages after merge: index, getting-started, reference sidebar

Made with Cursor

Didericis and others added 8 commits January 9, 2026 13:12
- modify youtube links
- modify gitignore
- modify featured table
* adjust pear init for GUI apps (#270)

* adjust other instance of pear init description

* feat: add pear book

- modify youtube links
- modify gitignore
- modify featured table

* Add pear book action

* Add publish and preview workflows

* Refactor preview workflow

* add route aliases for pear book

* reorder reference sidebar links

* move all pear-book config to file

* add guide alias/change prefix

* Publish

* Feat/rebase upstream deprecated run (#278)

* deprecate run

* cascading implications

* missing cmds, runtime tweaks, deployment stub

* add fumadocs
replace GB syntax

* fix: update logo and fav icon

* fix : update file to .mdx and update imege to use react component

* fix: replace raw HTML syntax with markdown in reference docs to md syntax

* chore: remove guide sectionto match deprecate-run upstream

* fix: remove refrence guides to match refernce on depercate-run upstream

* fix: restore mark syntax and rename reference files to .mdx

* fix: add pearpass.svg

* fix: center align showcase image

* fix: soften stable and deprecated badge colors for dark mode readability

* fix: align DEPRECATED marks with upstream, use plain bold syntax

* fix: update source map to reflect .mdx renames and remove guide directory

* fix: remove dead links from index.mdx

* fix: align system column icons horizontally

* fix: link to use url path approach

* fix: refine stability badge styles across reference docs

* fix: orama search

* fix: revert anchor syntax from [#id] to <a name> in mdx/md files

* fix: replace deprecated mark badges with **DEPRECATED** and fix anchor syntax across docs

* fix: update README

* fix: convert relative .md links to url paths and fix nested anchor hydration error

* feat: link checkers

---------

Co-authored-by: davidmarkclements <david.mark.clements@gmail.com>
Co-authored-by: Lucas Tortora <lucas.tortora@tether.io>

* feat(docs): information architecture reorg + cross-linking quality gates (#281)

* content: rename .md to .mdx and add Diátaxis docType / schemaType frontmatter

Fumadocs MDX needs the .mdx extension to compile JSX/MDX content; the .md
loader path doesn't run the MDX pipeline, which silently broke things like
JSX comments and component embeds.

While renaming, add the @tetherto/docs-seo-schema frontmatter so JSON-LD
@type values, the sitemap, and the Diátaxis classification land correctly
without warnings:

  - docType:    explanation | how-to | reference | faq
  - schemaType: WebPage | TechArticle | APIReference

The schemaType per page follows the docType -> @type mapping the schema
package documents (reference -> APIReference for upstream API surfaces,
how-to -> TechArticle for procedural docs, etc.). Four reference docs
that are actually procedural (deployment, migration, recommended-practices,
troubleshooting) were reclassified to docType: how-to.

deployment.mdx also gets its trailing HTML comment converted to a JSX
comment so MDX compilation succeeds.

Made-with: Cursor

* build: install @tetherto/docs-seo-* from GitHub Packages

The @tetherto/docs-seo-* SEO toolkit is published to GitHub Packages
under the npm.pkg.github.com registry rather than the public registry.
This adds the consumer-side wiring needed to install it cleanly.

  .npmrc          - point the @tetherto scope at npm.pkg.github.com and
                    read the auth token from \${GITHUB_TOKEN} at install
                    time (matches the convention already used across the
                    org, e.g. qvac's run-lint-and-unit-tests action).

  .env.example    - document GITHUB_TOKEN (required for npm install) and
                    every SEO env var the @tetherto/docs-seo-* packages
                    consume (NEXT_PUBLIC_DOCS_ORIGIN, SKIP_OG_BUILD,
                    DOCS_OG_*, DOCS_SEO_QUIET_GENERATED, DOCS_SEO_SILENT).

  README.md       - explain why npm install needs GITHUB_TOKEN exported
                    in the shell (npm reads .npmrc with process env, not
                    .env files) and link to docs-template's README for
                    the full PAT flow (scopes / expiration / SSO).

Made-with: Cursor

* feat(seo): wire @tetherto/docs-seo-* end-to-end

Replace the previous ad-hoc OG handler / hand-rolled metadata with the
@tetherto/docs-seo-* packages so the docs ship full structured SEO:
canonical URLs, Open Graph + Twitter cards, JSON-LD per page, sitemap
with <lastmod>, robots.txt with bot allow/deny lists, and pre-rendered
Takumi OG images for every MDX page.

Build / deps
  package.json         - add @tetherto/docs-seo-{schema,core,next,og},
                         @takumi-rs/image-response, zod, @fontsource/poppins,
                         tsx, serve. Add prebuild + build:og scripts that
                         run the Takumi prebuild before next build, and
                         keep tsx in NODE_OPTIONS for next build/dev so
                         source.config.ts can import @tetherto packages
                         shipped as raw .ts (Node's native type stripping
                         refuses to strip files under node_modules).
                         Switch to "type": "module".
  next.config.mjs      - transpilePackages for the four @tetherto/docs-seo-*
                         packages (Next has to compile their TS sources).

Schema / source
  source.config.ts     - extend Fumadocs frontmatterSchema with
                         tetherSeoFrontmatterSchema; install
                         fumadocs-mdx/plugins/last-modified with a custom
                         git resolver that --follows .md -> .mdx renames
                         and falls back to HEAD on shallow clones (Sevalla
                         and other managed CIs do shallow checkouts).
  src/lib/source.ts    - drop local getPageImage; OG image URLs now come
                         from @tetherto/docs-seo-og.

App routes / metadata
  src/lib/seo-config.ts                       - centralized DocsSeoConfig
                                                (origin, siteName, publisher,
                                                trailingSlash). Default
                                                origin is localhost:8080 to
                                                match the serve script.
  src/app/(docs)/[[...slug]]/page.tsx         - generateMetadata via
                                                buildDocsMetadata + JSON-LD
                                                via DocsJsonLd; OG image
                                                from getPageImage (or
                                                staticOgImagePath when
                                                SKIP_OG_BUILD=1).
  src/app/sitemap.ts                          - buildDocsSitemap (new).
  src/app/robots.ts                           - buildDocsRobots (new).
  src/app/layout.tsx                          - bump default origin to
                                                localhost:8080 to match
                                                seo-config.
  src/app/og/docs/[...slug]/route.tsx         - removed; replaced by the
                                                static prebuild below.

Takumi OG prebuild
  scripts/generate-takumi-og.tsx              - precomputeTakumiOgImages
                                                with a Pear-branded
                                                ImageResponse template
                                                (logo + title on one row,
                                                description below, brand
                                                colors and Poppins fonts
                                                matching the docs site).
                                                Loads pear-1.svg as a base64
                                                data URL and Poppins woffs
                                                from @fontsource so renders
                                                are deterministic (no
                                                network fetch at build).

Frontmatter
  content/index.mdx                           - docType: explanation,
                                                schemaType: WebPage
  content/reference/{api,cli,configuration}.mdx
                                              - docType: reference,
                                                schemaType: APIReference

Verified live (npm run build && npm run serve):
  - /sitemap.xml: 33 urls, all with <lastmod>
  - /robots.txt: well-formed, GPTBot / Google-Extended disallowed
  - JSON-LD on every page (Organization publisher + page schemaType)
  - 33 Takumi OG webp images at /og/docs/<slug>/image.webp
  - 0 [@tetherto/docs-seo] warnings under DOCS_SEO_QUIET_GENERATED=1

Made-with: Cursor

* chore: drop legacy Pear Book artifacts and untrack generated Fumadocs caches

  .gitignore                          - replace `.docusaurus` (legacy from
                                        the Docusaurus era) with the actual
                                        Fumadocs / Next caches: `.out`,
                                        `.source`, `.next`. Add
                                        `/public/og/docs/` so Takumi
                                        prebuild output stays out of git.
  .source/{browser,dynamic,server,
           source.config.mjs}         - untrack; fumadocs-mdx regenerates
                                        these on postinstall, so keeping
                                        them tracked just produced perpetual
                                        diff noise.
  .pear-book.json                     - remove; the Pear Book HTML doc
                                        builder is fully superseded by the
                                        Fumadocs site.
  .github/workflows/preview.yml       - remove; only consumed .pear-book.json
                                        / `pear-book build` and was already
                                        producing dead `preview` branches.
  next-env.d.ts                       - update routes types path
                                        (out/dev/types -> .next/types) to
                                        match Next 16's typegen output.

Made-with: Cursor

* chore(seo): address PR #280 review feedback

- Rename `scripts/generate-takumi-og.tsx` -> `scripts/generate-og.tsx` so the
  OG prebuild entrypoint is engine-agnostic; Takumi remains the current
  backend but the script / npm scripts no longer need to be renamed if it
  is swapped. Update `package.json` (`prebuild`, `build:og`) and the
  `.env.example` reference.

- `src/app/layout.tsx`: read `metadataBase` via `getDocsSeoConfig()`
  instead of duplicating the `NEXT_PUBLIC_DOCS_ORIGIN ?? NEXT_PUBLIC_SITE_URL
  ?? localhost:8080` fallback. Now consistent with `sitemap.ts`, `robots.ts`,
  and the docs page route, which all use the helper.

- `.env.example`: document `NEXT_PUBLIC_SITE_URL` as an accepted fallback
  alongside the preferred `NEXT_PUBLIC_DOCS_ORIGIN`.

Made-with: Cursor

* docs(adr): adopt Diátaxis IA — quadrant decisions + FAQ resolution

Records the design rationale for the IA reorganization landing in this
branch. The actual file moves, redirects, validators, and content
rewrites follow in subsequent commits, each mapped 1:1 to an Asana
subtask under https://app.asana.com/1/1204330682799323/task/1214311360861492.

Key decisions captured:

* Top-level structure collapses to the four canonical Diátaxis
  directories under content/: tutorials/, how-to/, reference/,
  explanation/. The current building-blocks/, helpers/, tools/ become
  reference/{building-blocks,helpers,tools}/. The four how-to-tagged
  pages physically misfiled in reference/ (deployment, troubleshooting,
  recommended-practices, migration) move out into how-to/.

* The FAQ is deconstructed, not relocated. Each Q&A is rewritten into
  the quadrant it actually belongs to; reference/faq.mdx is then
  deleted. This is the most editorially expensive option but the only
  one that fixes the underlying mixed-quadrant problem (Diátaxis treats
  FAQ as an anti-pattern).

* URL stability uses a belt-and-suspenders approach because
  next.config.mjs has output: 'export' (which means redirects() does
  not run at request time): static HTML redirect stubs at every old
  path AND a Sevalla-side _redirects file shipped in this PR. Stubs
  cover any host immediately; hosting-layer 308s take over once the
  next deploy lands. An E2E redirect test prevents regression.

* A new scripts/check-doctypes.ts enforces the dir <-> docType
  invariant in CI (e.g. content/how-to/** must have docType: how-to)
  so the IA can't drift back. Wires into the existing
  npm run check:internal-links flow.

* SUMMARY.md (root) is dropped in subtask 8 — GitBook-era artifact
  pointing at .md paths that no longer exist; Fumadocs ignores it.

Naming follows Diátaxis canon: directories are tutorials/ (plural),
how-to/, reference/, explanation/. The schema docType enum uses the
singular tutorial; the validator knows the dir<->docType mapping.

Out of scope deliberately: the optional Diátaxis quadrant badge in
page headers (defer to a follow-up; this PR is already large), and
URL changes for reference/{api,cli,configuration,runtime} (they stay
put).

Stored in decisions/ rather than content/ so the ADR doesn't get
published to the docs site.

Made-with: Cursor

* content: rename howto -> how-to and move misfiled how-tos out of reference

Subtask 2 of the Diátaxis IA reorganization (decisions/0001).

Renames the canonical how-to directory to its hyphenated form
(content/howto -> content/how-to) and moves the four reference docs
that were already tagged docType: how-to into it. The frontmatter is
unchanged; only the paths move. After this commit, every page tagged
docType: how-to lives under content/how-to/.

Moves (10 files):
  howto/connect-two-peers-by-key-with-hyperdht.mdx          -> how-to/...
  howto/connect-to-many-peers-by-topic-with-hyperswarm.mdx  -> how-to/...
  howto/replicate-and-persist-with-hypercore.mdx            -> how-to/...
  howto/work-with-many-hypercores-using-corestore.mdx       -> how-to/...
  howto/share-append-only-databases-with-hyperbee.mdx       -> how-to/...
  howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.mdx
                                                            -> how-to/...
  reference/deployment.mdx                                  -> how-to/...
  reference/troubleshooting.mdx                             -> how-to/...
  reference/recommended-practices.mdx                       -> how-to/...
  reference/migration.mdx                                   -> how-to/...

Internal-link rewrites in the same commit so the build stays green
and `npm run check:internal-links` passes between commits (no broken-
build window before redirects land in subtask 6):
  content/index.mdx                                  9 links updated
  content/how-to/connect-to-many-peers-...mdx        1 link
  content/how-to/replicate-and-persist-...mdx        2 links (in-quadrant)
  content/how-to/work-with-many-hypercores-...mdx    1 link
  content/reference/runtime.mdx                      1 link (-> /how-to/deployment)
  content/reference/api.mdx                          1 link (-> /how-to/migration)

Verified:
  - npm run check:internal-links: ✅ 33 files, all internal links valid
  - npm run build: ✅ static export clean, 0 warnings
  - sitemap.xml: 33 urls, 10 under /how-to/, 0 stale /reference/(deployment|
    troubleshooting|recommended-practices|migration) entries.
  - lastmod: falls back to HEAD commit time today; after this commit lands,
    fumadocs-mdx/plugins/last-modified --follow will resolve to each
    page's original commit time (the resolver in source.config.ts walks
    .md -> .mdx -> howto -> how-to renames).

Old paths are intentionally NOT yet redirected; that lands in subtask 6
(`feat(redirects): 308s for legacy paths via static stubs and hosting
rules`). External links will 404 in the interim, which is expected on a
local-only / preview-branch build.

src/lib/tree.ts still references /howto/ urls but is dead code (never
imported; sidebar comes from source.getPageTree()). It's deleted in
subtask 8 alongside the legacy SUMMARY.md.

Made-with: Cursor

* content: nest building-blocks/helpers/tools under reference/

Subtask 3 of the Diátaxis IA reorganization (decisions/0001).

Three top-level directories that were always reference content move
to where they belong:

  content/building-blocks/  ->  content/reference/building-blocks/   (6 files)
  content/helpers/          ->  content/reference/helpers/           (6 files)
  content/tools/            ->  content/reference/tools/             (5 files)

After this commit, the only top-level directories under content/ are
the four Diátaxis quadrants (`how-to/`, `reference/`) plus the upcoming
`tutorials/` and `explanation/` (added in subtask 4).

Pure path move — no internal-link rewrites needed inside content/. A
precise grep (\(/building-blocks/, \(building-blocks/, href="..." etc.)
returned zero matches: every reference to a building block / helper /
tool in pear-docs prose links to its external GitHub repo
(https://github.com/holepunchto/<name>), not the internal docs page.
The homepage's giant module tables (lines 190–250+) are entirely
external links.

Verified:
  - npm run check:internal-links: ✅ 33 files, all valid
  - npm run build: ✅ static export clean, 0 warnings
  - sitemap.xml: 33 urls
      0  stale top-level /(building-blocks|helpers|tools)/ paths
      17 nested /reference/(building-blocks|helpers|tools)/ paths
      16 unaffected (homepage, /how-to/*, /reference/{api,cli,configuration,runtime,faq})

src/lib/tree.ts still has stale /building-blocks/, /helpers/, /tools/
URLs but is dead code (never imported). Deleted in subtask 8.
Old paths are not yet redirected; static-export 308 redirects + Sevalla
rules land in subtask 6.

Made-with: Cursor

* content: add quadrant landing pages for how-to / reference / explanation

Subtask 4 of the Diátaxis IA reorganization (decisions/0001).

Adds an index.mdx for three of the four quadrants. Pages are
intentionally small ("draft, polish later" per the option C
checkpoint) — just enough to:

  1. Define the quadrant in Diátaxis terms.
  2. Cross-link to the other quadrants so readers self-route.
  3. List the pages currently in each quadrant.
  4. Leave a JSX-comment template hint for future authors.

Files added (3):
  content/how-to/index.mdx        Defines how-to vs tutorial; lists all
                                  10 current pages, grouped into
                                  "Building peer-to-peer apps" (the 6
                                  P2P recipes) and "Operating a Pear
                                  application" (the 4 docs that moved
                                  out of reference/ in subtask 2).
  content/reference/index.mdx     Defines reference; lists CLI / runtime
                                  / configuration / api, then inlines
                                  links to all 17 sub-pages under
                                  building-blocks/, helpers/, tools/.
                                  Notes that the FAQ is being
                                  deconstructed (subtask 9).
  content/explanation/index.mdx   "coming soon"; lists planned topics
                                  (What is Pear?, Peer-to-peer
                                  demystified, Append-only logs are a
                                  database, The runtime model, Bare vs
                                  Node). Notes that FAQ entries
                                  answering "what is X?" / "why X?"
                                  land here as part of the FAQ
                                  deconstruction.

Tutorials quadrant is intentionally NOT created in this commit. It's
been hidden until we have actual tutorial content. The cross-links
that would point to /tutorials in the three index pages above are
JSX-commented inline, with a re-enable note next to each:

  {/* Tutorials quadrant is hidden until we have actual tutorials.
      Re-add this leading clause when content lands: ... */}

When tutorials are written (Pear For Dummies / Pear Conventions / P2P
from Scratch — see the ADR), the quadrant comes back: create
content/tutorials/index.mdx and uncomment the three references. The
ADR's long-term plan is unchanged; this commit just defers the
quadrant landing.

Frontmatter for the 3 index pages:
  - description set on all (required by docs-seo schema; build is
    free of [@tetherto/docs-seo] warnings).
  - docType matches the directory: how-to / reference / explanation.
    The validator added in subtask 7 will enforce this.
  - schemaType: WebPage on how-to + explanation; APIReference on
    reference/ since it's the gateway to the API descriptions.

Two iterations during write-up:

1. An early draft of reference/index.mdx linked to
   /reference/building-blocks, /reference/helpers, /reference/tools as
   parent-pages, but those directories have no index.mdx. The link
   checker caught it; switched to inline listings only. Adding sub-
   directory landing pages is a one-liner if any of those subdirs grow
   large enough to warrant one (e.g. when each has 20+ entries).

2. The link checker (scripts/check-internal-links.ts via
   scripts/helpers.ts) text-scans for [text](/url) markdown patterns,
   so "commented-out" links inside {/* ... */} were still flagged as
   broken. Added a one-line strip of JSX comments before regex matching
   in extractLinks(). JSX comments don't render anyway, so links
   inside them shouldn't fail the check — this is a generally useful
   improvement for any "re-enable later" pattern in our docs.

Verified: - npm run check:internal-links: ✅ 36 files, all valid.
  - npm run build: ✅ static export clean, 0 warnings.
  - sitemap.xml: 36 urls (33 content + 3 new index pages, no /tutorials).
Made-with: Cursor

* content(index): rewrite homepage as four-quadrant launcher; move module tables to reference/

Subtask 5 of the Diátaxis IA reorganization (decisions/0001).

The old content/index.mdx (288 lines) was a hybrid: a short intro,
nine link bullets, and ~270 lines of giant module tables (Pear app /
UI / common / dev / integration libraries, P2P building blocks,
~50 bare-* modules, and CLI tools — roughly 100 external-GitHub-link
table rows in total). The result was a homepage where the catalog
swallowed the orientation; readers had to scroll through five tables
to find a Diátaxis-style entry point.

New homepage (87 lines, target was 150):

  Sections, in order:
    - Title + tagline + intro (intent unchanged from before).
    - Showcase (Keet, PearPass) — kept verbatim, useful.
    - "Where do you want to go?" — the four-quadrant launcher.
      Three cards visible (How-to / Reference / Explanation), each a
      heading + ~2 sentence quadrant definition + bold "Browse →"
      link to the quadrant's index page.
    - Stability legend — kept (used across reference pages).
    - Glossary — replaces the old "Terms" block; same content, name
      change for clarity.
    - Examples — kept (4 GitHub links to runnable examples).
    - Module catalog pointer — short paragraph that points readers at
      /reference/modules and /reference/bare-modules instead of inlining
      the tables here.

Tutorials quadrant card sits in a JSX comment (option C from the
earlier checkpoint). When the first tutorials land, uncomment 8 lines
and the four-card launcher restores. The card is fully populated
(definition, link to /tutorials, "learn by doing" subtitle) so the
re-enable is a no-edit copy-out-of-comment.

New file content/reference/modules.mdx (95 lines):
  - Pear application libraries (8 modules)
  - User interface libraries (2 modules)
  - Common libraries (10 modules)
  - Developer libraries (2 modules)
  - Integration libraries (15 modules)
  Plus a "Related" cross-link block at the bottom (bare-modules,
  building-blocks, helpers, tools).

New file content/reference/bare-modules.mdx (79 lines):
  Single big bare-* table (~50 entries) — too large for the homepage
  AND conceptually distinct from pear-* (Bare is a separate runtime).
  Lives on its own page per the option C scope decision; reachable
  from the reference index, the modules page, and the homepage's
  module-catalog pointer.

Cross-link from content/reference/index.mdx — added a "Module catalog"
sub-section pointing at the two new pages.

Cleanup applied to the extracted tables:
  - Stripped 7 stale <a name="..."></a> HTML anchors (GitBook-era
    in-page TOC links the old homepage relied on; Fumadocs auto-
    generates anchors from headings, so they were dead weight).
  - Promoted the bare-modules.mdx top heading from ### to # (it's a
    standalone page now, not a section of the homepage).
  - Renamed the modules.mdx top section from "### Pear Modules" to
    "# Modules" (page title comes from frontmatter; no "Pear" prefix
    needed since the URL says /reference/modules).
  - Demoted "#### Application Libraries" etc. to "## Application
    libraries" (one heading level less; page-title-cased).
  - Removed a duplicate intro paragraph that survived the extraction
    in bare-modules.mdx.

Tools section from the old homepage (lines 277-288) was NOT migrated.
The 5 tools (Hypershell, Hypertele, Hyperbeam, Hyperssh, Drives) all
have full reference pages under /reference/tools/, and the reference
index already lists them; the homepage table was redundant.

Frontmatter on both new pages:
  - description set (required by docs-seo schema; build runs clean).
  - docType: reference; schemaType: APIReference (these are catalogs
    of API-shaped artifacts, even if each row links externally).
  - The validator added in subtask 7 will accept both since they're
    under content/reference/.

Verified:
  - npm run check:internal-links: ✅ 38 files, all internal links valid.
  - npm run build: ✅ static export clean, 0 warnings.
  - sitemap.xml: 38 urls (was 36; +2 for /reference/modules and
    /reference/bare-modules). The homepage URL ('/') is unchanged.
  - Homepage: 87 lines, down from 288. No /tutorials links rendered.

Old paths NOT yet redirected:
  /#pear-modules, /#bare-modules, /#tools etc. (homepage in-page
  anchors). These were used by external links and the old TOC at the
  top of the homepage. Subtask 6 wires up redirects for legacy paths
  generally; in-page anchors on the same URL are a separate concern
  and probably best handled by adding a heading-level anchor on the
  homepage that mirrors the old #showcase / #legend names. Adding a
  TODO note for subtask 6.

Made-with: Cursor

* feat(redirects): 308s for legacy IA paths via static stubs and hosting rules

Subtask 6 of the Diátaxis IA reorganization (decisions/0001).

Reader bookmarks and external links to the old paths
  /howto/...                  /reference/{deployment,migration,...}
  /building-blocks/...        /helpers/...           /tools/...
need to keep working after the IA shape change. Pear-docs builds with
`output: 'export'` in next.config.mjs, which means Next.js's redirects()
config is silently ignored at request time (no Node runtime to honor it
on; it only fires during `next dev`). So we use a belt-and-suspenders
approach (option C in the decision checkpoint).

Architecture (scripts/redirects.ts is the single source of truth):

  1. Static HTML stubs at every legacy path. A postbuild step emits
     out/<from>/index.html with `<meta http-equiv="refresh">` +
     `<link rel="canonical">` to the new URL, plus a `<meta name=
     "robots" content="noindex">` so search engines don't index the
     duplicate. Browsers redirect immediately. Search engines treat
     sustained meta-refresh redirects as 301-equivalent. Works on any
     static host, zero deploy-side config.

  2. Hosting-layer 308 rules in out/_redirects. Sevalla / Netlify /
     Cloudflare-Pages compatible 3-column format
     ("<from> <to> <status>"), one line per redirect. Once the next
     deploy lands, the host returns true 308s and the HTML stubs become
     a defensive fallback rather than the primary mechanism.

  3. next.config.mjs redirects() listing the same patterns for `next
     dev` and as in-source documentation. `output: 'export'` ignores
     them at build time (this is fine; the postbuild stubs +
     _redirects file cover production).

The redirect list is DERIVED FROM THE FILESYSTEM rather than hardcoded.
buildRedirects() in scripts/redirects.ts walks content/how-to,
content/reference/{building-blocks,helpers,tools}, and explicitly
enumerates the 4 misfiled how-tos that moved out of content/reference/.
Net effect: when a new how-to lands at content/how-to/<slug>.mdx, a
/howto/<slug>/ -> /how-to/<slug>/ stub is emitted automatically next
build, no script edit needed. Same for building-blocks/helpers/tools.

Today the build emits 27 redirects:
  6  /howto/<slug>/                  -> /how-to/<slug>/
  4  /reference/<misfiled>/          -> /how-to/<misfiled>/
       (deployment, troubleshooting, recommended-practices, migration)
  6  /building-blocks/<slug>/        -> /reference/building-blocks/<slug>/
  6  /helpers/<slug>/                -> /reference/helpers/<slug>/
  5  /tools/<slug>/                  -> /reference/tools/<slug>/

E2E test (scripts/check-redirects.ts, run via `npm run check:redirects`).
For each redirect derived from buildRedirects(), asserts:

  1. out/<from>/index.html exists.
  2. The HTML contains `meta http-equiv="refresh" content="0; url=<to>"`.
  3. The HTML contains `link rel="canonical" href="<to>"`.
  4. out/_redirects contains the line `<from> <to> 308`.

Failure mode: if the postbuild step regresses or if scripts/redirects.ts
silently produces fewer entries than expected, this checker flags it.
Designed to slot into CI alongside check:internal-links so the IA
can't drift back.

URLs always carry a trailing slash to match next.config.mjs's
`trailingSlash: true` (which is what next-export emits in out/).

Files:
  scripts/redirects.ts                  - shared map builder + stub HTML
  scripts/generate-redirect-stubs.ts    - postbuild emitter
  scripts/check-redirects.ts            - CI-friendly E2E verifier
  next.config.mjs                       - +redirects(), +intent comment
  package.json                          - +postbuild, +check:redirects

Verified:
  - npm run build: ✅ static export clean; postbuild emits "Wrote 27
    redirect stubs and out/_redirects (27 rules)".
  - npm run check:redirects: ✅ 27 redirects, 54 assertions per row + 1
    _redirects file presence check; all pass.
  - npm run check:internal-links: ✅ 38 files, all internal links valid
    (the redirect stubs are in out/, not content/, so the checker
    correctly ignores them — internal links should always point at the
    NEW paths).
  - Sample stub /howto/connect-two-peers-by-key-with-hyperdht/index.html
    inspected: meta-refresh, canonical link, noindex, trailing slash on
    target URL — all correct.

Out of scope here:
  - Homepage in-page anchors (#pear-modules, #bare-modules, etc.) that
    moved to /reference/modules and /reference/bare-modules in subtask
    5. Those are URL-fragment changes on the same path, which neither
    HTML stubs nor _redirects can target. If we want to honor them,
    add heading IDs on the homepage that mirror the old anchor names.
    Punted to subtask 8 / a follow-up.
  - Bare modules table inside the old homepage was duplicated by
    /reference/bare-modules already; that's covered by the homepage
    rewrite, not by a redirect.

Made-with: Cursor

* content: hide Explanations quadrant until conceptual content lands

The Explanations quadrant has no pages yet — the index was a "Coming
soon" stub listing planned topics (What is Pear?, P2P demystified,
Append-only logs as a database, etc.). Per the user's call, hide the
quadrant entirely so it doesn't show in the sidebar, sitemap, or any
cross-references until real content exists.

What's hidden:
- content/explanation/index.mdx removed; the directory is gone.
- content/index.mdx homepage card for Explanations is wrapped in a JSX
  comment, mirroring the existing Tutorials hide. The replacement copy
  uses the plural "Explanations" so the form is right whenever the
  quadrant returns.
- content/how-to/index.mdx: the trailing "For the conceptual 'why,'
  see [Explanation]" clause moves into a JSX comment with restoration
  text. The leading Tutorials clause was already hidden.
- content/reference/index.mdx: the trailing "For the design rationale,
  see [Explanation]" clause same treatment. Also tightens the FAQ
  deconstruction note so it doesn't promise links to a quadrant that
  doesn't exist yet.

Why JSX comments instead of deletion: every hidden block carries the
exact prose to restore when the quadrant ships, so re-enabling is a
mechanical "uncomment and remove the wrapper" — no archeology.

Verification:
- sitemap.xml: 37 URLs (down from 38), zero /explanation/ entries.
- check:internal-links: clean.
- check:redirects: clean.

See decisions/0001-adopt-diataxis-ia.md §4 ("Quadrant content scope")
for the rule: a quadrant is only visible when it has at least one
substantive page beyond the index.

Made-with: Cursor

* content: rename "How-to guides" -> "How To", drop redundant prefix from titles, regroup by topic

Three threads in one commit because they're a single coherent IA
naming pass:

1) Section label rename: "How-to guides" -> "How To".
   Shorter, scans cleaner in nav, and matches the user's preferred
   form. Touched in: content/index.mdx (homepage card heading + browse
   link), content/how-to/index.mdx (frontmatter title), and
   content/reference/index.mdx (cross-reference). The body intro on
   how-to/index.mdx becomes "How-tos are goal-oriented recipes" — the
   "how-to" lowercase descriptor stays everywhere it isn't acting as a
   section name.

2) Page titles become imperative-only.
   Diátaxis style for how-tos is "do X", not "how to do X" — the
   "how-to" framing is the section, not the title. So:
     "How to connect two Peers by key with Hyperdht"
       -> "Connect two peers by key with HyperDHT"
     "How to connect to many peers by topic with Hyperswarm"
       -> "Connect to many peers by topic with Hyperswarm"
     "How to replicate and persist with Hypercore"
       -> "Replicate and persist with Hypercore"
     "How to work with many Hypercores using Corestore"
       -> "Work with many Hypercores using Corestore"
     "How to share Append-Only Databases with Hyperbee"
       -> "Share append-only databases with Hyperbee"
     "How to create a full peer-to-peer filesystem with Hyperdrive"
       -> "Create a full peer-to-peer filesystem with Hyperdrive"
   Also fixes module-name capitalization that was inconsistent
   ("Hyperdht" -> "HyperDHT", "Append-Only Databases" -> "append-only
   databases", etc.).

   The four operational how-tos had bare-noun titles which read like
   reference pages, not actions. Per the user's call (asym_recommen-
   dations option):
     "Deployment"           -> "Deploy your application"
     "Migration"            -> "Migrate to a new release"
     "Recommended Practices"-> "Apply recommended practices"
     "Troubleshooting"      -> "Troubleshoot common issues"

3) Listing on /how-to/ regrouped by topic, not by audience.
   The previous split was "Building peer-to-peer apps" vs "Operating
   a Pear application", which matched what the pages cover but
   collapsed all six core-primitive how-tos into one bucket. The new
   grouping (by_module option) makes the table of contents teach the
   shape of the building blocks too:
     - Connecting peers      (HyperDHT, Hyperswarm)
     - Storage and replication (Hypercore, Corestore, Hyperbee, Hyperdrive)
     - Operating an app      (deployment, migration, recommended-
                              practices, troubleshooting)
   The listing still uses flat /how-to/<slug>/ URLs in this commit;
   the topic prefix becomes part of the URL in the next commit.

What's intentionally NOT in this commit:
- File moves into topic subdirs and the redirect rewire — that's a
  cleanly separable change with its own test surface, so it lives in
  the next commit.
- Any prose changes inside the 10 how-to bodies — frontmatter only.

Verification:
- check:internal-links: clean (37 files).
- build: clean, 37 sitemap URLs, no warnings.
- check:redirects: clean (27 redirects, destinations unchanged).

See decisions/0001-adopt-diataxis-ia.md §4 ("Quadrant content scope")
and §7 ("Page-title style: imperative for how-tos") for the rules.

Made-with: Cursor

* content: nest how-to pages under topic folders, rewire redirects single-hop

The /how-to/ quadrant grew flat: 10 sibling pages spanning two
unrelated areas (peer connection, storage replication) plus four
operations recipes. With the regroup landing in the previous commit
("Connecting peers" / "Storage and replication" / "Operating an app"),
the URL ought to mirror the sidebar grouping. So the pages move into
topic subdirs and the URLs deepen by one level.

What moved:
  content/how-to/connect-two-peers-by-key-with-hyperdht.mdx
    -> content/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht.mdx
  content/how-to/connect-to-many-peers-by-topic-with-hyperswarm.mdx
    -> content/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm.mdx
  content/how-to/replicate-and-persist-with-hypercore.mdx
    -> content/how-to/store-and-replicate/replicate-and-persist-with-hypercore.mdx
  content/how-to/work-with-many-hypercores-using-corestore.mdx
    -> content/how-to/store-and-replicate/work-with-many-hypercores-using-corestore.mdx
  content/how-to/share-append-only-databases-with-hyperbee.mdx
    -> content/how-to/store-and-replicate/share-append-only-databases-with-hyperbee.mdx
  content/how-to/create-a-full-peer-to-peer-filesystem-with-hyperdrive.mdx
    -> content/how-to/store-and-replicate/create-a-full-peer-to-peer-filesystem-with-hyperdrive.mdx
  content/how-to/deployment.mdx
    -> content/how-to/operate-an-app/deployment.mdx
  content/how-to/migration.mdx
    -> content/how-to/operate-an-app/migration.mdx
  content/how-to/recommended-practices.mdx
    -> content/how-to/operate-an-app/recommended-practices.mdx
  content/how-to/troubleshooting.mdx
    -> content/how-to/operate-an-app/troubleshooting.mdx

All moves are git-tracked renames (status R / RM), so blame follows.

Folder naming: imperative-verb-phrase to match the page titles' style
("connect-to-peers/" mirrors "Connect two peers by key with HyperDHT").
The nouns-form ("connecting-peers/", "operating-an-app/") was rejected
to keep the convention parallel.

Internal cross-links rewired (18 in 6 files):
  content/how-to/index.mdx                         (10 listing URLs)
  content/how-to/store-and-replicate/replicate-and-persist-with-hypercore.mdx (3)
  content/how-to/store-and-replicate/work-with-many-hypercores-using-corestore.mdx (1)
  content/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm.mdx (1)
  content/reference/api.mdx                        (2 — migration#compat-mode)
  content/reference/runtime.mdx                    (1 — deployment)

Redirect strategy: single hop to the final nested destination.
Everyone with a legacy bookmark (/howto/<slug>/ or /reference/<misfiled>/)
should land at /how-to/<topic>/<slug>/ in one redirect, not two.
The "remap_legacy" option from the consult, picked over "add inter-
mediate /how-to/<slug>/ stubs too" — this branch hasn't shipped, so
no external links to the unmerged flat /how-to/<slug>/ URLs exist.

scripts/redirects.ts now walks content/how-to/<topic>/<slug>.mdx (via
buildHowToTopics) and looks the topic up per-slug at build time, so
new how-tos automatically get a redirect for free as long as a legacy
URL is meaningful for them. The MISFILED_HOWTOS set still exists
because /howto/deployment/ never existed (legacy was /reference/deploy-
ment/), so we need to know which prefix to emit.

next.config.mjs's redirects() can't use a single-wildcard rule any
more (the destination's topic prefix depends on the slug), so it
expands to ten explicit per-slug rules. Only matters in `next dev`;
production redirects come from the static stubs and _redirects file.

Verification:
- check:internal-links: 37 files, all clean.
- build: clean export, 37 sitemap URLs, 10 of them under
  /how-to/<topic>/<slug>/.
- check:redirects: 27 redirects, 54 assertions per row, all single-hop
  to the new deeply-nested destinations:
    /howto/connect-two-peers-by-key-with-hyperdht/
      -> /how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht/  (308)
    /reference/deployment/
      -> /how-to/operate-an-app/deployment/  (308)

See decisions/0001-adopt-diataxis-ia.md §6 (redirects under static
export) and §7 (page-title style: imperative for how-tos) for context.

Made-with: Cursor

* feat(check-doctypes): enforce dir <-> docType invariants

Adds scripts/check-doctypes.ts and an `npm run check:doctypes` script
that walks content/**/*.mdx and asserts each page's frontmatter
docType matches the Diátaxis quadrant it lives in. The map is the
ADR's §8 invariant:

  content/index.mdx      -> docType: explanation  (site-root special case)
  content/tutorials/**   -> docType: tutorial
  content/how-to/**      -> docType: how-to
  content/reference/**   -> docType: reference
  content/explanation/** -> docType: explanation

What this prevents: another /reference/deployment.mdx-style misfile
slipping in. The four pages that drove this rule (deployment,
migration, recommended-practices, troubleshooting) lived under
/reference/ but were tagged docType: how-to — exactly the kind of
drift CI now catches automatically.

Why a custom script vs. a content-collection plugin: pear-docs uses
fumadocs-mdx with @tetherto/docs-seo-schema's frontmatter validator,
which already validates the docType *enum*. What it can't validate is
"docType matches directory", which is a project-level rule, not a
schema rule. ~80 lines of TS is cheaper than wiring a Fumadocs plugin
for a one-off invariant.

Implementation:
- expectedDocType(file) computes the required docType from the path.
- readDocType(file) extracts the value with a forgiving regex that
  accepts the three YAML forms in the wild (bare word, single-quoted,
  double-quoted) — same set fumadocs-mdx accepts.
- TEMPORARY_EXEMPTIONS allows content/reference/faq.mdx to keep its
  docType: faq for now. Subtask 9 will deconstruct the FAQ and delete
  this entry, after which the set is empty and any future drift fails
  CI.
- Files outside the four quadrants and not the root index are reported
  as "unscoped" (warning only, no failure) — this is so a refactor
  branch with a scratch file in content/ doesn't break CI.

Verification:
  npm run check:doctypes
  -> "Checked 37 files (1 exempted, 0 unscoped) ✅"

Negative test (covered in code review, not committed):
  Flip docType: how-to -> docType: explanation in
  content/how-to/operate-an-app/deployment.mdx -> validator fails with
  exit 1 and prints expected vs actual.

Wired as a sibling of check:internal-links / check:external-links /
check:redirects, runnable via `npm run check:doctypes`. Subtask 10
(final QA) wires it into the same CI step as the other checks.

See decisions/0001-adopt-diataxis-ia.md §8.

Made-with: Cursor

* chore: delete legacy SUMMARY.md and src/lib/tree.ts; refresh README

Two artifacts from the GitBook era + pre-Fumadocs sidebar both pointed
at filesystem layouts that no longer exist. They were dead weight and
actively misleading to anyone grepping for the canonical site structure.

Deletions
---------

SUMMARY.md (root, 73 lines) — GitBook table of contents listing every
page by its old `.md` path under `howto/`, `building-blocks/`,
`helpers/`, `tools/`. Fumadocs never read it (it derives the sidebar
from content/ filesystem + meta.json), so it had been an outdated
duplicate since the migration. Every path in it is now a redirect.

src/lib/tree.ts (262 lines) — hardcoded sidebar tree mirroring
SUMMARY.md, with module URLs like `/howto/...` and `/building-blocks/...`
plus references to pages that don't exist (`/guide/getting-started`,
`/reference/bare-overview`, `/reference/templates`,
`/reference/node-compat`). A grep for any module importing it returned
zero matches — confirmed dead code.

Both deletions are referenced in decisions/0001-adopt-diataxis-ia.md §9
("Cleanup of legacy artifacts").

README.md
---------

The README hadn't picked up the four IA-era scripts. Added:

- `npm run check:redirects` — verify redirect stubs + _redirects rules.
- `npm run check:doctypes`  — enforce dir<->docType invariants
                              (added in the previous commit).
- `npm run build:og`        — regenerate Open Graph images standalone.
- `npm run serve`           — clarified, was hand-rolled `npx serve out`.

Repository layout section refreshed to reflect today's tree:
- `decisions/` (ADRs) added.
- `out/` (build output) added with the "generated; not checked in" note.
- `scripts/` description expanded beyond "link checking".
- `content/` annotated with the Diátaxis-quadrant convention.

A short "Architectural decisions" pointer to the ADR folder so future
contributors can find the IA rationale without spelunking commit logs.

Out of scope (deliberately): sitemap labels, search index, takumi-og
paths. ADR §subtask-8 listed those, but per-file inspection confirmed
they're all path-dynamic — the sitemap is generated from the
content/ tree at build time, the Fumadocs search index is populated
the same way, and scripts/generate-takumi-og.tsx points at
`path.join(root, 'content')` and walks. None of them needed editing.

Verification
------------

  npm run check:doctypes        Checked 37 files (1 exempted) ✅
  npm run check:internal-links  Checked 37 files                 ✅
  npm run build                 clean static export, 37 sitemap URLs
  npm run check:redirects       27 redirects, 54 assertions      ✅

No `tree.ts` import anywhere (verified with rg before delete). No
SUMMARY.md reference outside the ADR (which mentions the deletion).

See decisions/0001-adopt-diataxis-ia.md §9.

Made-with: Cursor

* chore(faq): deconstruct /reference/faq into how-to / explanation per ADR

The FAQ was the last single page mixing all four Diátaxis quadrants —
the anti-pattern called out in decisions/0001-adopt-diataxis-ia.md §5
and in [Diátaxis itself](https://diataxis.fr/how-to-use-diataxis/#what-about-faqs).
Deconstruct it: each Q&A is rewritten and routed into the quadrant it
actually belongs to, the FAQ page is deleted, /reference/faq/ redirects
to the new explanation index, and the dir<->docType validator's
temporary exemption for the FAQ is removed.

Q&A -> destination map (per the consult)
----------------------------------------

How-to-shaped (2 new pages):
- "How do I get a list of installed applications?" (Q1)   ┐
- "How do I uninstall a Pear application?" (Q2)           ┘
    -> content/how-to/operate-an-app/manage-installed-applications.mdx

- "How do I distribute a binary version?" (Q8)
    -> content/how-to/operate-an-app/distribute-as-binary.mdx

Explanation-shaped (3 new thematic pages):
- "Can Pear be used with X language?" (Q4)                ┐
- "How do I write an app once that runs everywhere?" (Q5) ┘
    -> content/explanation/runtime-and-languages.mdx

- "Where is the Pear application stored?" (Q3)            ┐
- "How is my application distributed? Do I have to keep   │
   `pear seed` running?" (Q6)                             ┘
    -> content/explanation/storage-and-distribution.mdx

- "Why is NPM used for dependencies?" (Q7)                ┐
- "Can peers know my IP address?" (Q9)                    ┘
    -> content/explanation/dependencies-and-network.mdx

Bundling rationale: each page anchors a coherent theme and runs 30-50
lines, which is meatier than the FAQ entries it replaces. One-per-Q
would produce six 5-line stubs that read like FAQ in disguise; one
mega-page would lose the Diátaxis "one concept per page" guideline.
The thematic split survives review.

Pages aren't 1:1 transcriptions — each got rewritten in the voice of
its destination quadrant: how-tos became imperative recipes with code
blocks and "see also" cross-links to the CLI reference; explanations
became discursive prose with rationale, trade-offs, and explicit
"what they can / can't do" framing on the IP-exposure section.

Quadrant unhide
---------------

The Explanations quadrant was hidden in 6765e92 because it had no
content; it now has three pages, so this commit unhides it:
- content/explanation/index.mdx is recreated (was deleted in 6765e92)
  with: a Diátaxis-shaped intro, an "In this section" listing of the
  three new pages, a "More to come" preview, and a "Coming from the
  old FAQ?" lookup table mapping each old anchor to its new home.
- content/index.mdx: Explanations homepage card uncommented.
- content/how-to/index.mdx: trailing "For the conceptual 'why,' see
  Explanations" cross-reference uncommented.
- content/reference/index.mdx: trailing "For the design rationale,
  see Explanations" cross-reference uncommented; the now-stale FAQ
  section that pointed at the deleted page is removed.

The Tutorials quadrant remains hidden — that's still a real "no
content" situation (the in-flight Pear For Dummies / Pear Conventions /
P2P from Scratch tasks haven't landed yet).

Redirect: /reference/faq -> /explanation
----------------------------------------

Static HTML stubs can't dispatch on URL fragment, so per-anchor
redirects (e.g. /reference/faq#how-do-i-uninstall -> the new how-to)
aren't possible without JavaScript. Compromise: a single page-level
redirect to /explanation/, which is where most Q&As landed. The
explanation index then carries an anchor-by-anchor lookup table so
anyone arriving from a deep FAQ bookmark sees a clear pointer to the
new home of their specific question.

Both the postbuild stub generator and next.config.mjs gain the
/reference/faq -> /explanation rule. scripts/redirects.ts emits the
stub at out/reference/faq/index.html and the _redirects entry; the
new how-tos in operate-an-app/ inherit the standard /howto/<slug>/
auto-emission (two extra stubs that no one will ever hit because
those slugs never lived under /howto/, but at ~200 bytes each they're
not worth special-casing — left for subtask 10 if it bothers anyone).

Validator cleanup
-----------------

scripts/check-doctypes.ts: TEMPORARY_EXEMPTIONS goes from {faq.mdx}
to empty. Any future dir<->docType drift now fails CI immediately —
no more grandfathered files.

Verification
------------

  npm run check:doctypes          Checked 42 files (0 exempted) ✅
  npm run check:internal-links    Checked 42 files                 ✅
  npm run build                   clean, 42 sitemap URLs (was 37)
  npm run check:redirects         30 redirects, 60 assertions       ✅

Sitemap delta: -1 (faq.mdx) +6 (5 new pages + recreated explanation
index) = +5. Redirects delta: +1 (/reference/faq) +2 (auto-emitted
/howto/ stubs for the new how-tos). Stub at out/reference/faq/
index.html confirmed: meta-refresh + canonical to /explanation/.

See decisions/0001-adopt-diataxis-ia.md §5 (FAQ resolution) and §8
(dir<->docType invariant).

Made-with: Cursor

* content: align user-facing copy with PR #273 (`pear run` deprecation)

User-facing pages on this branch lead with the Pear product, not the
docs framework, and the launch flow points at `pear-runtime` / `bare`
rather than the deprecated `pear run`.

Indexes (Pear-first framing, articles linked, planned content commented)
- content/index.mdx
  - Drop the explicit Diátaxis framework framing from "Where do you want
    to go?" -> "Find what you need". Keep the four-section IA itself.
  - Inline-link the How To / Reference / Explanations descriptions to the
    articles that exist; drop unbuilt teasers (peer-to-peer in practice,
    append-only logs, the runtime model) so links don't promise content
    that isn't there.
  - Replace "Examples" block (4 mature example repos that depended on
    `pear run`) with "Boilerplates" pointing at hello-pear-electron and
    hello-pear-react-native, matching upstream PR #273.
- content/explanation/index.mdx
  - Drop the "Pages in this quadrant" / "Diátaxis FAQ recommendation"
    framing (still uses the framework, just without name-dropping it).
  - Wrap the four planned conceptual overviews in a JSX comment so the
    intent stays in source for contributors but doesn't render as a list
    of nonexistent links.

`pear run` -> `bare <app-dir>` sweep across the 5 how-tos that PR #273
hadn't gotten to yet (the corestore one was already updated upstream).
Mirrors PR #273's pattern exactly — only the launch command changes,
example bodies are left alone for a follow-up sweep.
- content/how-to/connect-to-peers/connect-two-peers-by-key-with-hyperdht.mdx
- content/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm.mdx
- content/how-to/store-and-replicate/replicate-and-persist-with-hypercore.mdx
- content/how-to/store-and-replicate/share-append-only-databases-with-hyperbee.mdx
- content/how-to/store-and-replicate/create-a-full-peer-to-peer-filesystem-with-hyperdrive.mdx

Reference / how-to copy
- content/reference/index.mdx: drop `pear run` from the CLI bullet
  (cli.md itself stamps it deprecated); promote `pear release` instead.
- content/how-to/operate-an-app/distribute-as-binary.mdx: lead paragraph
  no longer says users `pear run pear://<your-link>`; they "open
  `pear://<your-link>` to launch", consistent with the rest of the page.

Verified: `npm run check:internal-links` passes (42 files, 0 broken),
no new lint errors.

Made-with: Cursor

* feat(sidebar): unify page tree into single src/lib/custom-tree.ts

Replace per-directory meta.json scattered across content/** with a single
hand-built Node[] fed directly to <DocsLayout tree={...}>. Matches the
pattern used in cosmic-ac-docs and gives one place to control ordering,
labels, and hierarchy. The 10 stale meta.json files were never committed
so no deletions land in this commit.

Made-with: Cursor

* docs: crosslink across quadrants, validate # fragments in link checker

Crosslinking pass (how-to / reference / explanation):
- Add inline links and `## See also` sections across content/ so readers
  can move between related how-to, reference, and explanation pages
  without bouncing through the sidebar.
- Split each multi-app how-to into named sections (`## Create the X app`,
  `## Run the writer and reader`, `## Inspect the …`) and link the
  intro's app names to those sections.
- Replace vague "in the former example" phrasings with titled internal
  links and convert "Related material" paragraphs to bulleted
  `## See also` sections in explanation pages.

Link checker:
- scripts/helpers.ts: extractLinks now returns InternalLink[] with the
  fragment split out from the path. New extractAnchors / buildAnchorMap
  build a per-page anchor set from heading slugs (via github-slugger,
  matching Fumadocs' rehype-slug), explicit <a name="…"> markers, and
  id="…" attributes; frontmatter and fenced code blocks are stripped
  first so they can't contribute false anchors.
- scripts/check-internal-links.ts: validates fragments against the
  target file's anchor set (anchor-only links resolve against the
  current file); reports broken fragments separately from broken pages
  and missing assets.

Fragment fixes the new check surfaced:
- content/reference/api.mdx: /#pear-modules → /reference/modules;
  #pear--config-checkpoint-any → #pear-app-checkpoint; drop the dead
  #compat-mode fragment on the migration link.
- content/how-to/connect-to-peers/connect-to-many-peers-by-topic-with-hyperswarm.mdx:
  #create-the-peer-app → #create-the-peer-app-project to match the
  heading slug.

Made-with: Cursor

* docs: see-also blocks; cross-link coverage + orphan checker

Adds `## See also` to the six pages still missing one:
deployment, recommended-practices, troubleshooting, reference/runtime,
reference/configuration, reference/api.

scripts/check-cross-links.ts:
- Coverage report — for 26 canonical terms (auto-derived from
  /reference/{building-blocks,helpers,tools}/* + curated CLI/runtime/api
  set), counts linked vs unlinked prose mentions across content. Ignores
  frontmatter, code fences/spans, and headings; case-sensitive to avoid
  "drives" the verb colliding with /reference/tools/drives.
- Orphan inventory — counts inbound MDX-to-MDX links per page.
  Quadrant landings exempt. Hard-fails on 0-inbound; --strict also
  fails on coverage <50% for >=3-mention terms and on 1-inbound pages.

Wires `npm run check:cross-links` into package.json.

Made-with: Cursor

* chore: ESLint flat config + content fix-ups from final QA

ESLint:
- Add eslint.config.mjs targeting the flat-config format ESLint 9
  requires. Extends `eslint-config-next` (which ships native flat config
  in v16+, including next/typescript and react/jsx-a11y/import plugins).
- Project-specific ignores: .source/ (Fumadocs MDX cache), public/og/
  (Takumi-generated), out/ (static export), pearbook/ (legacy scaffold).
- scripts/ override silences React/browser rules on Node CLIs and
  disables @next/next/no-img-element for the Takumi OG generator.
- src/mdx-components.tsx: pin the eslint-disable to the intentional
  native <img>; the surrounding component documents why.

Content:
- content/index.mdx: replace the broken hello-pear-react-native
  boilerplate link (404) with hello-pear-electron and drop the Mobile
  bullet — there's no current canonical mobile starter, and the
  Electron repo is the end-to-end Pear Hello World per its README.

Lint, internal links, external links all green.

Made-with: Cursor

* docs(readme): list check:cross-links alongside the other doc checks

Made-with: Cursor

* use admonitions

* cleanup

* docs: add cross-links and apply docs-review fixes

- Link first-mention Hypercore/Hyperdrive/Hyperbee/Corestore in explanation pages.
- Replace GitHub corestore/hyperdrive links with internal /reference targets in
  storage-and-distribution.mdx; lifts Hypercore mention coverage from 31% -> 100%.
- deployment.mdx: tighten description, add audience/outcome opener.
- configuration.mdx: rewrite ### Deprecations heading + intro, link pear-runtime
  internally, split 168-word pear.pre paragraph into four, expand LLM on first
  use, fix let's -> lets and conjuction -> conjunction.
- create-a-full-peer-to-peer-filesystem-with-hyperdrive.mdx: imperative voice in
  the lead-in paragraph.
- README: document --strict mode for check:cross-links in CI.

Made-with: Cursor

* feat(seo): integrate @tetherto/docs-seo-* end-to-end (metadata, sitemap, robots, JSON-LD, OG) (#280)

* content: rename .md to .mdx and add Diátaxis docType / schemaType frontmatter

Fumadocs MDX needs the .mdx extension to compile JSX/MDX content; the .md
loader path doesn't run the MDX pipeline, which silently broke things like
JSX comments and component embeds.

While renaming, add the @tetherto/docs-seo-schema frontmatter so JSON-LD
@type values, the sitemap, and the Diátaxis classification land correctly
without warnings:

  - docType:    explanation | how-to | reference | faq
  - schemaType: WebPage | TechArticle | APIReference

The schemaType per page follows the docType -> @type mapping the schema
package documents (reference -> APIReference for upstream API surfaces,
how-to -> TechArticle for procedural docs, etc.). Four reference docs
that are actually procedural (deployment, migration, recommended-practices,
troubleshooting) were reclassified to docType: how-to.

deployment.mdx also gets its trailing HTML comment converted to a JSX
comment so MDX compilation succeeds.

Made-with: Cursor

* build: install @tetherto/docs-seo-* from GitHub Packages

The @tetherto/docs-seo-* SEO toolkit is published to GitHub Packages
under the npm.pkg.github.com registry rather than the public registry.
This adds the consumer-side wiring needed to install it cleanly.

  .npmrc          - point the @tetherto scope at npm.pkg.github.com and
                    read the auth token from \${GITHUB_TOKEN} at install
                    time (matches the convention already used across the
                    org, e.g. qvac's run-lint-and-unit-tests action).

  .env.example    - document GITHUB_TOKEN (required for npm install) and
                    every SEO env var the @tetherto/docs-seo-* packages
                    consume (NEXT_PUBLIC_DOCS_ORIGIN, SKIP_OG_BUILD,
                    DOCS_OG_*, DOCS_SEO_QUIET_GENERATED, DOCS_SEO_SILENT).

  README.md       - explain why npm install needs GITHUB_TOKEN exported
                    in the shell (npm reads .npmrc with process env, not
                    .env files) and link to docs-template's README for
                    the full PAT flow (scopes / expiration / SSO).

Made-with: Cursor

* feat(seo): wire @tetherto/docs-seo-* end-to-end

Replace the previous ad-hoc OG handler / hand-rolled metadata with the
@tetherto/docs-seo-* packages so the docs ship full structured SEO:
canonical URLs, Open Graph + Twitter cards, JSON-LD per page, sitemap
with <lastmod>, robots.txt with bot allow/deny lists, and pre-rendered
Takumi OG images for every MDX page.

Build / deps
  package.json         - add @tetherto/docs-seo-{schema,core,next,og},
                         @takumi-rs/image-response, zod, @fontsource/poppins,
                         tsx, serve. Add prebuild + build:og scripts that
                         run the Takumi prebuild before next build, and
                         keep tsx in NODE_OPTIONS for next build/dev so
                         source.config.ts can import @tetherto packages
                         shipped as raw .ts (Node's native type stripping
                         refuses to strip files under node_modules).
                         Switch to "type": "module".
  next.config.mjs      - transpilePackages for the four @tetherto/docs-seo-*
                         packages (Next has to compile their TS sources).

Schema / source
  source.config.ts     - extend Fumadocs frontmatterSchema with
                         tetherSeoFrontmatterSchema; install
                         fumadocs-mdx/plugins/last-modified with a custom
                         git resolver that --follows .md -> .mdx renames
                         and falls back to HEAD on shallow clones (Sevalla
                         and other managed CIs do shallow checkouts).
  src/lib/source.ts    - drop local getPageImage; OG image URLs now come
                         from @tetherto/docs-seo-og.

App routes / metadata
  src/lib/seo-config.ts                       - centralized DocsSeoConfig
                                                (origin, siteName, publisher,
                                                trailingSlash). Default
                                                origin is localhost:8080 to
                                                match the serve script.
  src/app/(docs)/[[...slug]]/page.tsx         - generateMetadata via
                                                buildDocsMetadata + JSON-LD
                                                via DocsJsonLd; OG image
                                                from getPageImage (or
                                                staticOgImagePath when
                                                SKIP_OG_BUILD=1).
  src/app/sitemap.ts                          - buildDocsSitemap (new).
  src/app/robots.ts                           - buildDocsRobots (new).
  src/app/layout.tsx                          - bump default origin to
                                                localhost:8080 to match
                                                seo-config.
  src/app/og/docs/[...slug]/route.tsx         - removed; replaced by the
                                                static prebuild below.

Takumi OG prebuild
  scripts/generate-takumi-og.tsx              - precomputeTakumiOgImages
                                                with a Pear-branded
                                                ImageResponse template
                                                (logo + title on one row,
                                                description below, brand
                                                colors and Poppins fonts
                                                matching the docs site).
                                                Loads pear-1.svg as a base64
                                                data URL and Poppins woffs
                                                from @fontsource so renders
                                                are deterministic (no
                                                network fetch at build).

Frontmatter
  content/index.mdx                           - docType: explanation,
                                                schemaType: WebPage
  content/reference/{api,cli,configuration}.mdx
                                              - docType: reference,
      …
Resolve modify/delete conflicts in favor of published by keeping legacy
guide files removed; content lives under the new content/ IA.

Co-authored-by: Cursor <cursoragent@cursor.com>
@lucas-tortora
lucas-tortora requested review from a team June 19, 2026 18:15
@kinsta

kinsta Bot commented Jun 19, 2026 •

Copy link
Copy Markdown

Preview deployments for pear-docs preview ⚡️

Status Branch preview Commit preview
✅ Ready Visit preview Visit preview

Commit: 04ab8a12afabbbc7c9499abe877431283b7acf71

Deployment ID: cc17bd6d-f16e-48e5-b12d-73d6b52ce528

Static site name: pear-docs-preview-iimt7

* fix: add catch-all 404 rule to _redirects

Add public/_redirects with a Sevalla-compatible catch-all that serves
/404.html with HTTP 404, and merge those static rules into out/_redirects
during postbuild so they survive the generated IA redirect output.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: adopt qvac _redirects strategy for 404s and markdown negotiation

Mirror qvac docs: public/_redirects is the authored source (Accept:
text/markdown rules plus catch-all 404), copied into out/ by next build.
Postbuild prepends generated IA 308 redirects ahead of that file so the
catch-all stays last.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Ports the QVAC docs Keet modal into pear-docs. A Keet icon link in the sidebar footer opens a modal with two steps: download the Keet app, and join the Pear Development Group room via QR code or copy-link.

- src/components/keet-modal.tsx: theme-aware, portal-mounted modal that intercepts clicks on the Keet nav icon
- src/components/keet-icon.tsx: navbar Keet glyph
- wires the icon link + modal mount into the docs layout
- adds qrcode.react and next-themes deps

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
…g URLs (#309)

Covers three eras of missing redirects identified via git history and
Google Search Console:

- /reference/{cli,configuration,runtime}/ → /reference/pear/* (pear/ subfolder pass)
- /reference/{bare-modules,modules,desktop-release-npm-scripts}/ → new paths
- /reference/{node-compat,bare-overview,templates}/ → best-effort gitbook-era destinations
- /getting-started/ flat pages → build-a-peer-to-peer-chat/ and from-a-template/ subdirs
- /how-to/operate-an-app/ flat pages → build-and-package/ and manual-deployment/ subdirs
- /guide/* (10 gitbook-era pages) → nearest current equivalents
- /pear-runtime/*, /guides/best-practices/, /examples/react-app-using-pear/,
  /reference/api/ → stale Google-indexed paths from pre-IA structure

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
…cs (#310)

Readers cloning examples need the published branch, not main.

Co-authored-by: Cursor <cursoragent@cursor.com>
* docs: add Bare reference, explanations, and how-tos; integrate into IA

Documents Bare as a first-class part of the Pear stack:

- Reference: Bare runtime API, the `bare` CLI, Bare Kit (native
  embedding), and a 36-page `bare-*` module catalog.
- Explanation: the Pears stack, inside the Bare runtime, one core /
  many platforms, and using Bare standalone.
- How-to: run-on-native guides (bundle a Bare app, embed in React
  Native, type a native RPC bridge).
- Integration: landing page, explanation/reference indexes, the
  `bare-modules` catalog, and the sidebar tree now surface Bare; Vale
  config + Prose/Headings style aligned for the new terms.

Collapsed onto published: the Diátaxis IA reorganization this branch
originally carried is already upstream via #305, so only the net Bare
contribution lands here. Published's keet modal (#308), redirects
(#307/#309), and getting-started clone fix (#310) are preserved.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore: retire legacy Pearbook pipeline

Removes the committed pearbook/ gitbook-era HTML (122 files) and both
workflows of the old book pipeline: Preview (`pear run --output pearbook`
→ preview branch) and Publish (promote preview → published). The content/
Diátaxis IA supersedes pearbook, the Next.js app never built or served it,
and legacy URLs are covered by the redirects in scripts/redirects.ts.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore: gitignore vale-synced styles and Obsidian config

`.github/styles/Google/` is fetched by `vale sync` (re-fetched in CI; only
.github/styles/Prose/ is committed) and `content/.obsidian/` is local editor
state — neither should be committed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(bare): fix Vale prose lint errors

Satisfies the Google style rules enforced in CI (docs-lint):
- Google.Latin: "e.g." → "for example," (12 occurrences across
  bare-addon-resolve, bare-channel, bare-mdns-discovery, bare-pipe,
  bare-semver).
- Google.EmDash: remove spaces around the em-dash in
  bare-mdns-discovery ("Android — without" → "Android—without").

`vale --minAlertLevel=error content` now reports 0 errors in 126 files.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(bare): correct API mismatches in bare reference docs

- cli: remove --inspect-port flag that does not exist in bare v1.28.0
- bare-apk: document options for createAPKSet and createAPK
- bare-rpc: fix RPCIncomingRequest.reply() signature (add encoding param),
  expand property list (data, sent, received)
- bare-form-data: move isFormData and toBlob to module-level exports
- bare-semver: remove caret/tilde/X-range/hyphen range syntax from
  Range.parse — parser only supports comparison operators and ||

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(links): remove non-existent pear-base action, update moved-repo URLs

- Drop `holepunchto/actions/pear-base` table row and references — this
  action never existed in the repo; replace workflow step with
  `actions/checkout@v4` + `make-pear-app` to match the actual
  hello-pear-electron template
- Update `mafintosh/dht-rpc` → `holepunchto/dht-rpc` (repo moved)
- Update `prdn/hyper-cmd-utils` → `holepunchto/hyper-cmd-utils` (repo moved)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(bare): correct API mismatches found in doc-vs-source review

- cli: add missing --inspect-port flag
- bare-stream: clarify WHATWG streams require 'bare-stream/web' import path
- bare-ipc: remove incorrect structured-clone description; it's a raw duplex pipe
- bare-semver: document full range syntax (^, ~, X-ranges, hyphen, wildcard)
- bare-sdl: distinguish Rect (integer, Texture.update) from Rect.F (float, Renderer.texture)
- runtime: add 'wakeup' as a valid context for calling Bare.resume()
- explanation/bare-runtime: add Awake state to lifecycle diagram; fix simplified prose
- bare-broadcast-channel: note MAX_PORTS lifetime cap on channel.connect()
- bare-make: add missing color option and --no-color CLI flag to generate
- bare-sidecar: add missing 'close' event
- bare-union-bundle: document skipModules in b.add(); document cache/skipModules in b.load()
- explanation/bare-on-native: soften Swift/Kotlin native binding claims to language interop

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(prose): replace e.g. with 'for example' to pass Vale lint

bare-semver.mdx had two Google.Latin violations (lines 145, 151)
that were failing the vale prose lint CI job.

Also applies doc-vs-source verification fixes from the scheduled
review pass:
- bare-sdl: remove non-existent Rect/Rect.F classes; fix renderer/texture signatures
- bare-addon-resolve: drop unexported resolve.preresolved; add resolve.constants
- bare-sqlite: rename Statement → StatementSync throughout
- bare-bluetooth-apple: reword Constants as static properties, not a named export
- bare-union-bundle: fix skipModules ([]→true) and cache (true→require.cache) defaults
- build-desktop-distributables: pear.stage.includes → pear.stage.include (singular)
- migration.mdx: global.Pear.run() → Pear.worker.run(); updating/updated events on pear.updater
- start-from-hello-pear-bare: bin.js → bin.mjs (upstream entrypoint renamed)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Apply suggestions from code review

Co-authored-by: David Mark Clements <david.mark.clements@gmail.com>

* docs(bare): document QuickJS engine support

Bare's libjs ABI now has an ABI-compatible QuickJS backend
(holepunchto/libqjs), alongside the existing V8 default and
JavaScriptCore (libjsc). Add it to the engine list in bare-runtime.mdx:
"What Bare adds", "Engine independence", and the engine FAQ.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(vale): allow spaced em-dashes (disable Google.EmDash)

Adopts the spaced em-dash style applied in code review (d39166c).
Google.EmDash flags any space around a dash, which conflicted with the
reviewer's " — " usage in bare-runtime.mdx; disable it repo-wide so the
house style and docs-lint agree.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(bare): add bare-timers reference and wire up app-suspension docs (#312)

* docs(bare): add bare-timers reference and wire up app-suspension docs

Add a reference page for Bare's global timer functions (setTimeout,
setInterval, setImmediate, and their clear* counterparts), verified
against the upstream bare-timers source: object timer handles,
ref()/unref()/hasRef()/refresh(), the Symbol.dispose behaviour, the
promise-based API, and the Bare-specific delay clamping and lifecycle
integration that the suspension model relies on.

Register it in the sidebar and link it from the Bare modules catalog,
then connect it to the app-suspension how-to in both directions so the
"Clear timers" section links to real anchors instead of plain code
spans. Also wires the suspension how-to into the Inside Bare and
Embed Bare in React Native pages and the navigation tree.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* add react native bare kit note

* docs(bare): suspend/resume Hyperswarm instead of destroying it

Per review on #312: Hyperswarm exposes suspend()/resume(), so the
app-suspension how-to no longer needs to destroy the swarm and rebuild
it on every cycle. Call swarm.suspend() on the Bare `suspend` event and
swarm.resume() on `resume`, keeping the swarm instance and its joined
topics alive across suspension.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(bare): drop await/.flushed() from swarm.join in suspension example

Per review on #312: awaiting .flushed() here nudges readers toward an
unnecessary pattern. A plain swarm.join(topic, ...) is the idiomatic
fire-and-forget; the example doesn't need to block on the first announce.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(bare): simplify to swarm.join(topic) in suspension example

Per review on #312: { server: true, client: true } is the default for
swarm.join(), so drop it and let the example read swarm.join(topic).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: David Mark Clements <david.mark.clements@gmail.com>
Add the HTML verification token at public/googleb79b36e088621ed1.html so
it deploys to the site root (/googleb79b36e088621ed1.html). public/ is
copied verbatim into the out/ static export, and static-file resolution
runs ahead of the _redirects catch-all, so it serves with 200.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs(bare): add Node.js builtin-to-bare module mapping table

Improve the Node.js compatibility story across the three Bare pages that
previously left it scattered:

- bare-modules.mdx: add a "Node.js builtin → Bare module" mapping table
  (fs→bare-fs, crypto→bare-crypto, child_process→bare-subprocess, …),
  split the shims into their own subsection, and note the WHATWG modules
  (bare-url/fetch/encoding/console) that live in functional sections.
- bare-runtime.mdx: point the npm-modules FAQ at bare-compat-napi for
  Node-API addons and link to the new mapping section.
- runtime-and-languages.mdx: link the "coming from Node.js" note to the
  new mapping table.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* format fixes

* fix formatting

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add Status component for API stability badges

Replaces inline <mark style={{...}}> badges with a reusable <Status level="..." />
component registered in getMDXComponents, keeping the MDX authoring surface clean.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: replace inline mark badges with <Status> component

Swaps all <mark style={{...}}> stability badges across reference and index
pages to use the new <Status level="..." /> component.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(refgen): JSDoc-first reference generation pipeline

Generate curated API reference pages from upstream source: AST + JSDoc
(types, @param/@returns/@typedef/@type) merged into a structured model and
rendered to curated MDX via per-repo editorial manifests. Adds the JSDoc gap
report + coverage dashboard (refs:jsdoc), the README->JSDoc seeder
(refs:seed-jsdoc), the local-iteration regenerator (regen-local), a
cross-module type registry, and the agent runbook/handoff, JSDoc convention,
and shareable eslint-jsdoc config.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(refgen): generated models, curated previews, and JSDoc gap reports

Per-repo api-model.json, curated-preview.mdx, jsdoc-gaps.md and
improvement-plan.md for all 12 modules.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci(refgen): curated-manifest gate, JSDoc dashboard, and weekly regeneration

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(refgen): JSDoc-first reference generation pipeline

Introduces a JSDoc-extraction pipeline that generates rich API reference
pages for all 12 Holepunch modules directly from JSDoc in their source.

Pipeline overview:
- scripts/refgen/extract-ast.ts — extracts JSDoc from upstream source into
  a structured api-model.json per module (descriptions, typed params,
  returns, throws, typedefs with defaults)
- scripts/refgen/emit-jsdoc.ts — reconstructs per-repo JSDoc diffs in
  ../jsdoc-upstream/<slug> from the committed models (powers upstream PRs)
- scripts/refgen/prose.ts — shared description cleaning (destrand,
  cleanParamDesc) used by both renderer and emitter so they stay in sync
- scripts/refgen/layouts/<slug>.ts — per-module manifests controlling
  member order, description/throws overrides, keepCurated flag
- scripts/gen-curated.ts — renders api-model.json → curated-preview.mdx
  and content/reference/* pages; honours keepCurated so the hyperswarm
  page stays hand-curated
- .github/workflows/regenerate-references.yml — weekly regen watcher
  (cache-gated on upstream stable tags; auto-triggers commented out until
  JSDoc ships in upstream releases)

Content changes:
- All 12 reference pages now render typed params, returns, throws, typedef
  option tables, and a generated ## Errors section
- generated/refs/<slug>/api-model.json — committed models (source of truth)
- generated/refs/<slug>/curated-preview.mdx — rendered previews

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: align docs with Pear v3 — CLI updates, Pear OTA rename, deprecations

Align the CLI reference with the v3 command set on holepunchto/pear main:
- pear run, release, presets, shift, drop marked removed
  ("deprecated in v2.6.5, removed as of v3") with migration pointers
- pear install promoted to a real command (pear-install); pear build
  re-sourced to pear-build; source links repointed to main until v3 tags
- flag/subcommand drift fixed against cmd/*.js (no more --no-ask/--compact/
  --mem; data=dht+multisig; gc=sidecars+cores; sidecar adds shutdown/inspect;
  multisig adds keys paths and --peer-update-timeout; provision takes
  verlinks; info takes [dir])

Rebrand the embeddable OTA library as "Pear OTA" (branding only — the
package remains pear-runtime everywhere upstream, so code identifiers,
npm/GitHub links, class names, and the page slug are unchanged).

Rewrite pages that instructed removed commands: manage-installed-applications
now covers OS app-folder installs, pear info, and pear gc cores; the release
pointer flows through pear provision + pear multisig quorum cosigning.

Verify every API claim against source: pear-runtime v1.3.1 (deep links
re-pinned from v1.1.4), pear-runtime-updater options/events, and the
hello-pear-electron template; add a verified Options section to the OTA page.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat: add docs changelog with upstream-release watcher

Add a top-level /changelog — a single rolling, hand-curated record of
breaking changes across Pear and its modules, seeded with the Pear v3
entry (CLI removals, pear install, global Pear API removal, Pear OTA).

Wire-up: nav entry in custom-tree.ts, homepage and reference-index
sections, changelog→page in the check-doctypes quadrant map, and
inbound links so the page passes the orphan audit.

Automation: scripts/check-upstream-releases.ts (stdlib-only, so CI can
run it with just tsx) polls the repos in scripts/upstream-releases.json,
falls back to version tags for repos that don't publish GitHub releases
(pear, pear-electron, pear-build), and inserts TODO(curate)-marked draft
entries under the changelog:insert marker, advancing
upstream-releases-state.json. The upstream-releases workflow runs it
daily and force-pushes one rolling review PR (changelog/upstream-drafts)
with a curation checklist; baselines only land on published when the
curated PR merges.

Verified: doctypes/internal-links/cross-links/Vale pass; /changelog and
sidebar render; watcher dry-run (rewound bare tag) inserts correctly
formatted drafts and re-advances state.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat: harden release watcher and document store submissions

Watcher hardening:
- Resume the open changelog/upstream-drafts branch instead of
  force-pushing from published — scheduled reruns now stack new drafts
  on top of human curation commits instead of clobbering them; the PR
  body lists every draft on the branch, not just the latest run's
- Tripwire: when a pear (CLI) v3 tag is detected, the drafts PR body
  flags re-pinning the CLI reference source links from main to the tag
- Widen the watch list from 7 to 19 repos: add the building blocks and
  helpers with reference pages (hypercore, hyperbee, hyperdrive,
  autobase, hyperswarm, hyperdht, corestore, localdrive, mirror-drive,
  hyperswarm-secret-stream, compact-encoding, protomux), slugs verified
  and baselined

Store submissions:
- New how-to: Submit to app stores (Flathub + Snap), adapted from the
  hello-pear-electron README store-submissions section — manifest prep,
  local testing, review submission, and release automation for both
- Deployment guide gains step 8 "Store submissions (optional)"; wired
  into the sidebar, how-to index, and build-desktop-distributables

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(v3): rename Changelog→Release Overview; finalize removed CLI/API status

- Rename the changelog page title and nav label to "Release Overview"
  (route stays /changelog; automation marker and `pear changelog` CLI
  command untouched); update the links that point to it.
- Document `pear install` as an available v3 command (no status badge).
- Mark the ambient `global.Pear` API surface as REMOVED (removed in v3);
  the still-current `global.Bare` API is unchanged.
- Mark the `pear-api` module as removed and relabel the reference index
  entry "Pear API (removed)".
- Assorted in-progress v3 doc updates (store submissions, migration,
  distribution, upstream-release watcher tweaks).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(v3): move changelog to /release-overview; correct config field statuses

- Rename content/changelog/ -> content/release-overview/ and move the route
  /changelog -> /release-overview (new route, no redirect needed); update the
  inbound links, nav, and the upstream-release automation path (script +
  workflow).
- configuration.mdx: verified each deprecated field against pear-state and the
  pear repo (v3). Still-present fields (name, routes, unrouted, links, assets,
  gui) stay DEPRECATED; fields no longer read by pear v3 are marked REMOVED:
  pear.pre, pear.userAgent, pear.stage.prefetch, and the (previously
  documented-as-current) pear.stage.include and pear.stage.defer, which went
  away with the pear stage --compact/warmup static-analysis phase.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(config): document pear.stage.only and pear.stage.purge

Both are read by `pear stage` in v3 (subsystems/sidecar/ops/stage.js) but were
undocumented: `pear.stage.only` restricts staging to given path prefixes
(merged with `--only`); `pear.stage.purge` removes now-ignored entries from a
prior stage (config equivalent of `--purge`). Cross-linked from the removed
pear.stage.include note.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(refs): regenerate reference models for 5 modules to latest releases

Bring the JSDoc-first generated API models up to date with upstream:
compact-encoding v3.2.0→v3.3.0, corestore v7.10.1→v7.11.0,
hypercore v11.33.2→v11.34.0, hyperdht v6.32.0→v6.33.0,
hyperdrive v13.3.2→v13.3.3. Re-extracted api-model.json + reference.mdx +
improvement-plan.md per module, bumped scripts/refgen/.cache.json, and synced
the GitHub source links on the matching content/reference pages to the new
tags. The other 7 modules were already current and were skipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(hyperdht): document defaultKeyPair, findPeer, suspend, resume

Add the genuinely-public methods flagged by the refgen completeness pass but
missing from the reference page, sourced from holepunchto/hyperdht@v6.33.0:
node.defaultKeyPair, node.findPeer(), and node.suspend()/node.resume() (the
device-sleep / network-change lifecycle pair). Internal symbols surfaced by the
scorer (onrequest, pool, plugins, register, rawStreams, createRawStream, …) are
intentionally left out.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(refs): document real public gaps in hyperdrive, hypercore, corestore

Add genuinely-public methods flagged by the refgen completeness pass but missing
from the reference pages, each verified against upstream source:
- hyperdrive@v13.3.3: Hyperdrive.getDriveKey(), drive.blobs, drive.monitor()
- hypercore@v11.34.0: core.byteLength, core.manifest, core.purge(), the
  'migrate' event (skipped core.contiguousByteLength — it's a stub returning 0)
- corestore@v7.11.0: store.opened / store.closed

Internal symbols, EventEmitter passthroughs, and entries already documented on
the pages (findingPeers, audit, getBlobs, …) were left as-is.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(compact-encoding): add complete bundled-codec reference

The page detailed a representative codec per family but omitted the size and
variant codecs. Add a grouped "Complete codec reference" catalog covering every
bundled encoder in compact-encoding v3.3.0 — the full uint/int families
(uint8…uint64be, int8…int64), bigints, float32/64, buffers (incl. optionalBuffer),
all typed arrays, every string encoding (ascii/hex/base64/utf16le with .fixed(n)),
fixed buffers, structured/special values, network addresses (ipv4/ipv6 + Address
variants), and the cenc.raw.* non-prefixed variants. Descriptions taken from the
upstream README; each links back to the encoder contract and composition helpers.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(cli): add canonical "Install & upgrade" section (npx pear, v2→v3)

`npx pear` / `npm i -g pear` were only mentioned in passing across getting-started
and how-to pages, and there was no documented path for moving the CLI itself from
v2 to v3 (the migration page only covers the pear run → Pear OTA code migration).

Add an "Install & upgrade" section at the top of the CLI reference: `npx pear`
bootstraps the platform (per the upstream README) and prints PATH setup, with a
"Moving from Pear v2 to v3" note explaining the v3 CLI self-updates over the air
via Pear OTA. Cross-linked from the migration how-to so v2 users find it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: fix Vale Google.Latin lint — replace "e.g." with "for example"

Two occurrences introduced in the recent reference additions
(hyperdrive drive.monitor param, compact-encoding strings note).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix heading

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
lucas-tortora and others added 30 commits October 20, 2026 10:10
…nd bare-bluetooth-linux (#416)

* feat(refgen): carry author sections and README patches in layouts

A layout can now append author-written sections (inline or from
<name>.sections.json) and patch README-derived blocks by exact text, for
what a .d.ts can't carry, such as the event tables of modules that don't
export their event maps. A patch that no longer matches fails the render, so
one that upstream has made redundant gets noticed. Same shape as on the
docs/new-bare-module-pages-2026-10 branch, so the two merge cleanly.

The dossier also skips README sections about running the tests (Testing on
device, Running the tests under ASan), which are for contributors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): refresh the Bluetooth references and add bare-bluetooth and bare-bluetooth-linux

Both platform READMEs send readers to these pages for their API, so they
need to track upstream:

- bare-bluetooth-apple 0.5.1 -> 0.7.0: showPowerAlert, retrievePeripherals()
  and retrieveConnectedPeripherals(), and an Errors table. The README's
  usage passes serviceAdd an error argument it never receives; a layout
  patch drops it.
- bare-bluetooth-android 0.9.1 -> 0.11.3: Server.open()/close(),
  getBondedDevices(), ADAPTER_UNAVAILABLE, peripherals built from a Device,
  an Events table checked against every emit() in lib/ (the package doesn't
  export its event maps), and the README's Errors section.
- bare-bluetooth 0.6.3-0 (npm latest, a prerelease that adds Linux):
  hand-written, since the package ships no .d.ts. Based on the 0.6.0 draft
  from docs/new-bare-module-pages-2026-10, without Server.open()/close(),
  which 0.6.2 removed. The usage compares UUIDs through the expand() helper
  from example/gattpong.js; the README's === comparison fails on every
  platform. Linux permission constants differ in value, so the table shows
  both.
- bare-bluetooth-linux 0.9.2: generated, now that it ships types.

Also links the wrapper from the catalog and adds both new pages to the
sidebar.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(refgen): cover layout patches and author-written sections

The render-time guarantees added with the layout feature had no tests: a
patch must hit exactly once, a patch aimed at a missing block fails, and a
patch can reach a README section by heading. Also covers the order of
author-written sections and the dangling-anchor stripping they go through.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(bare): fix the Bluetooth reference review findings

- bare-bluetooth-linux: mark it experimental, as its README does, so the
  badge no longer contradicts the page; add the marker to its catalog row.
- bare-bluetooth-apple: document what showPowerAlert does and its default,
  and drop the connect/disconnect parameter overrides that hid upstream's
  text for RetrievedPeripheral and pending connections.
- bare-bluetooth-android: rename the Events sub-headings to "Central
  events" and so on, so their ids no longer collide with the API headings.
- bare-bluetooth: Linux filters discoverServices and discoverCharacteristics
  too; the Linux-only read/write defaults no longer read as general; link
  gattpong.js at the v0.6.3-0 tag; the usage example guards against
  connecting twice and against BlueZ's cached devices, as gattpong.js does.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* chore(docs): watch bare-bluetooth-linux and refresh the Bluetooth dossier

The commit-level upstream check now watches bare-bluetooth-linux, and the
recorded commits for bare-bluetooth-apple and -linux are the ones the
documented tags contain, so the daily job does not report work already done.

The research dossier had the three generated modules patched by hand while
the digest was left behind. Replace the four Bluetooth records with a fresh
run of the research script and re-render the digest from them, so the two
files agree again. Every other record is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(bare): refresh the Bluetooth references to the latest releases

- bare-bluetooth 0.6.3-0 -> 0.6.3, now the stable `latest`: rewrite the
  version callout (0.6.3 adds Linux over 0.6.2), point the example link at
  the v0.6.3 tag, and update the dependency ranges to android ^0.11.4,
  apple ^0.7.1 and linux ^0.9.2. Android now reports 'unsupported' when the
  device has no Bluetooth adapter instead of throwing from the constructors,
  so the state table lists it and the Platforms section says what each call
  does then. Setting `value` on a discovered characteristic throws.
- bare-bluetooth-android 0.11.3 -> 0.11.4 and bare-bluetooth-apple
  0.7.0 -> 0.7.1: regenerated; the Characteristic.d.ts docs now say that
  assigning `value` on a discovered characteristic throws. The layout
  fallback descriptions match.
- bare-bluetooth-linux stays at 0.9.2.

The research dossier has the three changed Bluetooth records re-run; every
other record is unchanged. scripts/upstream-commits-state.json needs no change
because none of the three releases touched the watched root index.d.ts.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
… the bare worker (#420)

holepunchto/hello-pear-bare now inlines its worker, the daemon variant lives
in its own repository (holepunchto/hello-pear-daemon), and the single-thread
variant is retired. Update the docs, the vendored snapshots, and the CI that
exercises them to match.

Docs
- start-from-hello-pear-bare: describe workers/main.js as an inlined copy of
  hello-pear-worker, including what `npm run inline-worker` does and how the
  source-header comment guards the file against being overwritten. Replace the
  "Variants" section with "Short-lived CLIs: hello-pear-daemon" (clone URL,
  repository links, daemon snippets), drop the single-thread section, and
  point the Build callout at hello-pear-daemon's older make.js.
- Note on the page that `updating-delta` is logged but never forwarded by the
  worker (the removed single-thread section was the only place that said so).
- Route short-lived CLIs to hello-pear-daemon from the template index, and say
  "services" instead of "daemons" in the hello-pear-bare card copy and the
  build-a-pear-app skill so the new repo name does not read as "for building
  daemons".
- Stop claiming every hello-pear-* template ships `require('hello-pear-worker')`
  on the Electron and mobile OTA guides, the React Native page, the QVAC TUI
  how-to, the shared worker callout, and check-workers-in-sync.ts.

Snapshots
- hello-pear-bare: refresh package.json and package-lock.json to upstream
  28ce09a. workers/main.js stays the canonical copy (upstream's inline minus
  its two-line source header), so check-workers-in-sync still holds.
- hello-pear-daemon: vendor holepunchto/hello-pear-daemon main at 0a2e3ef in
  place of hello-pear-bare-daemon, keeping only the placeholder `upgrade` link
  as a deviation.
- Delete hello-pear-bare-single-thread.
- Fix the dead content path in the hello-pear-bare snapshot README.

CI
- scripts/test-examples.ts and examples.yml: drop the single-thread scenario,
  rename the daemon scenario to hello-pear-daemon, and update the app-dir and
  scenario counts in the header comment.
- watch-boilerplates.yml: drop the two variant-branch entries, watch
  holepunchto/hello-pear-daemon main, and bump the hello-pear-bare pin.

Verified: docs checks (code-imports, includes, internal-links, doctypes,
workers-in-sync, docs-versions, agent-ready), Vale, and a full build all pass.
The hello-pear-bare and hello-pear-daemon scenarios pass from a clean
`npm install` on Bare 1.34.1, the version examples.yml pins.

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
The 3.6.0 quoted-link support exists because `npm pkg get` prints a
string as JSON, quotes included, so `pear stage $(npm pkg get upgrade)`
passes the quotes to Pear. 3.5.0 rejects that with `A valid pear link
must be specified.` The reference, release notes, troubleshooting entry,
and pear-cli skill described it only as a CI and pasted-quotes
convenience.

Verified on built v3.5.0 and v3.6.0 binaries: `npm pkg set
upgrade=$(pear touch)` stores the bare link, `pear stage`, `pear info`,
and `pear seed` accept `$(npm pkg get upgrade)` on 3.6.0, and the first
two fail on 3.5.0. `| tr -d '"'` is the workaround for 3.5.0 and earlier.

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
…ink the worker repos (#421)

* docs(templates): add a hello-pear-daemon page and card

hello-pear-daemon, the detached-updater boilerplate that moved out of
hello-pear-bare's variant/daemon branch, only had a section on the
hello-pear-bare page. Give it its own walkthrough, a card on the
template index and the other getting-started pages, and a nav entry.
The bare page's daemon section becomes a pointer, and its daemon-only
build note moves to the new page.

Checked against the snapshot by running it, in a dev run and in a
standalone bare-build binary:
- the foreground exits at once and one daemon runs per storage dir
  (the lock is released on kill -9)
- --update-window bounds the wait for a download to start
- an unreplaced upgrade link writes INVALID_URL to updates.log, not the
  terminal
- a dev run is unbundled, so --updates there never checks for or
  downloads a release; the page says to use a standalone build
- bare-build lowercases and hyphenates --name, while bin.mjs hands the
  updater productName || name verbatim, so the page tells readers to
  use identifier-style names and keep each --name in step

The vendored snapshot's name, make:* --name, repository and bugs URLs,
and lockfile entries are hello-pear-daemon instead of the
hello-pear-bare upstream still carries. SNAPSHOT.md documents this,
replacing the keep-as-upstream note from #420, and no longer claims the
scenario asserts the CLI exits. The build-a-pear-app skill links the
new page.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(templates): tell the two terminal templates apart, fix the install-location advice

The hello-pear-bare cards said just "(terminal)", which no longer
separates them from the short-lived CLI card, and the bare intro still
listed "daemons" next to a template named hello-pear-daemon. Label the
cards "long-running terminal" and say "long-running services".

The daemon page recommended apt for distribution while also saying the
updater swaps the executable in place. A root-owned install can't do
that: fsx.swap, which the updater calls, succeeds in a writable
directory and fails with EACCES in a read-only one. Drop apt and
Homebrew from the page's distribution line, and say the permission
error lands in updates.log.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(templates): add the hello-pear-qvac-tui page and list the other hello-pear repos

The template index covered four of the eight hello-pear-* repos. Add the
rest that belong there.

- New page, "Start an on-device AI terminal app from the
  hello-pear-qvac-tui template", with a nav entry and a card on the
  template index and both getting-started hubs. It reuses the snapshot
  the on-device AI how-to already vendors, so there is no new snapshot
  or CI wiring; the snapshot README now names both pages whose line
  ranges need re-checking on a refresh. The how-to and the
  build-a-pear-app skill link to the page.
- A "More hello-pear repositories" section on the index with external
  cards for hello-pear-worker, the shared worker the templates embed,
  and hello-pear-bare-worker. The latter is an earlier version of
  hello-pear-bare: its app.js and workers/main.js are byte-identical to
  hello-pear-bare at 42955ca (2026-06-24), where that design became the
  main boilerplate. hello-pear-bare-tui is left out; its README is a
  two-line stub.
- Counts like "all four" are now count-free on the index, the pear
  getting-started hub, and the "Where to go next" lists, and the
  portability sentence names the worker-based templates.

Verified with the check scripts, vale, types:check and a full next build.
The page's flags and headless tests (22/22) were run from a scratch copy
of the snapshot; the TUI itself was not run because it downloads the
model.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(templates): fix the cross-build advice, the name rule, and the bare-worker card

Review fixes for the hello-pear-daemon and hello-pear-qvac-tui pages.

- The daemon page told readers to build each platform's binary on a
  matching host. The make:<platform>-<arch> scripts cross-build (a
  Linux x64 ELF came out of npm run make:linux-x64 on macOS arm64);
  only npm run make ignores HOST. Say so.
- Both pages described bare-build's name handling as lowercase plus
  hyphens, which cannot turn MyCLI into my-cli. It also hyphenates a
  capital that follows a lowercase letter or digit. Checked against
  bare-build 1.0.1 and 1.2.1: My CLI, MyCLI, and my_cli all give my-cli.
- The hello-pear-bare-worker card called the repo an earlier
  hello-pear-bare, which upstream never says, and the supporting claim
  that app.js is byte-identical was wrong (that repo has no app.js).
  Only workers/main.js matches hello-pear-bare at 42955ca. Describe it
  as an early worker-based CLI around that worker.
- The daemon page now lists Bare on PATH as a prerequisite, as the qvac
  page does. scripts/test-examples.ts notes the local bare shim is
  unreliable on Linux.
- The qvac page: the update worker only starts when updates are on and
  upgrade is a real link, so the default npm start runs one worker;
  --model takes completion models only, since only llamacpp-completion
  is registered; --verbose is now explained; the offline claim is
  dropped because upstream does not make it.
- The home page lists hello-pear-qvac-tui next to hello-pear-daemon.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
* feat(refgen): carry author sections and README patches in layouts

A layout can now append author-written sections (inline or from
<name>.sections.json) and patch README-derived blocks by exact text, for
what a .d.ts can't carry, such as the event tables of modules that don't
export their event maps. A patch that no longer matches fails the render, so
one that upstream has made redundant gets noticed. Same shape as on the
docs/new-bare-module-pages-2026-10 branch, so the two merge cleanly.

The dossier also skips README sections about running the tests (Testing on
device, Running the tests under ASan), which are for contributors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): refresh the Bluetooth references and add bare-bluetooth and bare-bluetooth-linux

Both platform READMEs send readers to these pages for their API, so they
need to track upstream:

- bare-bluetooth-apple 0.5.1 -> 0.7.0: showPowerAlert, retrievePeripherals()
  and retrieveConnectedPeripherals(), and an Errors table. The README's
  usage passes serviceAdd an error argument it never receives; a layout
  patch drops it.
- bare-bluetooth-android 0.9.1 -> 0.11.3: Server.open()/close(),
  getBondedDevices(), ADAPTER_UNAVAILABLE, peripherals built from a Device,
  an Events table checked against every emit() in lib/ (the package doesn't
  export its event maps), and the README's Errors section.
- bare-bluetooth 0.6.3-0 (npm latest, a prerelease that adds Linux):
  hand-written, since the package ships no .d.ts. Based on the 0.6.0 draft
  from docs/new-bare-module-pages-2026-10, without Server.open()/close(),
  which 0.6.2 removed. The usage compares UUIDs through the expand() helper
  from example/gattpong.js; the README's === comparison fails on every
  platform. Linux permission constants differ in value, so the table shows
  both.
- bare-bluetooth-linux 0.9.2: generated, now that it ships types.

Also links the wrapper from the catalog and adds both new pages to the
sidebar.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): add Bluetooth how-to guides and explanation pages

Task-oriented Bluetooth docs for Bare, with every code block imported from
an existing upstream implementation rather than written for these pages.

How To > Connect over Bluetooth (new folder):
- Build a Bluetooth chat for iOS and Android: a walkthrough of
  bare-mobile-doctor's dual-role L2CAP chat worklet.
- Set up Bluetooth in a mobile app: iOS usage string, Android 12+ runtime
  permissions, bare-link/bare-pack, from bare-mobile-doctor and
  bare-bluetooth-android's native Kotlin test app.
- Exchange data over L2CAP and Read, write and subscribe with GATT: from the
  bare-bluetooth example/ scripts, plus the PSM-in-a-characteristic handover.
- Use platform-specific Bluetooth features: retrieve and reconnect on Apple,
  bonded devices, MTU and scan mode on Android.

About Bare:
- Bluetooth in Bare: module family, roles, GATT vs L2CAP, ids, security.
- Bluetooth best practices: each rule cites the upstream code it comes from.

Vendored pinned snapshots live under examples/how-to/connect-over-bluetooth/,
each with a README giving the upstream URL, commit and license. They are not
wired into test-examples.ts because they need physical radios.

Also wires the sidebar, the How To index, See also links from the Bluetooth
reference layouts and bare-on-native, and the ble-swarm note on the
Hyperswarm page.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(bare): fix Bluetooth guide claims found in review

Corrections checked against the pinned upstream code:
- iOS destroy(): the bare-bluetooth-apple fixes (#53, #56, #58) predate both
  consumers' workaround comments, so call the workaround possibly stale, limit
  it to iOS (ble-swarm destroys managers on macOS and Android), and drop the
  "since merged" ordering.
- Connection timeout: bare-mobile-doctor's BLECentral.disconnect() only acts
  once connected, so its 15s timeout does not cancel the pending attempt.
- Power cycle: _start() is guarded by serviceAdd/PSM flags that are never
  reset, so the sample does not re-add its service after a Bluetooth toggle.
- Errors: some calls throw (startScan, Android Java exceptions, Linux
  disconnect, platform packages); add a try/catch rule.
- PSM: Linux accepts publishChannel({ psm }); ble-swarm sends the PSM in a
  HELLO frame, not a readable characteristic.
- UUIDs: CoreBluetooth shortens to the 16-bit form only; drop the unverified
  "fails on all platforms" claim.
- Remove the unsourced split-characteristic rule, the "builds peer-to-peer
  apps on" claim and the ADVERTISE_FAILED overstatement; mark ble-swarm
  experimental and pin its version.

Additions: deadline on openL2CAPChannel, missing chat prerequisites (patchelf,
Gradle wrapper, iOS signing, adb install), test helpers in the platform
snippets, macOS terminal Bluetooth permission, clone the v0.6.3-0 tag, a home
page card, descriptions trimmed to 160 characters, and the ble-swarm excerpt
now complete with a pinned permalink.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* test(refgen): cover layout patches and author-written sections

The render-time guarantees added with the layout feature had no tests: a
patch must hit exactly once, a patch aimed at a missing block fails, and a
patch can reach a README section by heading. Also covers the order of
author-written sections and the dangling-anchor stripping they go through.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(bare): fix the Bluetooth reference review findings

- bare-bluetooth-linux: mark it experimental, as its README does, so the
  badge no longer contradicts the page; add the marker to its catalog row.
- bare-bluetooth-apple: document what showPowerAlert does and its default,
  and drop the connect/disconnect parameter overrides that hid upstream's
  text for RetrievedPeripheral and pending connections.
- bare-bluetooth-android: rename the Events sub-headings to "Central
  events" and so on, so their ids no longer collide with the API headings.
- bare-bluetooth: Linux filters discoverServices and discoverCharacteristics
  too; the Linux-only read/write defaults no longer read as general; link
  gattpong.js at the v0.6.3-0 tag; the usage example guards against
  connecting twice and against BlueZ's cached devices, as gattpong.js does.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* chore(docs): watch bare-bluetooth-linux and refresh the Bluetooth dossier

The commit-level upstream check now watches bare-bluetooth-linux, and the
recorded commits for bare-bluetooth-apple and -linux are the ones the
documented tags contain, so the daily job does not report work already done.

The research dossier had the three generated modules patched by hand while
the digest was left behind. Replace the four Bluetooth records with a fresh
run of the research script and re-render the digest from them, so the two
files agree again. Every other record is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(bare): bring the Bluetooth guides up to date with the latest releases

Upstream moved after the guides were written:
- bare-bluetooth 0.6.3 (stable): Android reports 'unsupported' when there is
  no adapter instead of throwing from the constructor, and assigning `value`
  on a discovered characteristic throws everywhere.
- bare-bluetooth-android 0.11.4 and bare-bluetooth-apple 0.7.1: the
  discovered-characteristic `value` rejection, plus init leak fixes.
- ble-swarm 2.4.0: Linux added to its import map; lib/ is unchanged, so the
  excerpt and permalinks keep their line numbers.
- bare-mobile-doctor 5bfe51b: app.json gains iOS build options and
  package.json moves to bare-bluetooth ^0.6.3; the Bluetooth worklet, screen
  and link script are unchanged.

Repin the vendored snapshots and every permalink to those commits (the
upstream-only changes in app.json, package.json and test/peripheral.js are
copied over and the #L ranges moved to match), point the clone instructions
at the v0.6.3 tag, say "0.6.3" where the guides said "0.6.3-0", and document
the unsupported state and the discovered-characteristic rule.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(bare): group Bluetooth explanations in a folder and link every API

- Move the two Bluetooth explanation pages into
  content/bare/explanation/bluetooth/ (index.mdx for "Bluetooth in Bare",
  best-practices.mdx), add a "Bluetooth" folder to the Bare sidebar, and
  update every link to the new URLs.
- Link the classes, methods, events, constants and platform APIs that the
  explanations and the how-to guides use, to the module references and to
  the Apple, Android, React Native and Expo documentation.
- Edit for the Google developer documentation style: numbered lists for
  steps, bullets for parallel items, callouts for tips, warnings and notes,
  and plain, active sentences.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(bare): fix Bluetooth guide claims found in adversarial review

- Android GATT server: tell readers to close() when the adapter leaves
  'on' before reopening, and warn that bare-bluetooth-android does not
  queue requestMtu() behind other GATT calls.
- Static characteristic `value` does not stop Android from raising
  readRequest for every read.
- ble-swarm: 2.4.0 maps Linux to bare-bluetooth (treat as untested), it
  has no lifecycle hook (the app calls suspend() and resume()), and its
  teardown and channel-rotation behavior is described as upstream does it.
- Error routing: CONNECTION_FAILED and DISCONNECT take different paths in
  bare-mobile-doctor; link the Android BluetoothError entries.
- Chat guide: run `npm run link` before `pod install`, prebuild Android
  before the Gradle downgrade, and fix the callout about advertising
  after a Bluetooth toggle.
- Set-up guide: pin the test-app link (upstream main removed it), point
  neverForLocation at the page that documents it, and fix the
  requestPermissions() fragment.
- Ignore the vendored Bluetooth snapshots in ESLint (one uses `using`) and
  stop the Examples workflow from running for them.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(bare): fix the remaining Bluetooth review findings

- Scope upstream claims to what the sources say: ble-swarm's README calls
  the iOS channel hang historical, scan.js doesn't advertise, and a vanished
  iOS peer needs keepalives because it raises no disconnect event.
- Restore "usually the better fit" for L2CAP over GATT, and order the PSM
  recipe the way best practices does (publish, advertise once ready, open).
- Match prose to the imported ranges in the L2CAP, platform-specific and
  set-up guides, and say what the GATT server snippet's helper does.
- Link stream events and write() to bare-stream, where they are documented.
- Link each ble-swarm try/catch claim to the file that holds it.
- Stop claiming bare-link writes a `*.classes.jar`; say it copies the
  helper classes next to the addon.
- Mention Bluetooth and on-device AI on the Bare how-to index, list every
  importing guide in the mobile-doctor snapshot README, and record why the
  snapshots aren't watched by watch-boilerplates.yml.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* ci(examples): watch the Bluetooth snapshots for upstream drift

Enroll bare-bluetooth, bare-bluetooth-android, bare-bluetooth-apple and
bare-mobile-doctor in watch-boilerplates.yml, each at the commit its
snapshot README records, so a tracking issue opens when upstream moves
past it and the `#L` ranges in the Bluetooth guides need a re-check.
Android and Apple are already ahead of their pins, so the first run
opens two issues.

Replace the "not watched" notes in the snapshot READMEs with a Refreshing
section, as the other snapshots have, and point the examples.yml comment
at the watcher.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…ages with 3.6.0 (#423)

* docs(pear): reconcile the cli, release overview and troubleshooting pages with 3.6.0

The Pear 3.6.0 fact-check, run against v3.5.0 and v3.6.0 builds of
holepunchto/pear and the pear-runtime-updater 3.4.0 source, found three
pages that contradicted live behavior.

- cli.mdx: the "Scripting with --json" callout said the next-step hint
  goes to stdout after the link since 3.3.0, so LINK=$(pear touch)
  captures it. That holds on 3.3.0 only. hint() writes to stdout in
  v3.3.0 and to stderr in v3.4.0, v3.5.0 and v3.6.0, and pear touch
  prints just the link on stdout there. The callout now scopes the leak
  to 3.3.0. The --vanity paragraph made the same claim ("from 3.3.0 the
  next-step hint does") and says the same thing now.
- release-overview: the 3.6.0 lede counted three changes that can
  affect a script. It counts four now, adding the pear info writable row
  (which shifts every row after it) and the ", uptime <time>" ending on
  the pear seed network line under --no-tty, and says --json carries
  writable and uptime.
- troubleshoot-desktop-releases: "Advance the release pointer after pear
  stage" described a pointer that does not exist. pear-runtime-updater
  listens for append on the drive behind the upgrade link, checks out
  the latest length, and downloads by-arch/<host>/app/<name> when the
  manifest version is higher than the running build's. The section is
  now "Stage to the link the app follows". It keeps the point that a
  stage link and a production link are different drives, and "Bump
  version" is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(pear): count the install exit code and the 3.3.0 hint leak, drop the v3 pointer wording

Follow-up to the previous commit, covering what it left alone.

- release-overview, 3.6.0: the lede counts five script-affecting
  changes. It adds pear install exiting 1 when an install fails
  (pear-install 1.4.0 sets process.exitCode on a failed final object;
  1.3.0, which Pear 3.5.0 bundles, never did), and covers the
  message-only ERR_INVALID_APP_NAME output inside the pear build item.
  The error code and message are the same in pear-build 1.3.0 and 1.3.2;
  only the stack trace is gone.
- release-overview, 3.3.0: says the next-step hints were written to
  stdout, so LINK=$(pear touch) captured the hint block, and that 3.4.0
  moves them to stderr. The lede now counts two script-affecting changes.
- cli.mdx and release-overview, 3.0.0: the removed pear release entries
  said a "single-key release pointer" was replaced by quorum cosigning,
  which reads as if v3 still has a pointer that cosigning moves. They now
  say v3 has no release pointer, and that a production release is a
  quorum-signed commit onto the production link.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
…y hand edits in refgen layouts (#426)

* docs(bare): refresh the Bluetooth references for bare-bluetooth 0.6.4

Checked against the published packages:

- bare-bluetooth 0.6.3 -> 0.6.4, now `latest`: the version callout keeps
  0.6.3 as the release that added Linux, and the dependency ranges are
  android ^0.11.6, apple ^0.8.0 and linux ^0.9.2. The Peripheral `name`
  row notes the Apple and Android fallback to the device's own name.
- bare-bluetooth-apple 0.7.1 -> 0.8.0: the central now keeps `discover`
  results until the next startScan() instead of dropping them at
  stopScan(), so the connect() note was backwards. Adds the `nameChange`
  event, and `name` falls back to the GAP device name once connected
  (0.7.2).
- bare-bluetooth-android 0.11.4 -> 0.11.6: adds the NOT_CONNECTED factory,
  which lib/errors.js defines but lib/errors.d.ts doesn't declare. The
  Peripheral calls that talk to the device throw it before 'connect' and
  once the link is gone. `name` falls back to the device's own name once
  connected (0.11.5).
- Linux failures: a failed connect arrives as `error` with code
  CONNECTION_FAILED (bare-bluetooth-linux's Device.connect() rejects with
  it), and a dropped link arrives as `disconnect`, since BlueZ only flips
  the Connected flag. Added to the reference and best practices.
- Android host: bare-bluetooth-android reads the JVM from the
  bare.android.jvm.v1 context key at load. Bare Kit publishes it from
  2.5.0, and react-native-bare-kit loads Bare Kit so that it captures the
  JVM only from 0.15.2 (holepunchto/react-native-bare-kit#53). Stated on
  the explanation page, the mobile setup guide and both references.

The generated previews are regenerated at the new versions. What the
generator can carry went into the layouts: the startScan() and nameChange
text in describe.json, and the Android intro and Errors patch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): add a ble-swarm reference

ble-swarm had no page on the site; the Hyperswarm reference said so, and
the Bluetooth pages linked only to its repository. The new page sits next
to bare-bluetooth, since the module runs only on Bare through it.

It documents 2.4.0 from its source, since the package ships no type
declarations: the options, properties, state values, methods and events,
toServiceUUID(), the platform mapping (including the stub that reports
'unsupported'), how a link forms, and the two pipes. Where the README and
the source disagree, the page follows the source and says so:

- maxOutbound caps live links before dialing stops, not concurrent dials.
- setTopic() closes existing connections rather than moving them, so the
  README's usage comment is corrected.
- scanOptions, debug, started, suspended and toServiceUUID() exist but are
  not in the README.

The page is in the Bare sidebar and the modules catalog, and every
ble-swarm mention that linked to GitHub now links to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(refgen): carry the Bluetooth hand edits in layouts

#419 hand-edited the generated bare-bluetooth-apple and -android pages
without touching their layouts, so `gen:bare-refs --write` would have
dropped those edits. The layouts couldn't hold most of them: `describe`
only fills a missing description and `patch` reaches README blocks only.

Layouts gain:

- `memberPatch`: { member, from, to } exact-text edits to one member's
  rendered block, which can replace or extend upstream TSDoc.
- `extraMembers`: { after, body } blocks for symbols the .d.ts doesn't
  carry, rendered after the named member.
- `patch` with `in: 'intro'`, for text between the install fence and
  Usage.

Both new fields apply to the docs page only, not the README API that
emit-tsdoc writes. Like `patch`, they fail the render when `from` doesn't
occur exactly once or the member doesn't resolve to exactly one entry, so
an edit that upstream TSDoc overtakes gets reviewed instead of hiding the
new text. Long Markdown lives in <name>.patches.json and
<name>.members.json, and check:bare-refs validates their member refs.

Every hand edit on both pages now comes from the layouts: TSDoc rewrites
and version notes in patches.json, parameter text in `params`, the See also
comparisons in `seeAlso`, and Android's NOT_CONNECTED factory and event
maps (which the package root doesn't re-export) in members.json. With
--write, the Apple page is unchanged. The Android page loses only the stale
duplicate `open()` entry that #419 left behind the hand-written one, so it
has a single #open-void anchor again. The previews now equal the pages.

Tests cover member patches, extra members, their failure modes and the
intro target. The refgen README lists every layout field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…eo, fumadocs 16.17 (#427)

* fix(llms.txt): list every page, grouped by product and quadrant

The route keyed sections on the first URL segment (getting-started,
how-to, ...), which stopped matching after the Pear/Bare/P2P split moved
every page under /pear, /bare or /p2p. Since then llms.txt has listed
only the homepage.

Group pages by product (first segment) and quadrant (second), with the
root and product landing pages under Overview. Unknown segments still get
a section instead of being dropped. Follow the llmstxt.org shape: site
name as H1, a blockquote summary, absolute links to each page's Markdown
version, and llms-full.txt under Optional.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(md): bump fumadocs-mdx to 14.2.14 so .md twins keep heading markers

fumadocs-mdx 14.2.7 serialized processed Markdown with a custom heading
handler that returned the flattened heading text plus `[#id]` and dropped
the `#` markers. Every .md twin and llms-full.txt lost its heading
structure: about 6,000 headings came out as plain paragraphs, and inline
code in headings was stripped. 14.2.14 delegates to mdast's default
heading handler, and also drops MDX import lines.

14.2.14 introduces its own bug: its stringifier wraps every toMarkdown
handler without copying `peek`, so mdast-util-to-markdown mispredicts the
next character and entity-encodes attention markers (`&#x2A;*bold**`,
closing backticks as `&#x60;`, 99 lines). restoreMarkdownPeek puts `peek`
back through the `stringify` hook that includeProcessedMarkdown passes
to the stringifier. 14.3.x has the same wrapper, so remove the hook once
upstream copies `peek`.

Against the live .md files: 6,229 headings restored, 43 import lines
removed, 0 entities, code lines unchanged (12,691). The only other
change is that JSX expression attributes now serialize as strings.
fumadocs-mdx 15 was tried and rejected: it serializes from the authored
source, which drops `file=` code imports, `<include>` expansion and MDX
comment stripping.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(seo): add check:seo for built SEO output

By default it asserts invariants on out/ that hold for any content, so CI
can run it after a build: title, description, self-canonical, index
robots, Open Graph and Twitter tags (with the og:image file present), and
JSON-LD whose url is the page. It also checks that robots.txt points at
the sitemap and carries Content-Signal, and that the sitemap lists
exactly the indexable pages.

--snapshot and --compare record and diff every page's SEO head, JSON-LD,
robots.txt, sitemap.xml and OG image hashes, for refactors that must not
change SEO output.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(seo): compare sitemap entries as a set in check:seo --compare

source.getPages() returns pages in a different order from build to build,
so the same sitemap can come out reordered. Order carries no SEO meaning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(seo): vendor @tetherto/docs-seo-* into src/lib/seo

The four packages came from GitHub Packages, so every install needed a
GITHUB_TOKEN with read:packages, and CI could never run `npm install` or
`next build`. They also shipped raw TypeScript (transpilePackages), and
docs-seo-core typed pages as fumadocs' `Page<TetherPageData>`, which
breaks under fumadocs-core 16.17's `Page<Type, Data>`.

About 800 lines are now in the repo:
- src/lib/seo/: core, metadata, robots, sitemap, json-ld, og
- scripts/og/precompute.tsx: the Takumi OG prebuild

Only imports and types change. The logic is copied verbatim, and each
file names the package version it came from.

- `TetherPage` is now structural ({ url, slugs, data }), so any fumadocs
  page fits it regardless of the Page generics.
- src/lib/seo/schema.ts holds the frontmatter schema. It replaces the
  copy source.config.ts used to inline.
- Unused exports (docsOgGet, docsOgGenerateStaticParams,
  SEO_SCHEMA_VERSION) are dropped.
- The log prefix and the DOCS_SEO_* env vars are unchanged.
- glob and gray-matter, which the OG prebuild uses, become direct
  dependencies.
- .npmrc and the GITHUB_TOKEN setup steps are gone. `npm ci` now works
  without a token.

`check:seo --compare` against a build from before this change finds no
differences: every page's head and JSON-LD, robots.txt, the sitemap
entries, and all 246 OG images byte for byte. The .md twins are
byte-identical.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(deps): fumadocs-core and fumadocs-ui 16.17.8

fumadocs-mdx stays on 14.2.14. mdx 15 serializes Markdown from the
authored source, which drops `file=` code imports, `<include>` expansion
and MDX comment stripping from the .md twins.

- shiki 4 comes in through core, so @shikijs/transformers moves to ^4.5.0
  to match.
- Core's static search client and the /api/search.json export now use
  zbsearch instead of Orama. search.tsx builds its fallback index with
  zbsearch's `create`, and zbsearch is a declared dependency. The exported
  index is 27 MB instead of 47 MB (4.1 MB gzipped instead of 7.1 MB).
- The docs grid gained outer gutter tracks (five columns). global.css
  zeroes them so sidebar, main and toc keep their current sizes. Without
  that, the three-column override collapses `main` to 0 px.
- Core's LLMsOptions type no longer lists `stringify`, but mdx 14.2.14
  still runs its own stringifier, which reads it. So the
  restoreMarkdownPeek option is cast to LLMsOptions.

Checked against a build from before the upgrade:
- `check:seo --compare` finds no differences: head, JSON-LD, robots,
  sitemap entries and all 246 OG images.
- The .md twins and llms.txt are byte-identical.

Checked against docs.pears.com in the browser at 1024, 1440 and 2560 px
and on mobile, light and dark: grid positions, TOC, code blocks, tables,
Steps, Tabs, the mobile drawer, the MCP popover, and both search paths
(QVAC, and the static fallback with QVAC blocked) all match, with no
console errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: address review findings on the ai-readiness PR

- OG prebuild skips `_`-prefixed snippet files, matching the `files` rule in
  source.config.ts. It rendered 246 images for 231 pages.
- generate-llm-md-files fails the postbuild when a .md twin has entity-encoded
  `*` or backticks, a heading without its `#`, or no headings at all, so a
  fumadocs-mdx bump can't silently undo the heading and peek fixes.
- check:seo also asserts that llms.txt links every page's .md twin on the
  sitemap origin and that each linked file exists. A flag without a value now
  exits non-zero instead of falling through to the invariants run, and
  normalizeSitemap no longer interprets `$` patterns in sitemap entries.
- restore-markdown-peek collects `peek` from the mdx and gfm extension handler
  tables instead of a hand-written list. mdast-util-gfm and mdast-util-mdx
  become direct dependencies; both were already installed at the same versions.
- JSON-LD escapes `<` so a `</script>` in a title or description can't end the
  script block.
- check-doctypes imports `productSchema` from src/lib/seo/schema.ts instead of
  copying the product list.
- Drops the dead `inferJsonLdType` branches and the redundant `toAbsoluteUrl`
  ternary. Behaviour is unchanged.
- Drops the `GITHUB_TOKEN: ''` overrides and the "token-gated @tetherto"
  comments left over from the deleted .npmrc. The throwaway-prefix installs in
  the workflows stay as they are.
- Renames `initOrama` and the Orama comments to match zbsearch.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(ci): install zod for the doctypes job

check-doctypes.ts now imports productSchema from src/lib/seo/schema.ts, which
imports zod. The doctypes job installs only tsx and github-slugger into a
throwaway prefix, so it failed with ERR_MODULE_NOT_FOUND for 'zod'. Install
zod there too, and run the workflow when the schema file changes.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…wn negotiation, site CI (#431)

* fix(llms.txt): list every page, grouped by product and quadrant

The route keyed sections on the first URL segment (getting-started,
how-to, ...), which stopped matching after the Pear/Bare/P2P split moved
every page under /pear, /bare or /p2p. Since then llms.txt has listed
only the homepage.

Group pages by product (first segment) and quadrant (second), with the
root and product landing pages under Overview. Unknown segments still get
a section instead of being dropped. Follow the llmstxt.org shape: site
name as H1, a blockquote summary, absolute links to each page's Markdown
version, and llms-full.txt under Optional.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(md): bump fumadocs-mdx to 14.2.14 so .md twins keep heading markers

fumadocs-mdx 14.2.7 serialized processed Markdown with a custom heading
handler that returned the flattened heading text plus `[#id]` and dropped
the `#` markers. Every .md twin and llms-full.txt lost its heading
structure: about 6,000 headings came out as plain paragraphs, and inline
code in headings was stripped. 14.2.14 delegates to mdast's default
heading handler, and also drops MDX import lines.

14.2.14 introduces its own bug: its stringifier wraps every toMarkdown
handler without copying `peek`, so mdast-util-to-markdown mispredicts the
next character and entity-encodes attention markers (`&#x2A;*bold**`,
closing backticks as `&#x60;`, 99 lines). restoreMarkdownPeek puts `peek`
back through the `stringify` hook that includeProcessedMarkdown passes
to the stringifier. 14.3.x has the same wrapper, so remove the hook once
upstream copies `peek`.

Against the live .md files: 6,229 headings restored, 43 import lines
removed, 0 entities, code lines unchanged (12,691). The only other
change is that JSX expression attributes now serialize as strings.
fumadocs-mdx 15 was tried and rejected: it serializes from the authored
source, which drops `file=` code imports, `<include>` expansion and MDX
comment stripping.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(seo): add check:seo for built SEO output

By default it asserts invariants on out/ that hold for any content, so CI
can run it after a build: title, description, self-canonical, index
robots, Open Graph and Twitter tags (with the og:image file present), and
JSON-LD whose url is the page. It also checks that robots.txt points at
the sitemap and carries Content-Signal, and that the sitemap lists
exactly the indexable pages.

--snapshot and --compare record and diff every page's SEO head, JSON-LD,
robots.txt, sitemap.xml and OG image hashes, for refactors that must not
change SEO output.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(seo): compare sitemap entries as a set in check:seo --compare

source.getPages() returns pages in a different order from build to build,
so the same sitemap can come out reordered. Order carries no SEO meaning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(seo): vendor @tetherto/docs-seo-* into src/lib/seo

The four packages came from GitHub Packages, so every install needed a
GITHUB_TOKEN with read:packages, and CI could never run `npm install` or
`next build`. They also shipped raw TypeScript (transpilePackages), and
docs-seo-core typed pages as fumadocs' `Page<TetherPageData>`, which
breaks under fumadocs-core 16.17's `Page<Type, Data>`.

About 800 lines are now in the repo:
- src/lib/seo/: core, metadata, robots, sitemap, json-ld, og
- scripts/og/precompute.tsx: the Takumi OG prebuild

Only imports and types change. The logic is copied verbatim, and each
file names the package version it came from.

- `TetherPage` is now structural ({ url, slugs, data }), so any fumadocs
  page fits it regardless of the Page generics.
- src/lib/seo/schema.ts holds the frontmatter schema. It replaces the
  copy source.config.ts used to inline.
- Unused exports (docsOgGet, docsOgGenerateStaticParams,
  SEO_SCHEMA_VERSION) are dropped.
- The log prefix and the DOCS_SEO_* env vars are unchanged.
- glob and gray-matter, which the OG prebuild uses, become direct
  dependencies.
- .npmrc and the GITHUB_TOKEN setup steps are gone. `npm ci` now works
  without a token.

`check:seo --compare` against a build from before this change finds no
differences: every page's head and JSON-LD, robots.txt, the sitemap
entries, and all 246 OG images byte for byte. The .md twins are
byte-identical.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(deps): fumadocs-core and fumadocs-ui 16.17.8

fumadocs-mdx stays on 14.2.14. mdx 15 serializes Markdown from the
authored source, which drops `file=` code imports, `<include>` expansion
and MDX comment stripping from the .md twins.

- shiki 4 comes in through core, so @shikijs/transformers moves to ^4.5.0
  to match.
- Core's static search client and the /api/search.json export now use
  zbsearch instead of Orama. search.tsx builds its fallback index with
  zbsearch's `create`, and zbsearch is a declared dependency. The exported
  index is 27 MB instead of 47 MB (4.1 MB gzipped instead of 7.1 MB).
- The docs grid gained outer gutter tracks (five columns). global.css
  zeroes them so sidebar, main and toc keep their current sizes. Without
  that, the three-column override collapses `main` to 0 px.
- Core's LLMsOptions type no longer lists `stringify`, but mdx 14.2.14
  still runs its own stringifier, which reads it. So the
  restoreMarkdownPeek option is cast to LLMsOptions.

Checked against a build from before the upgrade:
- `check:seo --compare` finds no differences: head, JSON-LD, robots,
  sitemap entries and all 246 OG images.
- The .md twins and llms.txt are byte-identical.

Checked against docs.pears.com in the browser at 1024, 1440 and 2560 px
and on mobile, light and dark: grid positions, TOC, code blocks, tables,
Steps, Tabs, the mobile drawer, the MCP popover, and both search paths
(QVAC, and the static fallback with QVAC blocked) all match, with no
console errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: address review findings on the ai-readiness PR

- OG prebuild skips `_`-prefixed snippet files, matching the `files` rule in
  source.config.ts. It rendered 246 images for 231 pages.
- generate-llm-md-files fails the postbuild when a .md twin has entity-encoded
  `*` or backticks, a heading without its `#`, or no headings at all, so a
  fumadocs-mdx bump can't silently undo the heading and peek fixes.
- check:seo also asserts that llms.txt links every page's .md twin on the
  sitemap origin and that each linked file exists. A flag without a value now
  exits non-zero instead of falling through to the invariants run, and
  normalizeSitemap no longer interprets `$` patterns in sitemap entries.
- restore-markdown-peek collects `peek` from the mdx and gfm extension handler
  tables instead of a hand-written list. mdast-util-gfm and mdast-util-mdx
  become direct dependencies; both were already installed at the same versions.
- JSON-LD escapes `<` so a `</script>` in a title or description can't end the
  script block.
- check-doctypes imports `productSchema` from src/lib/seo/schema.ts instead of
  copying the product list.
- Drops the dead `inferJsonLdType` branches and the redundant `toAbsoluteUrl`
  ternary. Behaviour is unchanged.
- Drops the `GITHUB_TOKEN: ''` overrides and the "token-gated @tetherto"
  comments left over from the deleted .npmrc. The throwaway-prefix installs in
  the workflows stay as they are.
- Renames `initOrama` and the Orama comments to match zbsearch.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(ci): install zod for the doctypes job

check-doctypes.ts now imports productSchema from src/lib/seo/schema.ts, which
imports zod. The doctypes job installs only tsx and github-slugger into a
throwaway prefix, so it failed with ERR_MODULE_NOT_FOUND for 'zod'. Install
zod there too, and run the workflow when the schema file changes.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* feat(mcp): advertise the live MCP server to agents

mcp.pears.com is deployed but nothing machine-readable pointed at it.

- Add /.well-known/mcp/server-card.json (streamable-http, tools
  search_docs and fetch_doc, no authentication).
- Add an application/mcp-server-card+json entry to ai-catalog.json.
- Add an mcp-server-card relation to the site-wide Link header.
- Add an MCP server line to llms.txt when NEXT_PUBLIC_MCP_URL is set.
- Extend check:agent-ready to validate the card and its ARD and Link
  references.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(redirects): generate Accept: text/markdown rules for every page depth

The negotiation rules were hand-written for four path depths, so the 94
pages five segments deep got HTML for Accept: text/markdown.

generate-redirect-stubs.ts now expands a marker line in public/_redirects
into one rule per depth, up to the deepest .md twin in out/, and
check:redirects asserts a rule exists for every depth with a twin.

Also correct the ai-catalog.json claim: only the exact header
Accept: text/markdown matches, not weighted lists (needs a zone rule).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(ai): point "Open in ChatGPT/Claude/Cursor" at the page's Markdown

The prompt quoted the raw GitHub MDX file, where the 154 code blocks that
use file= imports are empty. Quote the absolute .md URL instead, which
has the code inlined.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(md): turn MDX components in the .md twins and llms-full into plain Markdown

The processed Markdown that feeds the per-page .md files, llms-full.txt and
Copy page still carried 1,264 lines of JSX and 430 code fences with
file=/skip=/example= meta. Add cleanProcessedMarkdown and run it in
getLLMText:

- Callout becomes a GitHub alert (> [!NOTE], [!WARNING], [!TIP]).
- Card becomes a list item with its link and description; the old regex
  cleaner in the MCP corpus drops these entirely.
- Tab and Accordion become a bold label line, so OS-specific install
  commands stay attributable.
- Steps, Tabs, Cards, Accordions and Step are unwrapped and dedented, so
  the content no longer reads as an indented code block.
- VersionGate becomes an "Added in / removed in" line; Since, Until and
  Status become inline text.
- Mermaid becomes a mermaid fence with its entities decoded.
- Fence info keeps the language and title= only.

Checked against all 231 current pages: no JSX left outside code, and every
other line survives unchanged apart from indentation and the > prefix.

generate-mcp-corpus.ts keeps its own cleaner: it works on raw MDX
sources, not on processed Markdown, so the two can't share one.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* feat(llms): add Source lines and per-product dumps to llms-full.txt

- Each page in llms-full.txt now starts with "Source: <canonical URL>".
- Pages are sorted by URL, so the file no longer reorders between builds.
- Add /pear/, /p2p/ and /bare/llms-full.txt (all three were one 3.6 MB
  file), and list them in the Optional section of llms.txt.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* test(ci): build the site in CI and smoke-check the live deploy

Nothing in CI built the site, because npm ci needed a token before the SEO
packages were vendored. So the broken llms.txt, the heading-less .md twins
and the missing 303 rules shipped without a failing check.

- site-checks.yml builds the site on PRs and runs check:redirects,
  check:agent-ready and check:seo against out/.
- scripts/check-live-site.ts (npm run check:live) fetches the deployed
  site and checks that llms.txt lists the same pages as the sitemap, that
  sampled .md files have headings and no import lines, JSX or entities,
  that Accept: text/markdown 303s to the .md file, that each llms-full dump
  has one Source line per page, that the Link header and server card are
  served, and that the MCP server answers initialize and tools/list.
- A weighted Accept header is only a warning until the zone rule exists.
- live-smoke runs it after a push to published and retries for 20 minutes
  while the deploy lands. Scheduled workflows never fire here, since the
  default branch carries no workflows.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(llms): use canonical URLs in Source lines and include product landing pages

The Source lines dropped the trailing slash that the sitemap and canonical
links use, and the per-product dumps skipped each product's landing page.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(deps): make package-lock.json installable with npm 10

npm ci on npm 10 (what Node 22 ships, and what the new site-checks
workflow uses) failed with "Missing: zod@3.25.76 from lock file". npm 11
leaves out optional peer dependencies and bundled WASM packages that npm 10
records, so a lockfile written by npm 11 only passes npm 11.

Regenerated with npm 10 (--package-lock-only); npm ci now passes on both.
The same failure exists on published.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(seo): Markdown alternate links, unique titles, stable sitemap, pinned origin (#434)

* docs: tag the 37 code fences that had no language

The Pear and Bare CLI references fenced their flag listings, usage lines
and sample output without a language, so tools reading the Markdown could
not tell them from prose. Sample output and flag listings are text; the
three commands (pear install, pear dump, pear gc) are sh.

bare-bundle is generated, so its fix is a layout patch for the README's
format sketch rather than an edit to the page; the regeneration changes
only that fence.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(headers): send Vary: Accept

A page's HTML and Markdown representations share one URL, selected by the
Accept header via the 303 rule in _redirects. Cloudflare ignores Vary, but
other caches honor it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(build): pin NEXT_PUBLIC_DOCS_ORIGIN in .env.production

The origin was correct live only because the host's build environment set
it. A build without it silently emitted http://localhost:8080 canonicals,
sitemap entries and JSON-LD URLs. A value in the environment still wins.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* feat(seo): link each page to its Markdown version from the HTML head

Add <link rel="alternate" type="text/markdown"> pointing at the page's .md
file, so a client that fetched the HTML can find the Markdown without
sending Accept: text/markdown. check:seo asserts the link exists and its
file is in out/. This intentionally changes the SEO head of every page.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(seo): sort sitemap entries by URL

source.getPages() order varies between builds, so sitemap.xml reordered
itself without any content change. Sort by canonical URL, and have
check:seo assert the order.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(seo): give the 8 pages that shared a title their own

"Release Overview" and "Troubleshoot common issues" were each the <title>
of three pages (one per product), and "Getting started" of two. Add a
seoTitle to each, which sets the <title> and leaves the on-page heading
alone. check:seo now fails when two pages share a <title>.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…nces (#424)

* docs(bare): document Bare 1.36.0 and WebAssembly addons in the references

Bare 1.36.0 loads an addon's prebuilds/wasi-wasm32/<name>.wasm build,
sandboxed through WASI, when an import asks for it with the `host`
attribute or when the package has no native build. The support comes from
bare-module 7.5.0 in the v1.36.0 lockfile, not from Bare's own source.

New module references:
- bare-wasi 0.1.2, bare-directory 0.1.0, and bare-wasm 0.1.0 are generated
  from their typings. The curated prose lives in the refgen layouts, and a
  second --write leaves the pages byte-identical.
- bare-wasm-abi 0.1.1 is hand-written because it ships no typings.
- The catalog gets a WebAssembly section, and Node's `wasi` now maps to
  bare-wasi.

Refreshed references:
- bare-module 7.5.0: the `host` and `wasi` attributes, the `wasi` loader
  option, and a WebAssembly addons section.
- bare-module-traverse 2.7.2.
- bare-pack 3.0.2, including the breaking `resolveModule` argument.
- bare-sqlite 0.1.5, which adds its WebAssembly build.
- native-addon-prebuilds gets a WebAssembly prebuilds section.

Runtime page and release overview, for the rest of 1.36.0:
- `RangeError` for a `linger` or `deadline` above 0x7fffffff.
- The deprecated callback forms of `Bare.Thread`.
- The fallback to `.wasm` builds after `Addon.seal()`.
- A refreshed doc-state window, 1.28.2 to 1.36.0.
- Release-overview entries for v1.36.0 and the module updates.

Every behaviour claim was run on bare-runtime 1.36.0 on macOS arm64:
- Which `.wasm` builds load: bare-svg 1.1.1 and bare-heif 1.2.1 import
  js_add_teardown_callback, which bare-wasm-abi 0.1.1 lacks.
- The error codes, and that they surface while the importing module links.
- The post-seal fallback.
- The rights each bare-directory operation needs.
- That Bare has no `crypto` global, so the provider example in the
  bare-module README fails as written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): fix WebAssembly reference errors found in review

- bare-directory: rename() needs `remove` on the target directory whenever
  `replace` is true, even if nothing is replaced (binding.c:1056, run on
  1.36.0). Add an Options section for the unexported OpenOptions,
  OpenFileOptions and RenameOptions, and say which classes use the thread pool.
- bare-wasi: drop the "Mirrors the Node.js wasi module" line, which the
  page's own comparison contradicts. Document the WASIOptions defaults, the
  HostDirectory class comment, and the rename rights.
- bare-sqlite: document the rights the WebAssembly build needs (create and
  remove for the lock directory, write and truncate for writes), the stale
  lock that makes later opens fail with BUSY, the SQLiteError codes, and the
  real extension error message.
- bare-wasm: say each export is the WebAssembly global's member.
- bare-wasm-abi: list all ten libjs functions 0.1.1 neither implements nor
  excludes, and the UNEXPECTED_EXPORT error for a module that exports _start.
- bare-module, runtime, release overview: after a seal, a package without a
  .wasm build now throws ADDON_NOT_FOUND where 1.35 threw CANNOT_LOAD; import
  attributes must be string literals; errors from a computed require() can be
  caught; a literal import() also resolves before the seal.
- bare-pack: link the README's example folders on GitHub.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): correct the post-seal and dynamic import() WebAssembly notes

A native addon reached from any module linked before Bare.Addon.seal(),
not only from the sealing module, throws CANNOT_LOAD. A dynamic import()
with a wasi attribute throws ADDON_WASI_INCOMPATIBLE in bare-module 7.5.0.
Both were run on Bare 1.36.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): fix WebAssembly reference claims from the adversarial review

All run on Bare 1.36.0 unless noted.

- bare-sqlite: writing without `write` fails with CANTOPEN, not IOERR.
  Without `truncate`, a ROLLBACK of a grown transaction can report success
  and leave a hot journal. Only a killed process leaves the lock (Bare.exit,
  a throw and a normal exit release it), and with a stale lock the open
  succeeds and the first statement fails with BUSY. Bump the pin to 0.1.6
  (SQLite 3.54.1 only; same behaviour on re-run) and add it to the release
  overview.
- bare-wasi: without `write`, HostDirectory opens files for appending when
  `append` is granted; creating a file needs `write`; `clock: null` still
  leaks the time through timestamps set to now (index.js:417). The provider
  must install bare-wasi and bare-directory, because Bare's bundled bare-wasi
  can't be imported. Say that WASI limits only system calls.
- bare-directory: close() and restrict() are synchronous; the Right type
  comment understates when rename() needs `remove`.
- bare-module, runtime, release overview: bundles never fall back to .wasm
  after a seal (the preresolved path skips the loadable filter); the
  provider's native addons must load before the seal; computed attributes
  next to a literal specifier throw from the call and can be caught, and
  work with a computed specifier; a computed-specifier dynamic import()
  ignores the provider; ADDON_NOT_FOUND from a static import declaration
  can't be caught; the "linked in several contexts" message; a provider
  exporting { default } works, one returning nothing gives defaults; Bare
  1.36.0 also bumped bare-pipe to 4.4.0.
- bare-pack: a symlinked bundle works in place and fails with
  MODULE_NOT_FOUND only when moved; --out is skipped only when its
  directory is --base; the wasi-wasm32 host rule applies without a host
  attribute.
- native-addon-prebuilds: cmake-toolchains 2.1.1, which fixed the
  WebAssembly flags (#40).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…#428)

* fix(refgen): read param defaults only at the top level of a README signature

paramsFromSignature split each param on its first "=", including one nested
inside a destructured object. For protomux 3.13.0's
`mux.pair({ protocol, id = null }, callback)` that read the param as
`{ protocol, id` defaulting to `null }` and marked it optional, which the
curated preview then rendered as a bogus `options | null }` default row.

Skip "=" inside (), [] and {} so a destructured param keeps its inner
defaults and stays required.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs: regenerate API references from upstream

Rebuild the api-model, reference, improvement plan, JSDoc gap report and
curated preview for the three repos whose latest stable tag moved since the
last run:

- hypercore v11.37.2 to v11.39.4: adds core.count(); core.recover() takes opts
- corestore v7.13.0 to v7.16.1: adds store.purge(); store.staticify() takes
  opts = {}
- protomux v3.12.1 to v3.13.0: adds mux.watch(), mux.unwatch() and
  mux.unwatchAll(); pair and unpair take id = null

File hypercore `count` and protomux `watch`, `unwatch` and `unwatchAll` into
their curated layouts so the manifest gate passes. The other ten repos are
untouched: their tags have not moved, and several of their models carry
JSDoc-derived data that a forced regeneration would drop.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(bare): refresh the Bluetooth snapshots to upstream main

Re-pin bare-bluetooth, bare-bluetooth-android, bare-bluetooth-apple and
bare-mobile-doctor to upstream main (13bd28e, bc9f057, 806b596, b59f79b) and
move the guides' permalinks and clone tags with them.

- bare-bluetooth: only package.json changed upstream (0.6.4). example/ is
  byte-identical, so the three guides' ranges stay put. The L2CAP and GATT
  guides now say to clone v0.6.4, whose tree equals the pinned commit.
- bare-bluetooth-apple: test/central.js changed. The retrieved-peripheral test
  moves from L237-L278 to L238-L281 and gains a last line, and the guide now
  says what it checks. helpers.js link follows the pin, and waitForPoweredOn
  now rejects on poweredOff, unauthorized and unsupported, which the guide
  describes.
- bare-bluetooth-android: test/peripheral.js changed. The bonded-device test
  moves from L141-L184 to L164-L207 with identical content. Upstream deleted
  test/test-app/ in 6be8969, whose parent is the previous pin, so the three
  vendored files from it stay frozen at ca36e9b. The README, the workflow header
  and the guide's existing link to that tree say so.
- bare-mobile-doctor: bare/bluetooth.js and BluetoothTests.tsx are unchanged, so
  every permalink line number holds. scripts/link.mjs gains a worklet (L1-L31
  becomes L1-L32), and the guide now names bare-bluetooth ^0.6.4.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(bare): refresh bare-bluetooth-android entirely and document 0.11.7

Drop the three test-app files that were frozen at ca36e9b. Upstream deleted
test/test-app/ in 6be8969 and builds its test app from test/AndroidManifest.xml
with bare-native-test, so there is nothing on main to refresh them from.

- Vendor test/AndroidManifest.xml from bc9f057 and import its three Bluetooth
  permission lines in the mobile setup guide.
- Remove the Kotlin permission-request and Gradle link/pack snippets from that
  guide, which had no source left on main. The prose keeps the steps they
  showed, with links to the Android APIs.
- Say what 0.11.7 changes: the classes JAR embeds a keep rule for
  to.holepunch.bare.bluetooth.**, which the addon looks up by name through JNI.
  Earlier versions need the rule in the app's own R8 configuration.
- Regenerate the bare-bluetooth-android reference at 0.11.7. The API is
  unchanged: lib/ and index.js are identical between 0.11.6 and 0.11.7.
- Drop the frozen-files exception from the snapshot README and the
  watch-boilerplates header.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
….39.4 and 7.16.1 (#432)

* docs(p2p): re-point the hypercore and corestore source links to 11.39.4 and 7.16.1

Bump upstreamVersion on both pages and move every pinned [src] link to the
new tag. The edit is `syncSourceLinks` (scripts/refgen/sync.ts) run against
the models on docs/regenerate-p2p-references-2026-10, which never runs for
p2p pages because rate.ts only looks under content/bare/reference.

The sync resolves a heading to a model member by bare name, so seven links
it produced pointed at the wrong member and were fixed by hand:
- new Hypercore: lib/streams.js constructor -> index.js#L48
- core.snapshot: a stream property -> index.js#L230
- Hypercore.key and Hypercore.discoveryKey: the instance getters ->
  index.js#L133 and #L158
- new Corestore: the FindingPeers constructor -> index.js#L237
- handle.destroy: FindingPeers.destroy -> lib/notify.js#L20
- storeA.session: no model link, still on v7.13.0 -> index.js#L365

Every anchor was checked against the source at its tag. All 66 hypercore
lines are unchanged since 11.38.0. The corestore anchors sat one line below
their members already at 7.13.0.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(p2p): document core.recover, setRecoveryPeers and the working core.purge in the hypercore reference

Audit of hypercore 11.38.0 to 11.39.4. The upstream README did not change, so
these come from the source and tests.

- core.purge(): 11.39.0 reimplemented it on the RocksDB storage. Every 11.x
  release before that threw `TypeError: this._closeAllSessions is not a
  function`, because the helper was removed with the storage rewrite. The
  entry now says what is deleted, what survives, that it closes every
  session, the two errors it throws, and the release it starts working in.
- core.recover([options]): new entry. Public since 11.27.2, it gained
  `timeout` and `settle` and rejects when its session closes in 11.39.1 and
  11.39.2. It is only usable with Hypercore.setRecoveryPeers() (11.27.3), and
  core.recovering is the flag it clears, so all three get entries.
- Errors table: REQUEST_TIMEOUT, plus the new BAD_ARGUMENT, SESSION_CLOSED and
  SESSION_NOT_WRITABLE causes.

Left out on purpose: the shared in-flight storage reads for concurrent
core.get() calls (11.39.4) and the replicator teardown fixes (11.39.3 and
11.39.4) change no signature or default.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(p2p): document store.purge, the staticify manifest option and the new get options in the corestore reference

Audit of corestore 7.13.0 to 7.16.1. The upstream README did not change, so
these come from the source and tests.

- store.purge(keys, [options]): new in 7.15.0, in source only. Accepts keys or
  objects, skips unknown cores and cores with open sessions unless `force`,
  and returns the discovery keys it purged.
- store.staticify(core, opts = {}): `opts.manifest` overrides manifest fields
  (7.16.0), and `key` and `name` are ignored.
- store.get(): `userData` is forwarded to the session (7.14.0) and `weak` is
  honoured (7.15.0).
- handle.updates(): the heading said `handle.update`, but only `updates`
  exists, as the example on the same page already used. Added its source link
  and return value.

Left out on purpose: the 7.16.1 fix that sets `key` and `id` on a core first
opened by discovery key only. It changes no signature or default.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
… with upstream (#433)

- make-pear-app: use the v1 input names, drop the outputs, input validation and
  Node setup it no longer has, document the Mac App Store inputs, and list every
  input in the reference
- document the template's `make:mas` Mac App Store build and why the updater
  stays off for it
- sync the pear-chat example and the ship page with the template's MSIX assets
  (`msix-assets/`, `packageAssets`)

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
…roup (#435)

The docs are open, so permit model training instead of half-blocking it:
robots.txt disallowed GPTBot and Google-Extended while ClaudeBot, CCBot,
Applebot-Extended, meta-externalagent and Bytespider fell under "*" and were
allowed, which contradicted ai-train=no. Drop the two Disallow groups and
publish ai-train=yes.

Under RFC 9309 a crawler obeys only its most specific group, so Googlebot,
PerplexityBot and OAI-SearchBot never saw the Content-Signal line that sat in
the "*" group. inject-content-signals now adds it to every User-Agent group,
and check:seo fails if any group lacks it.

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
…es in line (#429)

* docs(templates): refresh the hello-pear-* snapshots and bring the pages in line

Re-pin hello-pear-bare, hello-pear-electron, hello-pear-react-native and
hello-pear-daemon to upstream main (b28bf7a, 016be67, 972e44a, 4aac96e). The
vendored code files and every imported #L range are unchanged: upstream's
changes to these four are README, build and workflow files, plus the
daemon's package rename, which the snapshot already carried.

Provenance records:
- hello-pear-daemon: the package rename is no longer a deviation, because
  upstream adopted it. README.md is re-copied verbatim.
- hello-pear-electron: upstream now inlines hello-pear-worker into
  workers/main.js with a two-line source header. The canonical copy keeps
  dropping that header, so it stays byte-identical to the other copies.
- Fix the stale content/ paths the electron and react-native records pointed
  at, and list the other pages that import from them.

Pages that described the old state:
- The shared worker callout and the Electron integration guide said the
  Electron template ships workers/main.js as require('hello-pear-worker').
- The Electron template page now mentions inline-worker, the MSIX logos in
  build/msix-assets/, and shouldUpdate() in electron/main.js.
- The daemon page said the template ships hello-pear-bare as its name.
- hello-pear-react-native now depends on pear-runtime-react-native 3.0.1,
  which generates an Android reload module and uses the OTA v4 marker, so a
  reload after applyUpdate() boots the staged bundle on Android. The boot
  control reference, the mobile integration and deployment guides and the
  mobile architecture page said Android needs a full restart.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(templates): say where the electron template keeps its Flatpak files

The map table listed "Flatpak/Snap metadata" under build/, but the template's
build/ holds only the icons, AppxManifest.xml, the entitlement plists and the
MSIX logos. The Flatpak metainfo and manifest live in a root flatpak/ directory,
and nothing in the template is Snap-specific. Correct the build/ row and add a
flatpak/ row.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(bare): document Bare 1.36.0 and WebAssembly addons in the references

Bare 1.36.0 loads an addon's prebuilds/wasi-wasm32/<name>.wasm build,
sandboxed through WASI, when an import asks for it with the `host`
attribute or when the package has no native build. The support comes from
bare-module 7.5.0 in the v1.36.0 lockfile, not from Bare's own source.

New module references:
- bare-wasi 0.1.2, bare-directory 0.1.0, and bare-wasm 0.1.0 are generated
  from their typings. The curated prose lives in the refgen layouts, and a
  second --write leaves the pages byte-identical.
- bare-wasm-abi 0.1.1 is hand-written because it ships no typings.
- The catalog gets a WebAssembly section, and Node's `wasi` now maps to
  bare-wasi.

Refreshed references:
- bare-module 7.5.0: the `host` and `wasi` attributes, the `wasi` loader
  option, and a WebAssembly addons section.
- bare-module-traverse 2.7.2.
- bare-pack 3.0.2, including the breaking `resolveModule` argument.
- bare-sqlite 0.1.5, which adds its WebAssembly build.
- native-addon-prebuilds gets a WebAssembly prebuilds section.

Runtime page and release overview, for the rest of 1.36.0:
- `RangeError` for a `linger` or `deadline` above 0x7fffffff.
- The deprecated callback forms of `Bare.Thread`.
- The fallback to `.wasm` builds after `Addon.seal()`.
- A refreshed doc-state window, 1.28.2 to 1.36.0.
- Release-overview entries for v1.36.0 and the module updates.

Every behaviour claim was run on bare-runtime 1.36.0 on macOS arm64:
- Which `.wasm` builds load: bare-svg 1.1.1 and bare-heif 1.2.1 import
  js_add_teardown_callback, which bare-wasm-abi 0.1.1 lacks.
- The error codes, and that they surface while the importing module links.
- The post-seal fallback.
- The rights each bare-directory operation needs.
- That Bare has no `crypto` global, so the provider example in the
  bare-module README fails as written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): fix WebAssembly reference errors found in review

- bare-directory: rename() needs `remove` on the target directory whenever
  `replace` is true, even if nothing is replaced (binding.c:1056, run on
  1.36.0). Add an Options section for the unexported OpenOptions,
  OpenFileOptions and RenameOptions, and say which classes use the thread pool.
- bare-wasi: drop the "Mirrors the Node.js wasi module" line, which the
  page's own comparison contradicts. Document the WASIOptions defaults, the
  HostDirectory class comment, and the rename rights.
- bare-sqlite: document the rights the WebAssembly build needs (create and
  remove for the lock directory, write and truncate for writes), the stale
  lock that makes later opens fail with BUSY, the SQLiteError codes, and the
  real extension error message.
- bare-wasm: say each export is the WebAssembly global's member.
- bare-wasm-abi: list all ten libjs functions 0.1.1 neither implements nor
  excludes, and the UNEXPECTED_EXPORT error for a module that exports _start.
- bare-module, runtime, release overview: after a seal, a package without a
  .wasm build now throws ADDON_NOT_FOUND where 1.35 threw CANNOT_LOAD; import
  attributes must be string literals; errors from a computed require() can be
  caught; a literal import() also resolves before the seal.
- bare-pack: link the README's example folders on GitHub.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): correct the post-seal and dynamic import() WebAssembly notes

A native addon reached from any module linked before Bare.Addon.seal(),
not only from the sealing module, throws CANNOT_LOAD. A dynamic import()
with a wasi attribute throws ADDON_WASI_INCOMPATIBLE in bare-module 7.5.0.
Both were run on Bare 1.36.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): add a WebAssembly addon how-to and explanation

New pages:
- How-to "Run an addon sandboxed in WebAssembly". It loads bare-sqlite's
  WebAssembly build with the `host` and `wasi` attributes, grants it one
  directory, checks that an absolute host path is refused, narrows the
  rights, keeps the files in memory, bundles with bare-pack, and lists the
  common errors.
- Explanation "WebAssembly addons". It covers the two builds of an addon,
  how Bare picks one, what WASI grants, what it does not stop, and what an
  addon cannot do as WebAssembly.

The how-to's runnable steps live in
examples/how-to/run-an-addon-sandboxed-in-webassembly/ and pass
check:examples. The project installs `bare` 1.36.0 or later as a
development dependency, so the steps don't depend on the global Bare.

Measured on bare-runtime 1.36.0:
- SQLite's WebAssembly build locks a database with a `.lock` directory, so
  even read-only access needs the `create` and `remove` rights.
- bare-pack bundles the `.wasm` build, but native addons such as
  bare-directory must be offloaded, and `__dirname` points inside the
  bundle.

An independent review against upstream source corrected the sandbox claims:
- WASI limits system access, but the ABI hands the addon `globalThis`, so
  it reaches whatever JavaScript in its realm can.
- The mitigation steps from the threat model are cumulative, not
  alternatives.
- The post-seal fallback applies only to addons resolved after the seal.

No iOS or Android claim is made: Bare 1.36.0 pins V8 prebuilds from before
WebAssembly was enabled for lite-mode platforms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): fix the WebAssembly how-to and explanation after a test run

Following the how-to from an empty folder on Bare 1.36.0 found:

- The read-and-write rights lacked `truncate`. Without it, rolling back a
  transaction that grew the file, or VACUUM, fails with IOERR and leaves a
  hot journal behind.
- Bundling failed as written: the command block ran before the fix, the fix
  dropped the HostDirectory wrapper (INVALID_PREOPEN), and bare-os and
  bare-path were never installed. The section now gives the full provider
  and the install step, and says how --host wasi-wasm32 bundles a fallback.
- A process without `remove`, or one that exits holding the lock, leaves
  books.db.lock behind and every later open fails with BUSY until it is
  deleted. The page now says how to recover.
- `host` and `wasi` must be string literals; computed values fail with
  ADDON_HOST_INCOMPATIBLE or ADDON_WASI_INCOMPATIBLE.

Also:
- The ledes of the how-to, the explanation and native-addons said the
  sandbox limits all system access. WASI limits files and system calls only;
  the addon still reaches the JavaScript realm.
- The how-to gets a tip callout and a Before you begin section like its
  siblings, output blocks for every run, explains HostDirectory, and adds
  INVALID_PREOPEN and IOERR/BUSY rows to the error table.
- The explanation's seal rule covers literal import() too, and the test note
  moves to a callout.
- bare-module, bare-wasi and bare-sqlite link back to the new pages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): correct the WebAssembly rights, stale-lock and seal notes

The read-only rights can create directories but not files. With a stale
lock, the open succeeds and the first statement fails with BUSY. The post-seal
CANNOT_LOAD rule covers every module linked before the seal. A dynamic
import() with a wasi attribute throws ADDON_WASI_INCOMPATIBLE. All were
run on Bare 1.36.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): fix WebAssembly reference claims from the adversarial review

All run on Bare 1.36.0 unless noted.

- bare-sqlite: writing without `write` fails with CANTOPEN, not IOERR.
  Without `truncate`, a ROLLBACK of a grown transaction can report success
  and leave a hot journal. Only a killed process leaves the lock (Bare.exit,
  a throw and a normal exit release it), and with a stale lock the open
  succeeds and the first statement fails with BUSY. Bump the pin to 0.1.6
  (SQLite 3.54.1 only; same behaviour on re-run) and add it to the release
  overview.
- bare-wasi: without `write`, HostDirectory opens files for appending when
  `append` is granted; creating a file needs `write`; `clock: null` still
  leaks the time through timestamps set to now (index.js:417). The provider
  must install bare-wasi and bare-directory, because Bare's bundled bare-wasi
  can't be imported. Say that WASI limits only system calls.
- bare-directory: close() and restrict() are synchronous; the Right type
  comment understates when rename() needs `remove`.
- bare-module, runtime, release overview: bundles never fall back to .wasm
  after a seal (the preresolved path skips the loadable filter); the
  provider's native addons must load before the seal; computed attributes
  next to a literal specifier throw from the call and can be caught, and
  work with a computed specifier; a computed-specifier dynamic import()
  ignores the provider; ADDON_NOT_FOUND from a static import declaration
  can't be caught; the "linked in several contexts" message; a provider
  exporting { default } works, one returning nothing gives defaults; Bare
  1.36.0 also bumped bare-pipe to 4.4.0.
- bare-pack: a symlinked bundle works in place and fails with
  MODULE_NOT_FOUND only when moved; --out is skipped only when its
  directory is --base; the wasi-wasm32 host rule applies without a host
  attribute.
- native-addon-prebuilds: cmake-toolchains 2.1.1, which fixed the
  WebAssembly flags (#40).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): fix WebAssembly how-to and explanation claims from the adversarial review

All run on Bare 1.36.0.

- explanation: "without the write right it can't write" was false twice:
  without `write`, bare-wasi opens files for appending when `append` is
  granted, and a hostile .wasm goes around WASI entirely. A test addon got
  the provider's already-loaded bare-directory back after the seal and read
  a file outside its preopen; say so under "What the sandbox doesn't stop".
  Qualify "can't open a file" with "through WASI". Builtins resolve first,
  and a broken native build throws CANNOT_LOAD with no fallback. Bundles
  never fall back. List all five of the threat model's must-dos.
- native-addons: fall back only when the package has no native build, or
  on a sealed process when it isn't loaded, not "when no native build can
  load".
- how-to: write without `write` gives CANTOPEN; without `truncate`, a
  rollback can report success and leave a hot journal; a killed process
  leaves the lock; computed attributes next to a literal specifier throw
  from the call and can be caught; ADDON_NOT_FOUND from a static import
  declaration can't be caught. The error table gains the other two
  ADDON_HOST_INCOMPATIBLE messages (including a package the provider loads
  natively), one provider with several preopens instead of `url`, the
  `{ default }` provider form, a provider that returns nothing, and the
  dynamic import() that drops `wasi`. bare-sqlite's .wasm never asks for
  random bytes, and clock: null doesn't cover timestamps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…#436)

- bare-wasm: regenerate the reference against 0.1.1, which loads without
  the WebAssembly global and throws WEBASSEMBLY_UNAVAILABLE on use. Say that
  Bare 1.36.0 still bundles 0.1.0.
- WebAssembly addons explanation: the bare-wasm 0.1.1 README names iOS
  without a JIT as a place the WebAssembly global is unavailable.
- Native-addon CI prebuilds: cmake-bare 1.10.1 is the minimum. 1.10.0 links
  with --allow-undefined-file pointing at a bare/wasm.syms that no
  bare-headers release ships.
- Release overview: add bare-wasm 0.1.1 (2026-10-27) and bare-make 2.1.1
  (2026-10-28).
- bare-make: document the AddressSanitizer runtime preload added in 2.1.1.
- Bluetooth best practices: the setup guide no longer shows native host
  code (#430), and only bare-bluetooth and ble-swarm carry an experimental
  banner.
- Embed Bare in React Native: react-native-bare-kit 0.16.0 stopped linking
  native addons, so point to the bare-link instructions.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
holepunchto/hello-pear-bare-worker is being archived. It was a June 2026
snapshot of hello-pear-bare, from before the worker moved into the
hello-pear-worker package and was inlined, so hello-pear-bare supersedes it.

Remove its card from "Start from a template" and reword the remaining
section for the one repository left, hello-pear-worker. No other page
mentioned the repository.

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
Add a `brew install pear` tab next to curl, irm, npx, and docker on the
Pear CLI reference and both getting-started pages, and name Homebrew in
the root page's install pointer.

The CLI reference explains what the formula does: Homebrew core's `pear`
formula installs the same npm launcher as `npm i -g pear`, so it pulls in
Node.js, the first `pear` run downloads the platform binary, and that
binary then updates itself over the air. `brew upgrade pear` therefore
refreshes only the launcher.

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
…or (#443)

* fix(refgen): regenerate Bare module pages at their pins, without base-class leaks

- fetch.ts: the lucas-tortora chore/ts-doc fork branches are now a fallback,
  used only for a .d.ts file the tarball ships without any TSDoc. Upstream
  merged and released that TSDoc, and the branches are older than the
  releases (bare-subprocess's still says kill(): void). 23 pins predate the
  releases, so the fallback stays for them.
- index.ts: --only name@version and --pinned (the version the live page's
  upstreamVersion names). Without them the generator packs npm latest and
  bumps pins.
- extract.ts: members inherited from another package's EventEmitter,
  EventTarget or stream base class are left out of member lists and
  interface shapes (bare-events 2.9 and the bare-stream typing rework put
  _destroy, addListener, emit and the rest on many pages). Shapes name the
  base instead, and a class that keeps only its own properties stays
  expanded (model field inheritsBase).
- render.ts: colliding headings take the least scope that makes them unique
  (Body.json, Event.bubbles; request.Request.json only beside a main-entry
  Request.json). TSDoc paragraphs are reflowed, so upstream rewrapping no
  longer changes pages. Same-page links survive when the page has the
  heading. New layout hooks: description, patch in: 'seeAlso', and member
  refs by heading text for members a subpath repeats.
- layout.ts: <name>.params.json. check.ts accepts heading refs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(refgen): move the hand edits of 25 Bare pages into their layouts

Every page edit that the .d.ts and README don't carry is now a layout
entry, so gen:bare-refs --write keeps it: bare-assert (intro, the Node.js
differences, matching thrown errors), bare-module (Loading bundles, the
CommonJS, ECMAScript and WebAssembly sections), bare-pack (3.0 upgrade
callout, Aliases, Offloading, Symlinks, WebAssembly, bare-pack/fs),
bare-module-traverse, bare-make (2.1 env), bare-dns (Android), bare-url
(UNC paths, threat model), the bare-timers and bare-structured-clone threat
models, bare-subprocess (6.2.2 kill), bare-sidecar (stdio), bare-stow,
bare-fs (4.8.3 cp and symlink), bare-pipe, bare-prom-client,
bare-mdns-discovery, bare-addon-resolve, bare-module-resolve, bare-stream,
bare-sqlite-vector, bare-file-logger and bare-console. bare-dgram had no
layout; its descriptions come from the Oct 6 fix branch, which encoded the
same page.

The Bluetooth memberPatches match the reflowed TSDoc now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): regenerate the 75 module pages at their current pins

Output of `npm run gen:bare-refs -- --only <every module> --pinned --write`.
No upstreamVersion moves. 18 pages change only in wrapping. Beyond that:

- Members inherited from bare-events and bare-stream base classes leave
  about 15 pages (bare-tcp, bare-net, bare-pipe, bare-http1, bare-https,
  bare-ws, bare-tls, bare-tty, bare-fs, bare-dgram, bare-ipc,
  bare-broadcast-channel, bare-subprocess, bare-sidecar, bare-dns) and the
  bare-process shape.
- Heading qualifiers: bare-fetch's request/response/headers subpaths and
  the bare-tcp/net/tty/dgram constants subpath keep a subpath prefix, as
  bare-fs, bare-os and bare-tls already did, so anchors stay unique;
  bare-wasi drops one it didn't need; bare-format shows format.format.
- Where the page had fork or stale text, the pinned release's TSDoc wins:
  bare-buffer, bare-abort-controller, bare-atomics (Semaphore throws the
  source never had), bare-type-stripper, bare-fs watch, bare-https,
  bare-fetch.
- Generator formatting replaces hand formatting that added no content on
  bare-pack's fs callbacks and bare-assert's AssertionError heading.

versions.json now matches the pages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* docs(bare): document Bare Kit 3 and react-native-bare-kit 0.17

bare-kit 3.0.0 reworked Bare Kit as a standalone C library
(include/bare-kit.h), moved the native bindings to bare-kit-swift and
bare-kit-kotlin, replaced the IPC pipes with an in-process queue, and
removed push, the BareKit global, and the assets option.
react-native-bare-kit 0.17.0 moved onto it and stopped including Bare
Kit; 0.17.1 added the exit event and wait().

- Rewrite the Bare Kit reference for react-native-bare-kit 0.17.1,
  bare-kit 3.0.1, bare-kit-swift 2.2.0 and bare-kit-kotlin 0.2.2:
  Swift and Kotlin sections replace the removed Objective-C and Java
  ones, the C API section follows include/bare-kit.h, and the linking,
  bundle loading and bundled-Bare-version sections cover bare-stow link
  and Bare 1.36.2. Pre-0.17 instructions stay behind until="0.17.0"
  gates.
- Regenerate the doc-states: 0.17.0 and 0.17.1 are new, 0.9.0 and
  0.9.1 drop out of the window, so the 0.9.1 and 0.9.2 markers go.
  The bare-cli and bare-runtime states only gain 1.36.1 and 1.36.2 in
  their release lists.
- Note on the embedder-context page that bare-kit 3 also publishes
  bare.android.context.v1.
- Rename "Linking native addons" to "Linking addons and assets" and
  update the two inbound links.
- Add a release-overview entry for Bare Kit 3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: rebaseline the bare-kit upstream commit

Point the bare-kit key at react-native-bare-kit 1081cd8 ("Surface
`exit` event from Bare"), the latest change to index.d.ts, now that
the Bare Kit page documents 0.17.1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
The pear-ci action gained a `length` output (holepunchto/actions#126),
read from the file that pear-ci 0.1.2's new `--output` flag writes
(holepunchto/pear-ci#7). Add both to the action reference and the
action table.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* docs(bare): document upstream drift in 24 module pins and Bare 1.36.2

Bump every drifted Bare reference pin to the latest npm release and
document what changed:

- Minor: bare-pipe 4.4.0 (remoteCredentials, ownerOnly, Local access
  control), bare-rpc 1.5.0 (CommandRouter typings, maxFrameSize,
  maxBufferedBytes, untrusted-peer errors), bare-tls 3.2.0
  (TLSNetSocket, onconnect after handshake, non-canonical IPv4 check),
  bare-stow 0.3.2 (package harness rewrite; page regenerated, stale
  layout replaced).
- Patch with behaviour changes: bare-addon-resolve 1.11.1,
  bare-bluetooth 0.6.5, bare-dns 2.3.1, bare-fetch 3.4.1,
  bare-module-traverse 2.7.4, bare-os 3.9.4, bare-sidecar 0.5.15,
  bare-tty 5.2.2, bare-url 2.5.6.
- Pin only: bare-abort, bare-ansi-escapes, bare-atomics, bare-bundle-id,
  bare-collabora, bare-format, bare-http1, bare-mdns-discovery,
  bare-realm, bare-string-decoder, bare-vm, and the embedder context
  page (Bare 1.36.2 changed only CMake targets).

New prose on generated pages is also encoded as layout patches so a
regeneration keeps it. Models for the bumped modules come from the
release tarballs: the lucas-tortora chore/ts-doc fork branches are now
older than the merged upstream TSDoc (bare-subprocess still says
kill(): void there). The research dossier now carries the current
README sections of bare-pipe, bare-rpc and bare-stow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(p2p): re-audit hypercore, hyperdht, autobee, blind-peer and blind-peering

- hypercore 11.40.0: clear() subtree fix (11.39.6), closed sessions
  destroy their extensions.
- hyperdht 6.35.1: close()/suspend() no longer wait for a first
  announce; force also skips unannounce retries.
- autobee 2.13.2: background remap (remapped, remapping, remap and
  warning events), moveTo() replacing a running fast-forward; fixes
  pre-existing errors (getMostRecentHead never existed, ackWriter is a
  no-op, conservative defaults to false since 2.12.0).
- blind-peer 3.18.1: metricsOpts client labels, upgradeLength proofs,
  FCM rate-limit retry.
- blind-peering 2.13.1: request/response registrations and
  notifications, sendNotification() peer order and AggregateError,
  osPlatform handshake, upgradeLength.

All [src] links moved to the new tags and re-checked line by line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: rebaseline reviewed upstream-commit entries

72 of 75 moved entries are reviewed: formatting or TSDoc only, or API
changes that the pinned release already carries and the pages document.
Held back so the check keeps flagging them: bare-kit (Bare Kit 3 /
react-native-bare-kit 0.17, not yet documented), compact-encoding
(unreleased API on main), and pear-cli (Pear 3.7.0 work).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
… (#444)

* docs(pear-ci): keep a seeder online, commit the first snapshot, pin @v1

The "Publish with GitHub Actions" how-to couldn't be followed as written:
- The Fetch step fails with `gh: Not Found (HTTP 404)` until `main` has a
  `ci/snapshot.json`. Add a step that commits `[]`, and warn never to
  reset it after the first release.
- Every run waits, with no time limit, for a peer that holds the drive,
  before and after staging. Drop the "nothing to keep online" claim, add
  a "Keep a seeder online" step, and start the workflow as a dry run so
  the key is known before the first real run.
- Add `timeout-minutes` to the job, pin `pear-ci@v1` instead of `@main`,
  and warn that a run stopped partway through its upload leaves the
  seeder with a gap that pear-ci 0.1.2 can't recover from.

The pear-ci action reference gets the same fixes: `@v1` in Usage, the
`[]` first snapshot and reset warning in Snapshot commits, and a new
"Peers and timeouts" section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear-ci): tighten snapshot, stop, and seeder guidance

Review follow-ups on the pear-ci how-to and action reference:

- pear-ci reads any snapshot it can't parse as [] (index.js parseJSON),
  so the reset warning now covers empty and invalid files too, says to
  publish each drive from one repository, and gives the way forward
  after a reset: a new namespace, at the cost of a new link.
- The Commit step commits on top of the commit the run checked out, so
  a push to main during a run, or branch protection, sends the snapshot
  to a pear-ci/snapshot-<run-id> PR. Until it merges, every run fails
  before staging with the length error. Document that, and the Actions
  setting the PR fallback needs with the default token.
- The stop guidance contradicted itself: "never stop after starting
  stage for key" next to "let the timeout end a run waiting for a
  peer". Stopping is unsafe only while a peer is connected, and the job
  log can't show that (pear-ci never emits the connection event its CLI
  listens for), so point at pear seed's peer and length rows, and tell
  readers to start the seeder while a run waits instead of re-running.
- The pear seed reference said seeding is sparse. Since Pear 2 the seed
  op downloads both cores in full and live, which pear-ci's
  remoteContiguousLength wait relies on.
- Note that the action installs the latest pear-ci from npm whatever
  action version is pinned, describe the pre-stage wait as a length
  check rather than a sync, show the sample log line with its real
  double space, and move the two shared warnings into snippets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* docs(pear): document the Pear 3.7.0 CLI changes (draft, pre-tag)

Covers upstream main at 056afaf, which is 3.7.0-rc.0 plus nine commits.
No v3.7.0 tag or GitHub release exists yet, so 3.7 is registered as a
prerelease doc-state and the Release Overview entry is headed
"Unreleased". Keep this PR in draft until the tag lands.

Reference (cli.mdx), every change behind a 3.7.0 gate:
- pear info: labeled rows and a Targets: section replace the keys/info
  tables. --json gains targets and blobs.key, and retrieving reports
  link instead of z32.
- pear seed: network status words (joining, unstable, unreachable) and
  the dht stats object; exit code 1 when the sidecar connection closes;
  Seeding: shows the link's origin.
- pear sidecar inspect: removed.
- pear dump: link must be a pear:// link or verlink. This is a
  clean-up, not a break: on 3.6.0 the link check already rejected local
  paths and file: URLs with the same error, so the help text and dead
  code are what changed.
- pear --menu: command groups, linked to the how-to.

How-tos: new screenshots and a rewritten "Find a command" for the
grouped menu; a post-stage Targets check in preflight-a-release and
publish-with-github-actions; a "cannot find a platform" entry in
troubleshoot-desktop-releases; Writable:/Drive Key: wording fixes.

Samples were captured from the rc.0-plus-nine-commits binary on a local
testnet with v3.6.0 run beside it; the findings are appended to
docs/plans/PEAR-3.7.0-RELEASE-PLAN.md. The seed network status words
were not reproduced live and come from the source. Recapture on the tag.
Open upstream PRs that would change this: #1260 (content to blobs
rename) and #1259 (pear make).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(pear): note that the first pear info on a new machine prints [ Empty ]

On a platform directory that has never held the link, the first
`pear info <link>` printed `[ Empty ]` after about 14 seconds even with a
seeder up, and the second run read the link in 0.3 seconds. This
reproduced on three fresh directories. The docs said `[ Empty ]` meant no
peer was reachable, and the GitHub Actions verify job ran `pear info`
once, so it would have failed on a fresh runner. The job now retries up
to three times, ten seconds apart; the loop was run against the real
binary on a fresh directory.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(pear): fix the Pear 3.7.0 review findings

- pear info: restore the pre-3.7.0 output description and JSON sample
  for 3.0-3.5 readers (gate until 3.7.0 only) and label it as pre-3.7.0.
  Document the multisig label change, say the Targets sizes come from
  the metadata plus block maps (no file contents), drop the
  no-argument platform-link claim, and move the first-run [ Empty ]
  note out of the 3.7.0-only gate.
- pear seed: the Seeding origin also applies to the --no-tty line, and
  the status word keeps the --- prefix.
- Release Overview: three breaking changes plus two seed changes that
  affect wrappers, multisig labels, the pear cores fix scope, and a
  TODO to flip stable.
- GitHub Actions verify job: install Pear in its own step (the first
  npx pear only installs), fail with an explicit message when no info
  object arrives, and note the production-channel dependency. The
  intro no longer says nothing needs to stay online.
- Troubleshoot: Not found also covers a folder missing the expected
  file.
- Menu how-to: drop "in that order", list the Platform commands
  exactly, and document the filter enter/esc and arrow keys.
- Preflight build gate: strip CR so it works with jq.exe under Git Bash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): sync with upstream pear as of 2026-11-04

- pear dump: `<dir>` can be left out only with `--list`; without it the
  argument is still required even though the help shows `[dir]`.
- pear identity: the key goes to stdout and the hint to stderr.
- Release Overview TODO: add holepunchto/pear#1261 to the open upstream
  PRs to reconcile, and record that main only gained a README change
  (#1262) after 056afaf.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): say that npx pear-install installs the same Pear as npx pear

Verified on 2026-11-05 in clean HOME directories: both commands exit 0,
and both install the same 88877040-byte pear binary (3.6.0 from the
production channel) into ~/.local/bin. The CLI reference explains how
they differ, and the two getting-started install tabs mention the
second form.

Also note in the Release Overview TODO that v3.7.0-rc.0 contains only
the version bump and the 3.6.0 CHANGELOG entry, and that the production
channel still installs 3.6.0.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(pear): sync the Pear 3.7.0 docs with the v3.7.0 tag

Upstream tagged v3.7.0 on 2026-11-11 (2a67b71). The tag includes two PRs
that this branch had marked as pending:

- #1259: add a pear make reference section, a Release Overview bullet,
  make in the Ship group of the menu, and a line in the pear-cli agent
  skill. It is written from cmd/make.js and the sidecar make op, and was
  not run live.
- #1260: Content Key is Blobs Key. pear info drops the Content Key row,
  pear seed shows Blobs Key (gated to 3.7.0, with the 3.5 and 3.6
  samples kept), pear gc cores prints "Cleared blobs ~", and the
  --core-only help and the gc and blind-peering prose say blobs core.

#1261 is not in the tag, so the pear dump [dir] note stands. The
upstream-releases pin for holepunchto/pear is v3.7.0 and the pear-cli
commit pin is be04ef7, the last cmd/index.js commit in the tag.

The entry stays "Unreleased" and 3.7 stays a prerelease doc-state: the
stage channel serves 3.7.0 but the production channel still serves 3.6.0.
The two menu screenshots still show the Ship group without make and need
recapturing from a 3.7.0 binary.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(pear): fix the findings of the Pear 3.7.0 adversarial review

- pear make: --install does not reinstall over an existing pear-make
  (pear-install refuses to overwrite it), the no-terminal case is
  "stdin is not a terminal", --version still runs the install check, bin
  has to be a single path, --host and --name are passed through and
  defaulted inside pear-make, and --json also ends with a final object on
  success, ends with an error object and no final on failure, and writes
  its objects without a trailing newline. Drop the host list, which came
  from pear-make's own build section, not its --host flag.
- pear install: document PEAR_INSTALL_NO_PATH, added in pear-install
  v1.5.0, which Pear 3.7.0 ships.
- Content to Blobs: fix the tutorial pear seed sample in
  build-a-peer-to-peer-chat/ship.mdx and the availability explainer, say
  that 3.6.0 printed the key as the content row of the pear info keys
  table, call out the second space in "Cleared core  ~", and gate the
  pear gc sample and the --core-only help line by version.
- Leave holepunchto/pear at v3.6.0 in upstream-releases-state.json.
  check-upstream-releases.ts prefers GitHub releases, and pear has
  releases but no v3.7.0 one, so a v3.7.0 pin would make it re-draft every
  earlier pear release. Bump it once the release exists.
- Menu wording says native app installers, and the pear-cli skill
  description lists pear make.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(pear): recapture the menu screenshot with make in the Ship group

The Ship group in pear --menu now lists make after build. The screen text
for the first fifteen rows comes from a 3.7.0 run on the maintainer's
machine. The remaining rows (rest of Release, Network, Platform) are
unchanged from the previous capture and the v3.7.0 source, so they are
carried over. Rendered with Menlo to match the earlier screenshots. The
Ship group help screenshot still needs a 3.7.0 capture.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(pear): fix the findings of the second Pear 3.7.0 review

- cli and pear-cli skill: from 3.7.0, pear info colors its output and
  redraws its loading line only when stdin is a terminal, so CI gets
  plain text.
- cli: platform pear info (no link) also lists the platform drive's
  Targets from 3.7.0.
- pear dump: 3.6.0 checked a non-empty <dir> before the link, so that
  case failed with "Dir is not empty" rather than the link error. Say
  so in the reference, the Release Overview and the skill.
- pear-cli skill description: mark pear make as 3.7.0 and later.
- Interactive menu: left and right collapse or expand only on a group
  header; left on a command jumps to its header.
- Drop pear-menu-group-help.png, a new capture that still shows the
  Ship help panel without make, until a 3.7.0 capture exists.
- pear-ci action: 3.7.0's text output labels the length Drive Length.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): end the 3.7.0 pear info sample with its Success line

pear info prints ✔ Success after the last row: its final tagger returns
false, so the outputter prints Success (cmd/info.js, lib/terminal.js at
v3.7.0).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): mark Pear 3.7 stable now that production serves it

The production channel serves 3.7.0 (pear info --json on the production
link reports version 3.7.0, length 92), and holepunchto/pear published
the v3.7.0 GitHub release on 2026-11-12.

- docs-versions: 3.7 is stable, 3.6 is no longer.
- Release Overview: date the 3.7.0 entry 2026-11-12, replace the
  before-merge TODO with a provenance note, and drop the ?v=3.7 pins,
  as the 3.6.0 entry does for its links.
- upstream-releases-state: pin holepunchto/pear to v3.7.0, now that the
  release exists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): recapture the 3.7.0 samples and menu screenshots on the tag

Captured from a v3.7.0 build (2a67b71) running with its own platform
directory on a local HyperDHT testnet, with a staged pear-chat@1.0.1
drive carrying darwin-arm64, linux-x64, and win32-x64 targets:

- pear info (human and --json) from a second machine that does not own
  the link: the labeled rows, Targets, and the ✔ Success line match the
  documented format. The samples now hold the captured values.
- pear seed live view (pty): Blobs Key: row confirmed; the sample now
  holds the captured frame. --no-tty prints "... blobs key".
- pear gc cores on a writable link prints "Cleared core  ~" and
  "Cleared blobs ~" after the CLEAR prompt, as documented.
- pear seed exits 1 on pear sidecar shutdown, with "x-x sidecar
  disconnected" (--no-tty) and the ERR_CONNECTION error object (--json).
- Both menu screenshots re-rendered from the build's screen buffer, and
  the Ship help panel, which now lists make, is back on the
  interactive-menu page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): let Vale read the 3.7.0 seed sample as code

Without a blank line after the VersionGate tag, the fence was read as
prose, and Vale took 974nd in the captured link for an ordinal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
…449)

* docs(pear): document the Pear 3.7.0 CLI changes (draft, pre-tag)

Covers upstream main at 056afaf, which is 3.7.0-rc.0 plus nine commits.
No v3.7.0 tag or GitHub release exists yet, so 3.7 is registered as a
prerelease doc-state and the Release Overview entry is headed
"Unreleased". Keep this PR in draft until the tag lands.

Reference (cli.mdx), every change behind a 3.7.0 gate:
- pear info: labeled rows and a Targets: section replace the keys/info
  tables. --json gains targets and blobs.key, and retrieving reports
  link instead of z32.
- pear seed: network status words (joining, unstable, unreachable) and
  the dht stats object; exit code 1 when the sidecar connection closes;
  Seeding: shows the link's origin.
- pear sidecar inspect: removed.
- pear dump: link must be a pear:// link or verlink. This is a
  clean-up, not a break: on 3.6.0 the link check already rejected local
  paths and file: URLs with the same error, so the help text and dead
  code are what changed.
- pear --menu: command groups, linked to the how-to.

How-tos: new screenshots and a rewritten "Find a command" for the
grouped menu; a post-stage Targets check in preflight-a-release and
publish-with-github-actions; a "cannot find a platform" entry in
troubleshoot-desktop-releases; Writable:/Drive Key: wording fixes.

Samples were captured from the rc.0-plus-nine-commits binary on a local
testnet with v3.6.0 run beside it; the findings are appended to
docs/plans/PEAR-3.7.0-RELEASE-PLAN.md. The seed network status words
were not reproduced live and come from the source. Recapture on the tag.
Open upstream PRs that would change this: #1260 (content to blobs
rename) and #1259 (pear make).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(pear): note that the first pear info on a new machine prints [ Empty ]

On a platform directory that has never held the link, the first
`pear info <link>` printed `[ Empty ]` after about 14 seconds even with a
seeder up, and the second run read the link in 0.3 seconds. This
reproduced on three fresh directories. The docs said `[ Empty ]` meant no
peer was reachable, and the GitHub Actions verify job ran `pear info`
once, so it would have failed on a fresh runner. The job now retries up
to three times, ten seconds apart; the loop was run against the real
binary on a fresh directory.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(pear): fix the Pear 3.7.0 review findings

- pear info: restore the pre-3.7.0 output description and JSON sample
  for 3.0-3.5 readers (gate until 3.7.0 only) and label it as pre-3.7.0.
  Document the multisig label change, say the Targets sizes come from
  the metadata plus block maps (no file contents), drop the
  no-argument platform-link claim, and move the first-run [ Empty ]
  note out of the 3.7.0-only gate.
- pear seed: the Seeding origin also applies to the --no-tty line, and
  the status word keeps the --- prefix.
- Release Overview: three breaking changes plus two seed changes that
  affect wrappers, multisig labels, the pear cores fix scope, and a
  TODO to flip stable.
- GitHub Actions verify job: install Pear in its own step (the first
  npx pear only installs), fail with an explicit message when no info
  object arrives, and note the production-channel dependency. The
  intro no longer says nothing needs to stay online.
- Troubleshoot: Not found also covers a folder missing the expected
  file.
- Menu how-to: drop "in that order", list the Platform commands
  exactly, and document the filter enter/esc and arrow keys.
- Preflight build gate: strip CR so it works with jq.exe under Git Bash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): sync with upstream pear as of 2026-11-04

- pear dump: `<dir>` can be left out only with `--list`; without it the
  argument is still required even though the help shows `[dir]`.
- pear identity: the key goes to stdout and the hint to stderr.
- Release Overview TODO: add holepunchto/pear#1261 to the open upstream
  PRs to reconcile, and record that main only gained a README change
  (#1262) after 056afaf.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): say that npx pear-install installs the same Pear as npx pear

Verified on 2026-11-05 in clean HOME directories: both commands exit 0,
and both install the same 88877040-byte pear binary (3.6.0 from the
production channel) into ~/.local/bin. The CLI reference explains how
they differ, and the two getting-started install tabs mention the
second form.

Also note in the Release Overview TODO that v3.7.0-rc.0 contains only
the version bump and the 3.6.0 CHANGELOG entry, and that the production
channel still installs 3.6.0.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(pear): sync the Pear 3.7.0 docs with the v3.7.0 tag

Upstream tagged v3.7.0 on 2026-11-11 (2a67b71). The tag includes two PRs
that this branch had marked as pending:

- #1259: add a pear make reference section, a Release Overview bullet,
  make in the Ship group of the menu, and a line in the pear-cli agent
  skill. It is written from cmd/make.js and the sidecar make op, and was
  not run live.
- #1260: Content Key is Blobs Key. pear info drops the Content Key row,
  pear seed shows Blobs Key (gated to 3.7.0, with the 3.5 and 3.6
  samples kept), pear gc cores prints "Cleared blobs ~", and the
  --core-only help and the gc and blind-peering prose say blobs core.

#1261 is not in the tag, so the pear dump [dir] note stands. The
upstream-releases pin for holepunchto/pear is v3.7.0 and the pear-cli
commit pin is be04ef7, the last cmd/index.js commit in the tag.

The entry stays "Unreleased" and 3.7 stays a prerelease doc-state: the
stage channel serves 3.7.0 but the production channel still serves 3.6.0.
The two menu screenshots still show the Ship group without make and need
recapturing from a 3.7.0 binary.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(pear): fix the findings of the Pear 3.7.0 adversarial review

- pear make: --install does not reinstall over an existing pear-make
  (pear-install refuses to overwrite it), the no-terminal case is
  "stdin is not a terminal", --version still runs the install check, bin
  has to be a single path, --host and --name are passed through and
  defaulted inside pear-make, and --json also ends with a final object on
  success, ends with an error object and no final on failure, and writes
  its objects without a trailing newline. Drop the host list, which came
  from pear-make's own build section, not its --host flag.
- pear install: document PEAR_INSTALL_NO_PATH, added in pear-install
  v1.5.0, which Pear 3.7.0 ships.
- Content to Blobs: fix the tutorial pear seed sample in
  build-a-peer-to-peer-chat/ship.mdx and the availability explainer, say
  that 3.6.0 printed the key as the content row of the pear info keys
  table, call out the second space in "Cleared core  ~", and gate the
  pear gc sample and the --core-only help line by version.
- Leave holepunchto/pear at v3.6.0 in upstream-releases-state.json.
  check-upstream-releases.ts prefers GitHub releases, and pear has
  releases but no v3.7.0 one, so a v3.7.0 pin would make it re-draft every
  earlier pear release. Bump it once the release exists.
- Menu wording says native app installers, and the pear-cli skill
  description lists pear make.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(pear): add a how-to for building CLI executables with pear make

Pear 3.7.0 adds pear make (holepunchto/pear#1259). The new guide covers:
pointing bin at the entry, the first-run pear-make install, a native
build, running the result, cross-host builds, CI use with --install and
--json, signing, and troubleshooting. A small paparam example under
examples/how-to/operate-an-app/build-a-cli-executable runs under
check:examples with npx bare. The pear make fences are skipped, because
CI has no 3.7.0 binary.

Every sample was captured live on the v3.7.0 tag with pear-make 1.1.0.
That run adds these facts to the reference section:

- Without --name the file is called "app". pear-make cannot read
  package.json from inside its own executable, so the productName/name
  default in the help never applies. --name is sanitized (Hello CLI
  writes hello-cli).
- The sidecar spawns pear-make with the PATH it started with. A pear-make
  installed after the sidecar started fails with "no such file or
  directory" until pear sidecar shutdown.
- An unknown --host prints "Unknown host '<host>'". android-arm64 and
  ios-arm64 also build, so the guide lists the desktop ids, not a closed
  set.
- --install over an existing copy fails with "Refusing to overwrite
  existing:". CI should install only when pear-make is missing.
- Output is ad-hoc signed on macOS and has no Authenticode signature on
  Windows.

The reference flags block now lists --install.

The guide is registered in the pear nav, the Build & package cards, the
how-to index, the release overview, and the pear-cli agent skill. It is
linked from the three CLI template pages, Bundle a Bare app, and
Distribute as a binary.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): recapture the menu screenshot with make in the Ship group

The Ship group in pear --menu now lists make after build. The screen text
for the first fifteen rows comes from a 3.7.0 run on the maintainer's
machine. The remaining rows (rest of Release, Network, Platform) are
unchanged from the previous capture and the v3.7.0 source, so they are
carried over. Rendered with Menlo to match the earlier screenshots. The
Ship group help screenshot still needs a 3.7.0 capture.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs: link the pear make guide from the pages about standalone builds

Every page that explains or mentions compiling a Bare or Pear CLI app
into a standalone executable now points readers to the new guide.

- Bare explanations: use-bare-standalone and the bare-runtime FAQ.
- Bare how-tos: migrate-a-nodejs-app-to-bare and the QVAC TUI guide's
  next steps.
- Bare CLI reference: a see-also entry.
- Pear how-tos:
  - the Make distributables step in deployment.mdx (for a terminal app);
  - the standalone-binary note in preflight-a-release;
  - the Ship group in the interactive-menu how-to.
- Explanations: install of standalone binaries in
  storage-and-distribution, and the Build & bundle layer in
  how-the-stack-fits-together.

The Operate an app card now says "standalone CLI executables", and the
build-a-pear-app agent skill names pear make for the terminal shape.

Also merges docs/pear-3.7.0 (03e1690, the recaptured menu screenshot).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): fix the findings of the second Pear 3.7.0 review

- cli and pear-cli skill: from 3.7.0, pear info colors its output and
  redraws its loading line only when stdin is a terminal, so CI gets
  plain text.
- cli: platform pear info (no link) also lists the platform drive's
  Targets from 3.7.0.
- pear dump: 3.6.0 checked a non-empty <dir> before the link, so that
  case failed with "Dir is not empty" rather than the link error. Say
  so in the reference, the Release Overview and the skill.
- pear-cli skill description: mark pear make as 3.7.0 and later.
- Interactive menu: left and right collapse or expand only on a group
  header; left on a command jumps to its header.
- Drop pear-menu-group-help.png, a new capture that still shows the
  Ship help panel without make, until a 3.7.0 capture exists.
- pear-ci action: 3.7.0's text output labels the length Drive Length.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): fix the findings of the pear make review

Build a CLI executable with pear make:
- Cross-built darwin executables are unsigned: bare-build only ad-hoc
  signs when it runs on macOS, and Apple silicon refuses unsigned arm64
  code. Add a warning to step 5 and say so in the signing callout.
- CI: add a PowerShell variant of the install-if-missing recipe, give
  the Windows install directory (%LOCALAPPDATA%\Programs\pear-make),
  which pear install adds only to the registry PATH, and show how to
  append it to GITHUB_PATH in both shells.
- --install over an existing copy prints "Already installed:" on
  Windows, and pear make exits 1. --install ignores --json, so its
  progress lands in the JSON stream as plain text.
- The jq example sets pipefail and also prints error objects.
- Naming: add the camelCase rule (PearChat writes pear-chat), and say
  the updater uses productName || name as written.
- Signing: pear make has no signing options; sign the output yourself
  (hardened runtime plus the two Bare entitlements for notarization)
  or build with bare-build --standalone. Only hello-pear-bare and
  hello-pear-qvac-tui sign in npm run make.
- pear sidecar shutdown also stops a running pear seed, and an idle
  sidecar exits on its own after about a minute.
- First download is about 900 MB.

cli reference: the same naming, --install, and sidecar notes, and the
help block is labeled a summary because --help does not list
--install. The Release Overview flag list gains --install.

Cross-links: lead with bare-build on the standalone Bare pages, give
the real trade-off on Bundle a Bare app, qualify pear make with Pear
3.7.0 everywhere, mark the deployment checklist as desktop-only, move
the Distribute as a binary pointer into "When this is the wrong tool",
add pear make --name to the templates' rename lists, and put the guide
link in the skills' link lists with a trailing slash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): end the 3.7.0 pear info sample with its Success line

pear info prints ✔ Success after the last row: its final tagger returns
false, so the outputter prints Success (cmd/info.js, lib/terminal.js at
v3.7.0).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: keep the pear make sentences off the lines #445 rewrites

#445 moves the template pages from /p2p/getting-started/ to
/pear/getting-started/ and rewrites every link to them. Five lines that
carry a hello-pear-bare link also had a pear make sentence appended, so
the two PRs conflicted there. Move each sentence into its own paragraph
(or, in the Bare CLI reference, below the next list item), leaving the
linked lines as they are on published. Only content/p2p/getting-started/
index.mdx still conflicts, because #445 relocates the whole block that
#439's npx pear-install line sits in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(examples): run the pear make guide's greeting CLI in CI

Add a build-cli-executable scenario to scripts/test-examples.ts and the
examples.yml matrix. It installs the example and asserts that
`bare bin.mjs Ada` prints "Hello, Ada! (hello-cli v1.0.0)". The
`pear make` steps stay skipped, because CI has no Pear 3.7.0. Commit
the example's lockfile, like most other examples, so CI installs the
same versions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): pear make --install still builds, and pear build takes CLI executables

- --install over an existing pear-make: pear-install's runner catches
  the refusal, prints it and Failed, and sets exit status 1 without
  throwing, so pear make goes on to run the build and exits 1 even when
  the build succeeds. Say so in the how-to, its troubleshooting, and
  the cli reference.
- The install prompt has no space after the warning sign
  (ansi.warning + 'The pear-make CLI...').
- Where to go next: show how pear build takes each executable as its
  host's app, so readers aren't sent to a desktop-only deploy step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): mark Pear 3.7 stable now that production serves it

The production channel serves 3.7.0 (pear info --json on the production
link reports version 3.7.0, length 92), and holepunchto/pear published
the v3.7.0 GitHub release on 2026-11-12.

- docs-versions: 3.7 is stable, 3.6 is no longer.
- Release Overview: date the 3.7.0 entry 2026-11-12, replace the
  before-merge TODO with a provenance note, and drop the ?v=3.7 pins,
  as the 3.6.0 entry does for its links.
- upstream-releases-state: pin holepunchto/pear to v3.7.0, now that the
  release exists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): unpin the pear make reference link now that 3.7 is stable

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): recapture the 3.7.0 samples and menu screenshots on the tag

Captured from a v3.7.0 build (2a67b71) running with its own platform
directory on a local HyperDHT testnet, with a staged pear-chat@1.0.1
drive carrying darwin-arm64, linux-x64, and win32-x64 targets:

- pear info (human and --json) from a second machine that does not own
  the link: the labeled rows, Targets, and the ✔ Success line match the
  documented format. The samples now hold the captured values.
- pear seed live view (pty): Blobs Key: row confirmed; the sample now
  holds the captured frame. --no-tty prints "... blobs key".
- pear gc cores on a writable link prints "Cleared core  ~" and
  "Cleared blobs ~" after the CLEAR prompt, as documented.
- pear seed exits 1 on pear sidecar shutdown, with "x-x sidecar
  disconnected" (--no-tty) and the ERR_CONNECTION error object (--json).
- Both menu screenshots re-rendered from the build's screen buffer, and
  the Ship help panel, which now lists make, is back on the
  interactive-menu page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(pear): let Vale read the 3.7.0 seed sample as code

Without a blank line after the VersionGate tag, the fence was read as
prose, and Vale took 974nd in the captured link for an ordinal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
…nd Bare Kit 3.1.0 (#451)

* docs(bare): document Bare 1.37.0 and 1.37.1 and refresh the module references

Runtime reference: the freertos and watchos platforms and the riscv32,
armv8m and arm64-32 architectures (with Since badges and the target.h
macros), V8 15.7 with the DrumBrake WebAssembly interpreter, the iOS
extended virtual addressing entitlement, the dropped-transition fix, and
bare-host-parser for addon conditions. The doc-states are regenerated:
1.37.0 and 1.37.1 enter the window and push out 1.31.0 and 1.28.2, so the
1.31/1.32 markers on Addon and Thread become prose.

WebAssembly on iOS: bare-wasm, the WebAssembly addons explanation and the
sandboxed-addon how-to no longer say WebAssembly is unavailable on iOS.

Module references: bare-rpc 2.0.0 (cancellation, with a "Changes in
v2.0.0" section), bare-addon-resolve 1.12.0, bare-pack 3.1.0, bare-realm
2.1.1, bare-type 1.6.0, bare-module 7.5.2, bare-module-traverse 2.7.6,
bare-logger 2.0.6, bare-stow 0.3.7, bare-sidecar 0.5.16, bare-tls 3.2.1,
bare-system-logger 1.0.7, bare-wasm-abi 0.1.2, and pin bumps for bare-dns,
bare-make, bare-path and bare-wasi. Prose lives in the refgen layouts, so a
--pinned regeneration leaves every page byte-identical.

Release overview: Bare v1.37.0, v1.37.1, Bare Kit 3.1.0 and the module
updates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): bring the Bare Kit reference to 3.1.0 and add bare-kit-python

bare-kit-swift 2.3.0, bare-kit-kotlin 0.2.3 and bare-kit-python 0.2.1
build Bare Kit 3.1.0, which embeds Bare 1.37.1. Adds a Python section
written from src/bare_kit/worklet.py, an iOS entitlement section for the
extended virtual addressing entitlement that Bare 1.37 needs on devices,
and a table of which Bare each Bare Kit release embeds. The Swift and
Python examples were run on macOS against an echo bundle.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): add a how-to for migrating to Bare Kit 3

Walks a React Native or native app from Bare Kit 2 and
react-native-bare-kit 0.16 to Bare Kit 3: linking Bare Kit with
bare-stow, Bare.IPC instead of the BareKit global, resources instead of
the assets option, porting to the Swift, Kotlin or Python bindings, the
iOS entitlement, and WebAssembly on iOS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): update the native how-tos for Bare Kit 3

The React Native, suspension and RPC bridge how-tos used the BareKit
global, which Bare Kit 3 removed, and linked addons with bare-link, which
react-native-bare-kit 0.17 no longer builds into the app. They now use
Bare.IPC and bare-stow link. The RPC bridge's streaming snippet never sent
its request; it now calls req.send() and notes that bare-rpc 2.0
cancellation needs a cancel-aware peer. The Bluetooth setup guide notes
that its link script is for react-native-bare-kit 0.16.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): fix accuracy issues found reviewing the Bare Kit 3 pages

- Migration guide: bare-stow lays out worklet assets under the name
  bare-stow and starts bare-stow.bundle with the source inline, so the
  assets step now packs with bare-stow instead of starting 'app.bundle'.
  The Swift and Kotlin snippets close the IPC before wait(), which
  otherwise never returns.
- WebAssembly on iOS: the fallback to an addon's .wasm build happens only
  when wasi-wasm32 is among the resolved hosts, which the bare-pack mobile
  presets and the bare-stow bare-kit/react-native targets leave out; the
  x64 iOS simulator's V8 build leaves WebAssembly out; the WebAssembly
  global was missing before 1.37, not throwing.
- bare-stow 0.3.2 to 0.3.6 wrote `from: "2.2.0"` for bare-kit-swift, so a
  package update alone brings an app onto Bare Kit 3.1.0 and the iOS
  entitlement requirement.
- Release overview: the bindings shipped on 2026-11-12, and bare-stow
  0.3.3 exported link() and resources from its type declarations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): fix issues found in an adversarial review of the Bare Kit 3 pages

Migration guide and React Native how-to:
- Install bare-stow-runtime. The code bare-stow wraps around each entry
  imports it, so `bare-stow link` fails with MODULE_NOT_FOUND without it.
- The `pack --target react-native` path needs bare-stow-target-react-native,
  the generated package as an app dependency, and an entry that takes its
  stream as an argument rather than using Bare.IPC.
- Android needs JitPack among the repositories, Kotlin 2.4 or later and
  minSdk 29.
- bare-stow 0.2.0 through 0.3.6, not 0.3.2 through 0.3.6, wrote a `from:`
  requirement for bare-kit-swift that now resolves to 2.3.0.
- Note the shared V8 heap reservation, say "the same API" rather than
  "the same stream", make the bare-stow folder conditional, add
  troubleshooting rows, and fix the react-native-bare-kit version name.

Bare Kit reference: give binding version ranges in the Bundled Bare version
table, list the exact bare-kit-kotlin pin of each bare-stow release, and say
the app still needs JitPack.

Bare 1.37:
- Document pointer compression on all 64-bit targets, which makes every
  heap in a process share one reservation of about 4 GiB.
- The dynamic import() wasi bug was in libjs, which kept only the first
  import attribute, and Bare 1.37.0 fixed it. Correct bare-module, the
  sandboxed-addon how-to and the release overview.
- Add the new and removed ABI exports, align the transition no-op wording
  with the runtime page, and qualify the WebAssembly callout.

Module references (layouts, regenerated with --pinned):
- bare-rpc: onrequest defaults to an empty CommandRouter that answers
  UNKNOWN_COMMAND, not a no-op; RPCIncomingRequest.reply sends nothing once
  cancelled; opts takes AbortController from v2.0.0.
- bare-stow: a JavaScript harness also moved to bare-rpc 2.x, and v0.3.7
  links bare-kit-swift from 2.3.0 and bare-kit-kotlin v0.2.+.
- bare-system-logger: fatal() ends the process.
- Release overview: bare-module-traverse parses every host with
  bare-host-parser, and bare-sidecar 0.5.16 adds two builtin addons.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): finish the Bare Kit 3 review follow-ups

- Migration guide: trim the WebAssembly step to what a migrating app has to
  check, and leave the explanation to the WebAssembly addons page. Note that
  Bare Kit 3 no longer builds in bare-crypto, bare-os, bare-pipe and
  bare-ipc, so a worklet that uses them must link them. Drop "now" from the
  open-IPC sentence, because a Bare Kit 2 IPC kept the worklet alive too.
- bare-path: path.resolve() reads a working directory of any length from
  v3.1.3. Before, one of 4,096 bytes or more threw ENOBUFS. Added as a layout
  patch and regenerated with --pinned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
… packages (#450)

* docs(bare): document Bare 1.37.0 and 1.37.1 and refresh the module references

Runtime reference: the freertos and watchos platforms and the riscv32,
armv8m and arm64-32 architectures (with Since badges and the target.h
macros), V8 15.7 with the DrumBrake WebAssembly interpreter, the iOS
extended virtual addressing entitlement, the dropped-transition fix, and
bare-host-parser for addon conditions. The doc-states are regenerated:
1.37.0 and 1.37.1 enter the window and push out 1.31.0 and 1.28.2, so the
1.31/1.32 markers on Addon and Thread become prose.

WebAssembly on iOS: bare-wasm, the WebAssembly addons explanation and the
sandboxed-addon how-to no longer say WebAssembly is unavailable on iOS.

Module references: bare-rpc 2.0.0 (cancellation, with a "Changes in
v2.0.0" section), bare-addon-resolve 1.12.0, bare-pack 3.1.0, bare-realm
2.1.1, bare-type 1.6.0, bare-module 7.5.2, bare-module-traverse 2.7.6,
bare-logger 2.0.6, bare-stow 0.3.7, bare-sidecar 0.5.16, bare-tls 3.2.1,
bare-system-logger 1.0.7, bare-wasm-abi 0.1.2, and pin bumps for bare-dns,
bare-make, bare-path and bare-wasi. Prose lives in the refgen layouts, so a
--pinned regeneration leaves every page byte-identical.

Release overview: Bare v1.37.0, v1.37.1, Bare Kit 3.1.0 and the module
updates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): bring the Bare Kit reference to 3.1.0 and add bare-kit-python

bare-kit-swift 2.3.0, bare-kit-kotlin 0.2.3 and bare-kit-python 0.2.1
build Bare Kit 3.1.0, which embeds Bare 1.37.1. Adds a Python section
written from src/bare_kit/worklet.py, an iOS entitlement section for the
extended virtual addressing entitlement that Bare 1.37 needs on devices,
and a table of which Bare each Bare Kit release embeds. The Swift and
Python examples were run on macOS against an echo bundle.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): add a how-to for migrating to Bare Kit 3

Walks a React Native or native app from Bare Kit 2 and
react-native-bare-kit 0.16 to Bare Kit 3: linking Bare Kit with
bare-stow, Bare.IPC instead of the BareKit global, resources instead of
the assets option, porting to the Swift, Kotlin or Python bindings, the
iOS entitlement, and WebAssembly on iOS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): update the native how-tos for Bare Kit 3

The React Native, suspension and RPC bridge how-tos used the BareKit
global, which Bare Kit 3 removed, and linked addons with bare-link, which
react-native-bare-kit 0.17 no longer builds into the app. They now use
Bare.IPC and bare-stow link. The RPC bridge's streaming snippet never sent
its request; it now calls req.send() and notes that bare-rpc 2.0
cancellation needs a cancel-aware peer. The Bluetooth setup guide notes
that its link script is for react-native-bare-kit 0.16.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): fix accuracy issues found reviewing the Bare Kit 3 pages

- Migration guide: bare-stow lays out worklet assets under the name
  bare-stow and starts bare-stow.bundle with the source inline, so the
  assets step now packs with bare-stow instead of starting 'app.bundle'.
  The Swift and Kotlin snippets close the IPC before wait(), which
  otherwise never returns.
- WebAssembly on iOS: the fallback to an addon's .wasm build happens only
  when wasi-wasm32 is among the resolved hosts, which the bare-pack mobile
  presets and the bare-stow bare-kit/react-native targets leave out; the
  x64 iOS simulator's V8 build leaves WebAssembly out; the WebAssembly
  global was missing before 1.37, not throwing.
- bare-stow 0.3.2 to 0.3.6 wrote `from: "2.2.0"` for bare-kit-swift, so a
  package update alone brings an app onto Bare Kit 3.1.0 and the iOS
  entitlement requirement.
- Release overview: the bindings shipped on 2026-11-12, and bare-stow
  0.3.3 exported link() and resources from its type declarations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): add reference pages for the Swift, Kotlin and Python host packages

Document the 15 non-JavaScript packages that let a native host run Bare and
talk to it, one page per language under Reference > Bare > Native host
packages:

- Swift: bare-sidecar-swift 0.1.3, bare-stow-host-swift 0.2.1,
  bare-rpc-swift 3.0.0, compact-encoding-swift 1.0.1, hyperschema-swift
  1.0.1, hrpc-swift 1.0.0
- Kotlin: bare-stow-host-kotlin 0.2.2, bare-rpc-kotlin 0.6.0,
  compact-encoding-kotlin 0.3.0
- Python: bare-sidecar 0.1.3, bare-stow-host 0.2.1, bare-rpc 0.3.0,
  compact-encoding 0.1.1, hrpc-python 0.1.1, hyperschema-python 0.1.0

Each section covers install, platforms, a minimal example and every public
type and member, written from the source at the latest release. The
examples and behavior were verified by running the packages on macOS,
including a bare-stow bundle booted through the generated Kotlin (JVM
worklet) and Python (sidecar) harnesses against JS bare-rpc 2.0.0.

The pages state the cross-version facts readers trip over: cancellation
needs JS bare-rpc 2.0.0, hrpc-swift 1.0.0 output targets the bare-rpc-swift
1.x delegate API, and versioned Hyperschema types framed by hyperschema
1.25+ don't match the generated Swift and Python codecs.

The modules index lists the 15 packages under Native development kits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): link the Bare Kit 3 pages from the host package references

The Python page now links bare-kit#python for running Bare in a worklet
instead of a sidecar. The Protocol section of bare-stow points its
stow-host bullets at the native host package pages instead of the raw
GitHub repositories, through a layout patch so regenerating the page
keeps the links.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): fix the accuracy issues a review found in the host package pages

An adversarial review against the released sources found these problems,
each re-checked against the code before changing the page.

Swift:
- The hrpc-swift JS example called schema.namespace('chat') twice, which
  throws "Namespace already exists". It now creates the namespace once.
- The list of mismatches with JS Hyperschema now covers compact-struct
  flags (fixed-width in JS, a uint in Swift), bool arrays (an optional one
  becomes a single flag, a required one doesn't compile), and decoding data
  written before optional fields were added. Versioned framing applies only
  to versions that aren't compact structs.
- hrpc-swift: the generated package needs macOS 13 / iOS 15 in every case,
  because the Schema package does. Empty payloads also break send
  commands. The error table adds STREAM_ERROR and PROTOCOL_ERROR.
- WORKER_CLOSED: a transport that ends before ready is a crash, reported
  as WORKER_EXITED or WORKER_KILLED. ready() is documented to match.
- spawn() can throw a POSIXError while creating the IPC socket, and a
  failed transport write fails an RPC session.

Python:
- hyperschema-python loses bool arrays without an error, and drops
  `version` when it decodes a versioned type (the `map` of a version isn't
  applied either). Constant fields aren't supported, and the page says how
  they break.
- The supported primitives are now listed explicitly. int8/16/32/64 aren't
  ported, but int24 to int56 are. `json` shadows a module, not a builtin.
- WORKER_CLOSED, ready, read() and write() match the released IPC. A
  Sidecar drops writes instead of raising.
- Leaving `async with RPC(...)` ends the worker. A cancelled caller gets
  asyncio.CancelledError. The generated schema.py and hrpc.py share names
  with PyPI packages. The harness example closes the sidecar after exited().

Kotlin:
- FrameDecoder doesn't validate the length, so it can throw, hang or lose
  sync rather than always throwing.
- write() and TRANSPORT_ERROR: WORKER_CLOSED once terminating or exited.
  The WORKER_CLOSED and ready() rows match the crash handling, as in Swift.
- Rpc.close() returns at once from a streamed body too. Messages.encode
  skips more data than listed. DecodingException has a public constructor.
- The stow example closes the transport and worklet, as the bare-stow
  harness does. The maintainer note names bare-kit-kotlin v0.2.3.

Modules index: only the sidecar packages start Bare. The worklet bindings
are pointed to in the Bare Kit reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): fix issues found in an adversarial review of the Bare Kit 3 pages

Migration guide and React Native how-to:
- Install bare-stow-runtime. The code bare-stow wraps around each entry
  imports it, so `bare-stow link` fails with MODULE_NOT_FOUND without it.
- The `pack --target react-native` path needs bare-stow-target-react-native,
  the generated package as an app dependency, and an entry that takes its
  stream as an argument rather than using Bare.IPC.
- Android needs JitPack among the repositories, Kotlin 2.4 or later and
  minSdk 29.
- bare-stow 0.2.0 through 0.3.6, not 0.3.2 through 0.3.6, wrote a `from:`
  requirement for bare-kit-swift that now resolves to 2.3.0.
- Note the shared V8 heap reservation, say "the same API" rather than
  "the same stream", make the bare-stow folder conditional, add
  troubleshooting rows, and fix the react-native-bare-kit version name.

Bare Kit reference: give binding version ranges in the Bundled Bare version
table, list the exact bare-kit-kotlin pin of each bare-stow release, and say
the app still needs JitPack.

Bare 1.37:
- Document pointer compression on all 64-bit targets, which makes every
  heap in a process share one reservation of about 4 GiB.
- The dynamic import() wasi bug was in libjs, which kept only the first
  import attribute, and Bare 1.37.0 fixed it. Correct bare-module, the
  sandboxed-addon how-to and the release overview.
- Add the new and removed ABI exports, align the transition no-op wording
  with the runtime page, and qualify the WebAssembly callout.

Module references (layouts, regenerated with --pinned):
- bare-rpc: onrequest defaults to an empty CommandRouter that answers
  UNKNOWN_COMMAND, not a no-op; RPCIncomingRequest.reply sends nothing once
  cancelled; opts takes AbortController from v2.0.0.
- bare-stow: a JavaScript harness also moved to bare-rpc 2.x, and v0.3.7
  links bare-kit-swift from 2.3.0 and bare-kit-kotlin v0.2.+.
- bare-system-logger: fatal() ends the process.
- Release overview: bare-module-traverse parses every host with
  bare-host-parser, and bare-sidecar 0.5.16 adds two builtin addons.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): finish the Bare Kit 3 review follow-ups

- Migration guide: trim the WebAssembly step to what a migrating app has to
  check, and leave the explanation to the WebAssembly addons page. Note that
  Bare Kit 3 no longer builds in bare-crypto, bare-os, bare-pipe and
  bare-ipc, so a worklet that uses them must link them. Drop "now" from the
  open-IPC sentence, because a Bare Kit 2 IPC kept the worklet alive too.
- bare-path: path.resolve() reads a working directory of any length from
  v3.1.3. Before, one of 4,096 bytes or more threw ENOBUFS. Added as a layout
  patch and regenerated with --pinned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(bare): link the host package mentions to their reference pages

The Bare Kit 3 guide, the Bare Kit reference, the RPC explanation, the
native RPC bridge how-to and the HRPC helper page linked bare-sidecar-swift,
bare-sidecar-python and hrpc-swift to their GitHub repos, and named the
bare-rpc ports without links. They now point at the Swift, Kotlin and
Python reference pages. The modules index keeps its repo links, because each
row already has a reference link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
#452)

* docs(bare): bring ten module references up to their latest releases

Regenerates bare-bundle 1.12.0, bare-fetch 3.5.0, bare-pack 3.2.0, bare-ws 3.3.0,
bare-buffer 3.7.2, bare-inspect 3.1.11, bare-url 2.5.7, bare-stow 0.3.9 and the
3.x to 4.0.0 majors bare-tls and bare-https.

The bare-tls and bare-https pages carry an "Upgrading from 3.x" callout for the
renamed handshake events (`secureConnect`, `secureConnection`, `tlsClientError`)
and the new `handshakeTimeout` option. bare-stow documents the `engine` target
option, bare-pack the module type recorded in the bundle, and bare-buffer and
bare-inspect their new threat-model section.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs: refresh the boilerplate snapshots and the GitHub Actions reference

Re-pins the seven watched boilerplates and refreshes the vendored lockfiles of
hello-pear-bare, hello-pear-daemon and hello-pear-qvac-tui. hello-pear-react-native
now inlines its worker and needs `npm run link`, so the template page, the shared
worker callout and the Electron integration guide say so.

The GitHub Actions reference follows upstream: `create-release` became
`create-github-release` and `publish` is an alias of `publish-npm`. The Pear CLI
reference mentions `npx pear-install --arch`.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs: add the Bare 1.36.1, 1.36.2 and pear-install 1.6.0 changelog entries

The P2P releases are left for their own change, so their watcher baselines stay behind.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(p2p): bring eight reference pages and the changelog up to date with upstream

Re-audits hypercore 11.40.4, hyperdht 6.36.0, autobee 2.13.6, blind-peer 3.18.3,
blind-peering 2.14.0, compact-encoding 3.7.0, hrpc 4.3.2 and protomux 3.13.1
against the upstream diffs and repins them. Adds one curated "P2P module updates"
changelog entry covering hypercore, hyperdht, autobee, compact-encoding, corestore,
protomux, blind-peering and blind-peer, and advances the watcher baselines.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(hyperdrive): note that drive.contentKey is the Blobs Key Pear prints

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* ci(examples): run the scenarios on Bare 1.37.1

The refreshed hello-pear-bare and hello-pear-daemon lockfiles resolve bare-worker
with a nested bare-module that requires Bare >=1.35.0, so both scenarios failed on
the pinned 1.34.1 with UNSUPPORTED_ENGINE. That is the condition the old comment
named for lifting the pin: hello-pear-bare resolving bare-worker 4.5.3 or later.

All twelve scenarios the matrix runs pass on bare-runtime 1.37.1 (hello-pear-qvac-tui
stays out of CI). The history that lived in the comment is in this message:
1.33.0 moved the resolver to bare-module v7, which bare-worker 4.4.0 can't use, so
the pin stayed on 1.32.0 until bare-worker 4.5.0, and on 1.34.1 until the lockfile
resolved bare-worker 4.5.3, which fails on 1.34.1 and passes on 1.35 and later.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>

This branch was successfully deployed

1 active (outdated) deployment
preview — ca7d3ae4 Deployed Nov 5, 2026 by kinsta[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants