Repository navigation
Release published docs to main - #306
Open
lucas-tortora wants to merge 123 commits into
Open
lucas-tortora wants to merge 123 commits into
lucas-tortora wants to merge 123 commits into
Conversation
- 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>
Preview deployments for pear-docs preview ⚡️
Commit: Deployment ID: Static site name: |
* 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>
…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 (`**bold**`, closing backticks as ```, 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 (`**bold**`, closing backticks as ```, 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
publishedbranch tomain, replacing the legacy docs site with the current published Pear docs platform.mainintopublishedwith all conflicts resolved in favor ofpublished.mainwith 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.mdguide/making-a-pear-desktop-app.mdguide/starting-a-pear-desktop-project.mdWhat's included
@tetherto/docs-seo-*end-to-end (metadata, sitemap, robots, JSON-LD, OG)Test plan
mainMade with Cursor