docs: improve AGENTS.md for future opencode sessions

[LWWZH]

Summary

Rewrites AGENTS.md to give future Agent sessions a tighter, more accurate onboarding doc. The previous version mixed useful hard-earned context with generic style advice and a few claims that were either stale or actively wrong.

What changed

• Trimmed to ~135 lines (was 191). Removed generic JS/HTML/CSS style guidance that any agent already knows and kept the parts that are actually repo-specific.
• Fixed stale "Adding New Features" section. It told agents to put files in a js/ directory and add <script> tags to New-Tab.html. The real flow is: append the file path to scriptSources in src/core/bootstrap.js. New-Tab.html only loads storage.js and bootstrap.js; everything else is loaded dynamically with script.async = false to preserve order.
• Added the script-order constraint. app-manager.js must run before add-app-modal.js, context-menu.js, and app-folders.js (already noted in a comment inside bootstrap.js, but not in AGENTS.md).
• Documented the IIFE / window.Foo rule. Several files wrap their top-level code in a strict-mode IIFE; cross-file globals must be referenced as window.Foo, enforced by no-restricted-globals in eslint.config.js.
• Documented the test loader. tests/setup.js uses injectScript(...) which evals the real source files into the jsdom globals so the chrome.storage shim works. The DOM stub list lives in tests/setup.js — failures saying "cannot read property of null" usually mean a new stub is needed there.
• Captured CI order. npm ci --ignore-scripts → npm run lint → npm test (matches .github/workflows/release.yml).
• Removed dead reference to Sharp (no longer in package.json).
• Added the local .agents/skills/ inventory so agents know which skills to load for common tasks (release, PR, review, issue, resolve).

Why

An agent reading the old AGENTS.md would have followed bad instructions to add <script> tags to New-Tab.html, or skipped the load-order constraint and broken add-app-modal / context menu / app folders. The new doc front-loads the wiring facts (entry point, bootstrap loader, IIFE rule, storage bridge, chrome mock) before code style.

Out of scope

• No source-code, lint, or test changes.
• package.json / manifest.json versions untouched.
• .agents/skills/* untouched.

Verification

• npm run lint — unchanged files outside AGENTS.md.
• npm test — unchanged; no test files modified.
• Manual reload of the unpacked extension is unaffected.

Summary by CodeRabbit

• Documentation
  • Rewrote development guide with explicit setup prerequisites, local development commands (testing, linting, coverage), and CI/pre-commit workflow information.
  • Enhanced architecture documentation with updated conventions for extension entry points and script-loading constraints.
  • Clarified directory layout and development patterns.

[404-Page-Found]

Review Findings

1. Severity: Low — docs/ISSUES vs ISSUES mismatch in strip step description
   • The Release / Packaging section says the release workflow strips docs/ISSUES, but the actual workflow (.github/workflows/release.yml line 39) runs rm -rf .github .husky .agents tests ISSUES screenshots — it strips a top-level ISSUES/ directory, not docs/ISSUES/. Since this PR is specifically about improving documentation accuracy, this should be corrected to just ISSUES.

Verified Correct

All other factual claims in the proposed AGENTS.md checked out against the codebase:

• .nvmrc contains 22.13 ✓
• src/core/dom-ready.js exposes window.onDomReady ✓
• src/core/version.js reads version via chrome.runtime.getManifest().version ✓
• eslint.config.js uses srcGlobals and testGlobals variable names ✓
• src/core/storage.js exposes window.__storageBridgeReady ✓
• .agents/skills/ has all 5 listed skills ✓
• New-Tab.html has exactly 2 <script> tags (storage.js in head, bootstrap.js at end of body) ✓
• Release workflow runs npm ci --ignore-scripts → npm run lint → npm test ✓
• CRX built with crx3 ✓
• tests/setup.js + tests/helpers/inject-script.js use script injection into jsdom ✓
• no-console: 'off' is exclusive to background/tools/** ✓
• IIFE-wrapped files list matches ESLint config ✓

Verdict

Good rewrite — more accurate and more useful than the current version. One minor fix needed: change docs/ISSUES → ISSUES in the Release / Packaging section.

[404-Page-Found]

Address findings

[LWWZH]

Fixed in commit ef9e878: changed \docs/ISSUES\ → \ISSUES\ in the Release / Packaging section to match the actual strip list in .github/workflows/release.yml\ line 52.

Thanks for the careful read of the strip list.

[404-Page-Found]

Review: AGENTS.md rewrite (PR #337)

What I verified

I cross-referenced every factual claim in the diff against the actual codebase — bootstrap.js, eslint.config.js, vitest.config.js, storage.js, New-Tab.html, release.yml, package.json, and the skills directory. Everything checks out: script loading mechanism, IIFE list, no-restricted-globals rule, storage bridge, CI order, coverage exclusions, Sharp removal, and skill inventory are all accurate.

What needs changing before merge

1. Clarify the "no ES modules" claim in the Architecture section

"Browser code is plain scripts that attach functions to window.*. There are no ES module imports in src/."

This is true for source files, but tests in tests/ do use import/export (they are ES modules run by Vitest). An agent could interpret this to mean the entire project is script-mode and avoid import in test files too. Please add a qualifier like:

There are no ES module imports in `src/` source files (tests are ES modules).

2. Move the single-test command into the Commands table

The npx vitest run tests/todo.test.js example lives as a bullet under Testing but would be more discoverable as a row in the Commands table:

| Single test file | `npx vitest run tests/todo.test.js` |

3. Minor: mention the {{placeholder}} replacement mechanism

The doc uses {{searchPlaceholder}} as an example but never explains that New-Tab.html placeholder tokens are replaced by the i18n runtime, not by a template engine. An agent encountering {{something}} in the HTML might think it's a bug or try to fix it. A one-sentence note under the i18n convention bullet would clear that up.

What's great

• Removes ~100 lines of generic style guidance that any LLM already knows — good call.
• Fixes the stale "add <script> tag to New-Tab.html" instruction that would have broken the extension.
• Front-loads wiring facts (bootstrap, ordering, IIFE rule, storage bridge) before conventions — much better onboarding.
• Documents the test loader (injectScript) and DOM stub list — a common debugging dead end for contributors.
• Includes the .agents/skills/ inventory so agents know what tools are available.

Bottom line

Well-researched, accurate, and a clear improvement over the current version. Fix the three items above and this is ready to merge. No source code is changed so there is no risk to the extension.

[coderabbitai]

Need the big picture first? Review this PR in Change Stack to see what changed before going file by file.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 24dcc6f7-4f0d-41cb-b91b-27013b9065a6

📥 Commits

Reviewing files that changed from the base of the PR and between 4b0303e and acba25e.

📒 Files selected for processing (1)

• AGENTS.md

---

📝 Walkthrough

Walkthrough

The AGENTS.md file is rewritten to serve as a comprehensive developer guide for the new-tab extension. It replaces general project overview with explicit setup prerequisites, local commands (test, lint, coverage), and key architecture rules covering script loading, globals management, storage bridging, and service worker context. The guide updates directory layout descriptions, testing practices (Vitest/jsdom), linting configuration, code conventions, release workflow, and reference documentation pointers.

Changes

Developer Guide Restructure

Layer / File(s)	Summary
Setup, Commands & Architecture Rules AGENTS.md	New Setup and Commands section with prerequisites and local tasks; architecture constraints for entry points, script loading, plain-browser globals, storage bridging, service worker separation, and version sync policy.
Project Layout & Testing Setup AGENTS.md	Directory Layout updated with responsibility notes for src/, background/, tests/, and docs/locales; Testing section describes Vitest/jsdom setup, script injection/eval, DOM stubs, reset behavior, and coverage rules.
Development Standards & Conventions AGENTS.md	ESLint v10 flat-config and globals guidance for window.* symbols; Conventions section covers naming, DOM-ready initialization, visibility-aware intervals, localStorage fallbacks, i18n usage, branch targeting, and commit messages.
Release Process & Reference Docs AGENTS.md	Release/Packaging section updated for version-sync and CRX build/signing; Skills and Reference Docs sections streamlined to point to existing markdown documentation.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A guide is born, fresh and bright,
Setup, tests, and linting right—
Architecture rules now clear,
For developers, both far and near!
The new-tab shines with docs so neat. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title clearly and concisely describes the main change: improving AGENTS.md documentation for future agent development sessions, which aligns with the core purpose of the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[404-Page-Found]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.