feat(discovery): ship browser agent metadata

[drewstone]

Summary

• Add discovery/llms.txt and discovery/tangle-agent.json to the Browser Agent package
• Include discovery metadata in npm package files
• Link the live Browser Agent manifest from README

Checks

• jq empty discovery/tangle-agent.json package.json
• git diff --check
• npm pack --dry-run --json confirms discovery files are included
• git merge-tree --write-tree origin/main HEAD

Not run

• pnpm lint: node_modules missing in clean worktree (tsc not found)

[tangletools]

✅ Auto-approved PR — bf835810

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-16T17:44:01Z}

[tangletools]

🟢 Value Audit — sound

Verdict	sound
Concerns	0 (none)
Heuristic	0.0s
Duplication	0.0s
Interrogation	30.0s (2 bridge agents)
Total	30.0s

No concerns — sound change, no better or existing approach found. ✅

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260616T174619Z}

[tangletools]

✅ No Blockers — bf835810

Readiness 73/100 · Confidence 80/100 · 10 findings (1 medium, 9 low)

	deepseek	glm	aggregate
Readiness	80	73	73
Confidence	80	80	80
Correctness	80	73	73
Security	80	73	73
Testing	80	73	73
Architecture	80	73	73

Full multi-shot audit completed 4/4 planned shots over 4 changed files. Global verifier still owns final merge decision. | Full multi-shot audit completed 4/4 planned shots over 4 changed files. Global verifier still owns final merge decision.

🟠 MEDIUM Manifest URL returns 404 — agent discovery instructions point at a dead link — README.md

README.md:52 references https://tangle.tools/.well-known/tangle-browser-agent.json and README.md:50 instructs 'Agents should read the product manifest before generating Browser Agent integration code.' Verified via curl -sIL https://tangle.tools/.well-known/tangle-browser-agent.json → final=404, body is an Astro 'Page Not Found' page. The /​.well-known/ directory itself also 404s. Impact: the entire 'Agent Discovery' section's primary purpose is broken — any agent following the README hits a dead link and cannot read the manifest. Fix: either publish the manifest file before merging this README change, or remove/gate the manifest URL line until the file is live. Keeping a 404 link in a section titled 'Agent Discovery' that exists to make agents discoverable is worse than no section.

🟡 LOW Live .well-known manifest returns 404 (pre-deployment timing) — discovery/llms.txt

Line 7 references 'Live manifest: https://tangle.tools/.well-known/tangle-browser-agent.json' but this URL currently returns HTTP 404. The sibling discovery/tangle-agent.json also references this URL. This is expected pre-deployment behavior (the route likely hasn't been created on the website yet), but if this llms.txt is consumed from the GitHub repo before deployment, readers get a broken link. Not blocking, but worth noting for deployment sequencing.

🟡 LOW Summary paragraph not formatted as blockquote per llms.txt spec — discovery/llms.txt

Line 3-5: The project summary is a plain paragraph. The llms.txt spec (llmstxt.org) requires it in a blockquote: 'A blockquote with a short summary of the project, containing key information necessary for understanding the rest of the file.' Tools that programmatically parse llms.txt files (e.g. llms_txt2ctx CLI) expect the summary in a > prefixed blockquote. Fix: prefix the summary line with > .

🟡 LOW llms.txt does not strictly follow llmstxt.org convention format — discovery/llms.txt

The llmstxt.org specification recommends an H1 title followed by a blockquote summary line and optional linked file listings. This file uses H1 + prose + fenced code blocks instead. This is a cosmetic convention deviation, not a correctness or security issue. Many projects use this relaxed format. Fix (optional): add a one-line blockquote summary after line 1, e.g. '> Agentic browser automation CLI for testing, wallet flows, and evidence capture.'

🟡 LOW Missing env var alternative: GOOGLE_GENERATIVE_AI_API_KEY vs GEMINI_API_KEY — discovery/tangle-agent.json

Line 33 lists google_key as only GOOGLE_GENERATIVE_AI_API_KEY, but src/provider-defaults.ts:95 also accepts GEMINI_API_KEY as an alternative. An LLM agent that only knows GEMINI_API_KEY from Google docs would miss that both names work. Fix: add gemini_alt: "GEMINI_API_KEY" or note in description.

🟡 LOW No automated validation to prevent metadata drift — discovery/tangle-agent.json

No test validates that tangle-agent.json fields (exports, bin, env vars, peer deps) remain in sync with package.json and source exports. Over time, this file could silently diverge. A small vitest that asserts j.bin === Object.keys(packageJson.bin)[0], j.environment.openai_key is in source env-vars, and j.sdk.exports subset of actual index.ts exports would prevent drift.

🟡 LOW No test guards discovery manifest against export/CLI drift — discovery/tangle-agent.json

The manifest hardcodes sdk.exports=[BrowserAgent,PlaywrightDriver], cli.bin=bad, and safe_discovery_commands referencing 'run' and 'snapshot'. If any of these are renamed or removed in a future PR, the shipped discovery file silently goes stale. A lightweight test (e.g., import the package and assert BrowserAgent/PlaywrightDriver are functions; spawn 'bad --help' and check exit 0) would prevent drift. Non-blocking — all values are currently accurate as of this commit.

🟡 LOW sdk.peer_dependency omits optional AI SDK provider packages — discovery/tangle-agent.json

Line 28 lists only playwright as peer_dependency, but package.json peerDependencies also includes @ai-sdk/anthropic and @ai-sdk/google. While these are dynamically imported and optional at runtime (only needed when using those providers), a consumer relying solely on this discovery file would not know they exist. Consider listing them with a note that they're optional.

🟡 LOW No changeset for an npm-publish-surface change — package.json

CLAUDE.md mandates 'Every PR with user-visible changes must include a changeset' and the post-merge changesets.yml workflow only versions/packages when a .changeset/.md exists. Adding discovery to files[] changes the published tarball contents (consumer-visible), so this qualifies. No .changeset/.md is present in the diff. Without it, merging this PR will not bump the version or publish the new discovery files — the change would land on main but never reach npm consumers. Fix: run pnpm changeset, pick patch, summarize 'ship agent discovery manifest (llms.txt, tangle-agent.json) in the npm package', and add the generated .changeset/*.md. This is a release-process finding, not a package.json correctness defect — the one-line edit itself is correct.

🟡 LOW exports map has no ./discovery subpath — package.json

files[] now bundles discovery/tangle-agent.json and discovery/llms.txt, but package.json exports (lines 14-19) only expose '.' → dist/index.js. Consumers cannot do import manifest from '@tangle-network/browser-agent-driver/discovery/tangle-agent.json'. This appears intentional — the assets are meant to be read as static files (and are mirrored at tangle.tools/.well-known/), not imported as modules. No action required unless programmatic in-package discovery is a goal; if so, add "./discovery/tangle-agent.json": "./discovery/tangle-agent.json" to exports.

---

_{tangletools · 2026-06-16T17:51:36Z · trace}