docs: add a BetterMan verification skill and feature map

[amanthanvi]

What

Adds a project-local verification skill at .agents/skills/verify-betterman/ (linked from .cursor/skills/verify-betterman) plus a feature map, helper scripts, and an optional manual smoke workflow.

• pnpm verify:launch starts Convex and Next on http://127.0.0.1:3000 only when that port is free. Next binds with --hostname 127.0.0.1. Session names and the state directory are per checkout.
• VERIFY_ID is 3 to 32 characters of lowercase letters, digits, or hyphens. A 2-character value was briefly accepted so a ci proof could run. That widening is reverted. VERIFY_ID=ci is rejected with VERIFY_ID must be 3-32 characters of lowercase letters, digits, or hyphens. The manual workflow sets VERIFY_ID=cix.
• A later launch prints REUSED only when doctor is READY and the live listener matches the recorded pid and start time and is under this repo. Otherwise it exits 2 and leaves that process running. The message says to stop that process yourself, then run pnpm verify:launch again.
• An empty dataset is seeded only when the live listener belongs to this repo or this checkout already owns it. Belonging means the cwd or an argv, after path.resolve, equals this repo root or starts with that root plus a path separator. A sibling such as <repoRoot>-other does not match, a path that uses .. to leave the checkout does not match, and neither does an argument that only contains the root, such as --config=<repoRoot>/nextjs. A listener that fails the check is refused. Launch exits 2, does not seed it, and does not stop it.
• pnpm verify:smoke and pnpm verify:drive refuse unless that same pid, start time, repo, and Next session match. When the state directory belongs to another user, smoke prints smoke: refusing <dir>: owned by uid ... and exits 1.
• Listener ownership reads Linux /proc for a loopback base URL. Loopback is 127.0.0.1, localhost, or [::1], so doctor runs that check for http://[::1]. A doctor URL that is not loopback skips it. On any other platform, the loopback check exits 2 and prints Linux-only.
• Launch refuses http://[::1]:3000 with exit 2 before it creates state or starts Convex or Next. The message says to use http://127.0.0.1:3000. Next is started with --hostname 127.0.0.1.
• Seed runs only for an anonymous loopback deployment, including [::1]. npx convex env set receives an allowlisted environment (PATH, HOME, USER, LOGNAME, SHELL, locale and temp variables, NVM_DIR, PNPM_HOME, CONVEX_AGENT_MODE=anonymous, an anonymous: deployment name, and the loopback Convex URLs). That child does not receive BETTERMAN_DATASET_STAGE or CONVEX_DEPLOY_KEY. The seed process sets BETTERMAN_DATASET_STAGE=prod itself. Doctor is READY only when /api/v1/info reports pageCount greater than 0.
• Launch writes generated-snapshot.json only after it owns the Next server, and only before that server starts. A non-zero exit deletes that file when bmv-<id>-next is not running, including a stale snapshot whose Next process already died, and leaves it when that session is still running. Cleanup restores an owned snapshot. Cleanup does not overwrite nextjs/next-env.d.ts edited after the snapshot. If a file changed since a snapshot this checkout does not own, cleanup leaves the file in place, warns, and copies it under generated-backup/.
• State directories are mode 0700. run.json and the other state files are mode 0600.
• scripts/verify-paths.d.cts types the CommonJS path helper imported by evidence.ts. pnpm verify:typecheck runs tsc --noEmit -p .agents/skills/verify-betterman/tsconfig.typecheck.json. The project is not named tsconfig.json, so Node does not apply its paths while loading the Playwright specs. nextjs/tsconfig.json and convex/tsconfig.json do not include .agents.
• .github/workflows/verify-smoke.yml is workflow_dispatch only, with permissions: contents: read. It sets VERIFY_ID=cix and uploads /tmp/betterman-verify-cix/evidence.

Why

Agents need a scripted way to launch BetterMan, drive it like a reader, and attach evidence. The feature map is the sweep order and the per-feature driving notes.

Checklist

• Skill, feature map, and helpers only. No product or app code changes.
• pnpm verify:doctor and pnpm verify:drive recorded below after a local run.
• CHANGELOG.md updated under Unreleased.
• pnpm next:lint, pnpm next:grammar, pnpm next:test (not required: no Next.js or Convex code changes)
• pnpm ingest:lint, pnpm ingest:test (not required: no ingestion changes)

How launch actually behaves

1. When the base URL is loopback (127.0.0.1, localhost, or [::1]) and /proc is missing, launch and doctor exit 2 with Linux-only. A doctor URL that is not loopback skips that listener check. Launch refuses http://[::1] before that check and before any server starts.
2. When doctor is READY and run.json matches the listener pid and start time, and that process is under this repo, launch prints REUSED and exits 0. If the pid, start time, or repo does not match, launch exits 2 and leaves that process running. A non-zero exit deletes generated-snapshot.json when bmv-<id>-next is not running, and leaves the snapshot when that session is still live.
3. When port 3000 is open, the dataset is empty, and the listener's cwd and argv do not equal this repo root and do not start with that root plus a separator after path.resolve, launch exits 2 without seeding. It deletes generated-snapshot.json when bmv-<id>-next is not running, and leaves the snapshot when that session is still live. When the listener belongs to this repo, launch may seed it and leave that process running.
4. When port 3000 is free, launch creates /tmp/betterman-verify-<id> mode 0700, starts Convex with remote Convex variables unset, deletes the Next fetch cache, snapshots nextjs/next-env.d.ts, nextjs/AGENTS.md, and nextjs/CLAUDE.md, and starts Next on 127.0.0.1:3000. It records the listener pid, start time, and cwd in run.json mode 0600. When launch exits after owning Next, it restores that snapshot. A non-zero exit then deletes the snapshot file when bmv-<id>-next is not running.
5. Seed runs only for an anonymous loopback deployment, including [::1]. npx convex env set gets the allowlisted environment above and does not inherit BETTERMAN_DATASET_STAGE. The seed process sets BETTERMAN_DATASET_STAGE=prod. After seeding a Next process this skill started, launch clears the fetch cache, restarts Next, and waits until pageCount is greater than 0.
6. Cleanup stops this checkout's recorded sessions and restores the owned snapshot. Cleanup does not overwrite nextjs/next-env.d.ts edited after the snapshot, and a snapshot this checkout does not own is not written over a file that has changed. Cleanup warns and backs that file up under generated-backup/. Evidence stays.

Proof

Head fc022b03fa6021751269b95a296565aaf2cbad02. Delta since f72bdb8013ea7e5001b86ae295423d78ad95085f:

pnpm verify:test
pnpm verify:typecheck

• pnpm verify:test passed, 6 tests, 0 skipped. tmux is present, so the live-session test ran. An owned snapshot whose run.json lists bmv-snastale-next, with no tmux session, is removed on a refused http://[::1]:3000 launch. stderr contains removing generated-snapshot.json; Next session is not running. A live bmv-snalive-next session keeps those snapshot bytes. stderr contains leaving generated-snapshot.json; Next session is still running. That live test skips when tmux -V fails. Cleanup leaves a nextjs/next-env.d.ts edit whose mtime is newer than the owned snapshot, prints changed since the recorded snapshot, and copies the bytes under generated-backup/. An edit with an older mtime is restored.
• pnpm verify:typecheck exited 0.

Delta on 347bf14: launch.mjs --base-url http://[::1]:3000 with VERIFY_ID=v6ref exits 2, prints Use http://127.0.0.1:3000, leaves the state directory empty, and does not create bmv-v6ref-convex or bmv-v6ref-next. Doctor still treats http://[::1]:3000 as loopback.

Delta on 548e2ff: http://[::1]:3000 is loopback with port 3000, http://172.30.0.2:9 is not, and path.resolve keeps a .. escape outside the repo.

The VERIFY_ID=cix launch, smoke, and cleanup proof below is from 176da33 and was not re-run on this head. origin/main (cd2583853df856700c12915e5c4d15ef69a9453a) is an ancestor.

pnpm verify:typecheck
pnpm verify:test
VERIFY_ID=ci pnpm verify:launch
VERIFY_ID=cix VERIFY_SKIP_BROWSER_INSTALL=1 pnpm verify:launch
VERIFY_ID=cix pnpm verify:smoke
VERIFY_ID=cix pnpm verify:cleanup
git status --short

Results on 176da33:

• pnpm verify:typecheck (tsc --noEmit -p .agents/skills/verify-betterman/tsconfig.typecheck.json) exited 0. The same command reports TS7016 on evidence.ts for ./verify-paths.cjs when scripts/verify-paths.d.cts is absent.
• pnpm verify:test passed, 2 tests on that head. The refused-launch test starts a foreign server with cwd /tmp and argv --config=<repoRoot>/nextjs, expects exit 2 and Refusing to seed. It also checks file mode 0600, directory mode 0700, and that a cwd or argv belongs to this repo only when it equals the repo root or starts with that root plus a separator.
• VERIFY_ID=ci pnpm verify:launch exited 1. The message is VERIFY_ID must be 3-32 characters of lowercase letters, digits, or hyphens.
• VERIFY_ID=cix pnpm verify:launch exited 0. Doctor printed info pageCount=7 release=e2e-debian-1792066324688, pid 35091, cwd=/workspace/nextjs, start=642731, and READY. Evidence is /tmp/betterman-verify-cix/evidence. /tmp/betterman-verify-cix is mode 0700. run.json is mode 0600. The dataset was already populated, so this launch did not run convex env set.
• VERIFY_ID=cix pnpm verify:smoke passed 1 test (3.1s). Screenshots are smoke-home.png, smoke-search.png, and smoke-tar.png in that evidence directory.
• VERIFY_ID=cix pnpm verify:cleanup stopped bmv-cix-convex and bmv-cix-next. Evidence remains at /tmp/betterman-verify-cix/evidence. git status --short was empty.

Home search from the VERIFY_ID=cix smoke
tar(1) from the VERIFY_ID=cix smoke

Command log: /opt/cursor/artifacts/verify/cix-proof.log.

INCONCLUSIVE:

• Service worker cache hits. next dev leaves the worker unregistered. Cached pages need next start.
• License body text. The E2E seed has an empty package list.
• The error boundary was not forced. That would take down the shared Convex deployment.
• Arch and Alpine have no seeded release.

Suggested CI smoke

.github/workflows/verify-smoke.yml stays workflow_dispatch only. Permissions are contents: read. It sets VERIFY_ID=cix, runs launch, doctor, and smoke, uploads /tmp/betterman-verify-cix/evidence, then runs cleanup. It does not edit ci.yml.

_{To show artifacts inline, enable in settings.}

  

Summary by Sourcery

Add an isolated, evidence-producing verification workflow that lets agents launch BetterMan locally and exercise its reader experience end to end.

New Features:

• Add a project-local BetterMan verification skill with a feature map and Playwright-based smoke and regression drives.
• Add isolated launch, health-check, seeding, evidence, and cleanup commands for local BetterMan verification.
• Add an optional manually triggered CI workflow for running the verification smoke test and uploading evidence.

Enhancements:

• Document verification procedures, proof requirements, and generated-file cleanup guidance for agents.
• Isolate verification state and scrub remote Convex configuration to protect against accidental use of non-local deployments.

Build:

• Add package scripts for launching, checking, smoking, driving, and cleaning up verification runs.

CI:

• Add a manual GitHub Actions workflow that launches the local app, runs verification, uploads evidence, and cleans up without affecting required checks.

Documentation:

• Add the BetterMan feature map covering reader flows, navigation, local state, metadata, and edge cases.
• Update AGENTS.md and CHANGELOG.md with the verification workflow and usage guidance.

Tests:

• Add Playwright smoke and feature-drive coverage for core BetterMan reader journeys and UI behaviors.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
betterman	Ready	Preview	Oct 15, 2026 3:09pm UTC

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 52bb69b7-f99f-47b3-bc8d-5a1e12f5877b

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Reviewer's Guide

This PR adds a project-local, loopback-isolated BetterMan verification system: extensive feature-map guidance, tmux-managed Convex/Next launch and health scripts, Playwright smoke/full-drive evidence capture, cleanup/reporting conventions, agent guidance, and an optional manually triggered CI workflow.

Sequence diagram for the BetterMan verification smoke flow

sequenceDiagram
    participant Agent
    participant Smoke as smoke.mjs
    participant Doctor as doctor.mjs
    participant Next as Next.js
    participant Browser as Playwright
    participant Evidence

    Agent->>Smoke: pnpm verify:smoke
    Smoke->>Doctor: checkHealth(baseUrl)
    Doctor->>Next: GET /
    Next-->>Doctor: Search box HTML
    Doctor->>Next: GET /api/v1/info
    Next-->>Doctor: pageCount
    Doctor->>Next: GET /api/v1/search?q=tar&limit=5
    Next-->>Doctor: tar(1) result
    Doctor-->>Smoke: READY
    Smoke->>Browser: run smoke.spec.ts
    Browser->>Next: Open home
    Browser->>Next: Search tar
    Browser->>Next: Open tar(1)
    Browser->>Evidence: Write screenshots and traces

Loading

Sequence diagram for launching and cleaning up BetterMan

sequenceDiagram
    participant Agent
    participant Launch as launch.mjs
    participant Doctor as checkHealth
    participant Convex as Convex tmux session
    participant Next as Next tmux session
    participant Cleanup as cleanup.mjs
    participant Evidence

    Agent->>Launch: pnpm verify:launch
    Launch->>Doctor: checkHealth(baseUrl)
    alt READY
        Doctor-->>Launch: Existing instance ready
    else Not ready and port available
        Launch->>Convex: Start convex dev
        Convex-->>Launch: Convex functions ready
        Launch->>Next: Start Next.js dev
        Next-->>Launch: Port 3000 ready
        Launch->>Doctor: checkHealth(baseUrl)
        alt empty-dataset
            Launch->>Convex: Seed E2E fixture
            Launch->>Next: Restart Next.js
            Launch->>Doctor: checkHealth(baseUrl)
        end
    end
    Launch->>Evidence: Create evidence directory
    Agent->>Cleanup: pnpm verify:cleanup
    Cleanup->>Convex: killTmuxSession
    Cleanup->>Next: killTmuxSession
    Cleanup-->>Agent: Evidence remains on disk

Loading

File-Level Changes

Change	Details	Files
Add a project-local verification skill with documented launch, health-check, browser-driving, evidence, cleanup, and reporting procedures.	Document loopback-only isolation, Convex fixture seeding, tmux ownership, readiness criteria, and cleanup behavior. Define reviewer-facing proof requirements and stable UI selectors, side effects, gotchas, and inconclusive-result handling. Add a feature map covering site chrome, discovery, search, reading, local state, errors, offline behavior, and end-to-end journeys.	.agents/skills/verify-betterman/SKILL.md .agents/skills/verify-betterman/references/features/README.md .agents/skills/verify-betterman/references/features/*.md .cursor/skills/verify-betterman
Implement command-line helpers that provision and manage a local BetterMan verification environment.	Add launch logic for dependencies, Playwright, local Convex and Next tmux sessions, readiness polling, and conditional E2E seeding. Add a read-only doctor that validates the home page, dataset health, and tar(1) search endpoint. Add smoke and full-drive runners that invoke Playwright only after doctor succeeds. Persist owned-session state and retain screenshots, traces, and reports while cleanup stops only recorded skill sessions.	.agents/skills/verify-betterman/scripts/runtime.mjs .agents/skills/verify-betterman/scripts/launch.mjs .agents/skills/verify-betterman/scripts/doctor.mjs .agents/skills/verify-betterman/scripts/smoke.mjs .agents/skills/verify-betterman/scripts/cleanup.mjs .agents/skills/verify-betterman/scripts/evidence.ts package.json
Add Playwright-based smoke and feature-sweep coverage for the documented reader workflows.	Configure a single Chromium project with serial execution, trace collection, and evidence/report output under /tmp/betterman-verify/evidence. Add a short home-to-search-to-tar smoke test. Add a broad sweep for navigation, search, man-page rendering, find and TOC controls, palette, shortcuts, themes, preferences, distro variants, bookmarks, recents, licenses, errors, offline UI, SEO metadata, and cross-page journeys.	.agents/skills/verify-betterman/playwright.config.mjs .agents/skills/verify-betterman/scripts/smoke.spec.ts .agents/skills/verify-betterman/scripts/drive.spec.ts
Integrate the verification workflow into project guidance and provide an optional manual CI entry point.	Point agents to the local skill and require Proof sections for feature pull requests. Add verification commands to the root package scripts and document the skill in the changelog. Add a workflow_dispatch-only GitHub Actions job that installs prerequisites, launches and smoke-tests the app, and always cleans up without altering required CI checks.	AGENTS.md CHANGELOG.md package.json .github/workflows/verify-smoke.yml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Sorry @amanthanvi, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 2 days and 10 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[greptile-apps]

Confidence Score: 5/5

[Low impact] The latest changes appear safe to merge and address the reported cleanup overwrite.

Summary

Adds a local verification skill, feature notes, browser checks, and an optional manual smoke workflow.

• Agents can launch and clean up a private local BetterMan run.
• The feature map gives agents a sweep order for BetterMan reader flows.
• Playwright can smoke-test BetterMan or walk its feature sweep.
• A manual GitHub Actions run can launch BetterMan and upload smoke evidence.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Launch exits] --> B{Started Next?}
  B -->|Yes| C[Restore saved generated files]
  B -->|No| D{Exit failed?}
  C --> D
  D -->|No| E[Keep snapshot]
  D -->|Yes| F{Recorded Next session alive?}
  F -->|Yes| E
  F -->|No| G[Remove stale snapshot]

Loading

_{Reviews (14) · Last reviewed commit: "fix: drop a stale verify snapshot when N..." · Reviewed by Greptile}

[cursor]

@greptileai review

[cursor]

@greptileai review

[cursor]

@greptileai review

[cursor]

@greptileai review

[cursor]

@greptileai review

[cursor]

@greptileai review

[cursor]

@greptileai review

[cursor]

@greptileai review