sf-docs-agent 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 drsaavedra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,313 @@
-# Temporary Holding Version
+# sf-docs-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Claude Code subagent that answers Salesforce questions from the official docs and hands back quotes, not pages.
+
+It reads developer.salesforce.com, architect.salesforce.com, help.salesforce.com, admin.salesforce.com and
+lightningdesignsystem.com. The model picks the lines and a script copies them from the cached page,
+each with the official URL it came from, so you can check any quote with one grep.
+
+I built this because every docs lookup was dumping whole pages into my session. I only wanted the lines that answer my question.
+
+## Why an agent, not a skill
+
+A skill pulls every page it reads into your main session. The agent reads them in its own context and returns only
+the lines you asked for.
+
+Salesforce's own [sf-skills](https://github.com/forcedotcom/sf-skills) library already has a skill for the same job,
+[`platform-docs-get`](https://github.com/forcedotcom/sf-skills/tree/main/skills/platform-docs-get). In its own words,
+it is an "official Salesforce documentation retrieval skill" for the same five sites, "especially when pages are
+JS-heavy, shell-rendered, or hard to extract with naive fetching."
+
+Here is how the two compare:
+
+| | platform-docs-get | sf-docs-agent |
+|---|---|---|
+| Runtime | Python, `playwright`, `playwright-stealth` | Node, `playwright-core` |
+| Bot checks | spoofs a desktop user agent, optional stealth | neither |
+| developer, architect and LDS pages | renders and scrapes the HTML | reads the `.md` copy where one exists |
+| Finding pages | you give the URL | `llms.txt` indexes, sitemaps and link lists |
+| What lands in your context | every page | a report of quotes |
+| Checking an answer | re-read the page | `grep` one line |
+
+The trade-off: your main session trusts the subagent. That is why the model only picks line numbers and the script
+copies the lines. Every quote is the page's own text, never the model's memory, and you can check it with one `grep`.
+
+## 86% less in your context, 64% fewer tokens overall
+
+On 10 questions against Salesforce's own platform-docs-get skill, the agent
+added 86% fewer tokens to your context and used 64% fewer tokens over the whole session, with the right answer on
+10 of 10.
+
+Below are the measurements, each read as platform-docs-get → sf-docs.
+
+| Question | Site | Tokens added to context | Saved | Session token usage | Saved |
+|---|---|---|---|---|---|
+| 1. Scratch org editions | developer | 906 → **242** | **73.3%** | 236,882 → **86,172** | **63.6%** |
+| 2. Platform event allocation | developer | 3,120 → **471** | **84.9%** | 387,764 → **126,998** | **67.2%** |
+| 3. QueryLocator batch limits | developer | 692 → **458** | **33.8%** | 287,129 → **105,756** | **63.2%** |
+| 4. Integration patterns | architect | 1,223 → **528** | **56.8%** | 154,149 → **102,635** | **33.4%** |
+| 5. Salesforce Connect editions | help | 5,591 → **649** | **88.4%** | 477,647 → **311,396** | **34.8%** |
+| 6. Flow version limits | help | 5,940 → **293** | **95.1%** | 354,017 → **171,752** | **51.5%** |
+| 7. Headless 360 | admin | 4,247 → **341** | **92.0%** | 675,859 → **121,840** | **82.0%** |
+| 8. SLDS tooltips | lightningdesignsystem | 5,983 → **463** | **92.3%** | 360,244 → **112,618** | **68.7%** |
+| 9. Bulk API batch size | developer | 2,328 → **476** | **79.6%** | 454,224 → **91,811** | **79.8%** |
+| 10. Pub/Sub fetch limit | developer | 2,212 → **625** | **71.7%** | 448,205 → **141,343** | **68.5%** |
+| **All** | | 32,242 → **4,546** | **85.9%** | 3,836,120 → **1,372,321** | **64.2%** |
+
+<details>
+<summary>The 10 questions</summary>
+
+1. What are the valid values for edition in a scratch org definition file?
+2. What is the hourly platform event publishing allocation for Enterprise Edition and for Developer Edition?
+3. With a QueryLocator start method, what is the maximum batch scope, and how many records can the QueryLocator return?
+4. Which integration patterns does the architect Integration Patterns guide list?
+5. Which editions include the Salesforce Connect cross-org adapter?
+6. How many versions can a flow have, and how many active flows per flow type in Enterprise vs Professional?
+7. What three technologies is Salesforce Headless 360 built on, and does it replace the Lightning UI?
+8. Should you put an SLDS tooltip on a non-interactive element?
+9. How many records fit in one Bulk API batch, and in one sObject Collections create request?
+10. How many events can a Pub/Sub API client request across all FetchRequests in one Subscribe call?
+
+</details>
+
+## How sf-docs-agent reads each site
+
+The agent reads the `.md` copy of a page where the site publishes one. Not every Salesforce docs site does yet.
+
+Give the script an `.html` or bare URL for a new developer docs, architect or LDS page and it fetches the `.md` copy
+instead. The same goes for an atlas URL that now redirects to the new docs.
+
+The agent finds pages through the site's `llms.txt` index or its sitemaps.
+
+| Site | How | Where it finds pages |
+|---|---|---|
+| developer.salesforce.com, new docs | the `.md` copy Salesforce publishes | `/docs/llms.txt` and one index per product |
+| developer.salesforce.com, atlas docs (Apex, Apex Reference, Metadata API, Object Reference) | renders the page, code samples included | `/docs/llms-product-docs.txt` |
+| developer.salesforce.com, API reference pages (`?meta=<operation>`) | renders the page | the product's index |
+| architect.salesforce.com | the `.md` copy | `/llms.txt` |
+| help.salesforce.com, articles and knowledge articles | renders the page | links in other docs and articles, and Help's product sitemaps |
+| admin.salesforce.com | renders the page | `/sitemap_index.xml` and its post sitemaps |
+| lightningdesignsystem.com (SLDS 2) | the `.md` copy | the home page's link list |
+| v1.lightningdesignsystem.com (SLDS 1) | renders the page | the home page's link list |
+
+## Use
+
+Ask Claude to read the Salesforce docs in your own words. You can name the agent in the prompt, or just give it a
+Salesforce docs link and ask. It picks up the intent either way.
+
+```
+Go scan the developer.salesforce.com docs on the current release's governors and limits
+```
+
+Name the site or product if you know it, and say what you want to know.
+
+The sample prompt is broad on purpose: I wanted to see the agent decide what "governors and limits" covers, and whether it could find everything in a broad question.
+
+Here are the results of that prompt, one run each on Opus 5.5 and Sonnet 5.5 at effort high. Each session called the sf-docs agent, which returned quotes with their
+official URLs, and the session turned them into the answer.
+
+<details>
+<summary><b>Sonnet 5.5, effort high, through the agent</b>: 86 seconds, 34k agent tokens</summary>
+<br>
+
+> The `sf-docs` agent finished scanning the Apex governors and limits pages. All limit values below are quoted from the cached concept page, `apex_gov_limits.htm`. The release version is an inference, not a stated fact.
+>
+> ## Which release
+> - The cached pages are the unversioned "current" docs, and they don't name a release.
+> - The version dropdown lists **Summer '26 (API 67.0, path `262.0`)** as the newest versioned link.
+> - The page's own sidebar links point to `264.0` paths. That is most likely **Winter '27 (API 68.0)**.
+> - The agent did not fetch the 262 or 264 versioned pages to confirm.
+>
+> ## Per-transaction Apex limits
+> Limits are listed as synchronous / asynchronous.
+>
+> | Limit | Sync | Async |
+> |---|---|---|
+> | SOQL queries | 100 | 200 |
+> | SOQL rows retrieved | 50,000 | 50,000 |
+> | DML statements | 150 | 150 |
+> | DML rows | 10,000 | 10,000 |
+> | Callouts | 100 | 100 |
+> | `@future` methods per invocation | 50 | 0 in batch and future contexts, 50 in queueable |
+> | `System.enqueueJob` | 50 | 1 |
+> | Heap | 10 MB | 25 MB |
+> | CPU time | 10,000 ms | 60,000 ms |
+> | Execution time | 10 minutes | 10 minutes |
+>
+> - **Enforcement:** "the Apex runtime engine strictly enforces limits", and exceeding a limit raises a runtime exception "that can't be handled."
+> - **Reset and scope:** For Batch Apex, limits reset for each `execute` call. Synchronous limits apply to scheduled Apex. Bulk API transactions get the higher of the sync and async limits.
+> - **Heap:** Exceeding it gives an uncatchable `System.LimitException`. Email services get a 50 MB heap.
+>
+> ## Certified managed packages
+> - Each certified namespace gets its own per-transaction limits.
+> - The cumulative limit across namespaces is 11 times the per-namespace limit. That gives 1,100 SOQL queries and 1,650 DML statements.
+> - Heap, CPU, execution time and the unique-namespace count are not counted separately per package.
+>
+> ## Platform, static and size limits
+> - **Async executions per 24 hours:** 250,000, or licenses × 200, whichever is greater.
+> - **Concurrent long-running transactions (over 5 seconds):** one per 100 licenses.
+> - **Scheduled classes:** 100 (5 in Developer Edition).
+> - **Batch jobs queued or active:** 5.
+> - **Callout timeout:** 10 seconds by default.
+> - **Callout request or response size:** 6 MB synchronous, 12 MB asynchronous.
+> - **Apex code per org:** 6 MB.
+> - **Method size:** 65,535 bytecode instructions.
+> - **Single email:** 5,000 external addresses per day per org (GMT).
+> - **Push notifications:** 20,000 iOS and 10,000 Android per hour.
+> - **Governor limit email warnings:** The default threshold is 50% of allocated limits, and only per-request limits are checked.
+>
+> ## Gaps
+> - **Not fetched:** The agent did not read the "Elastic Limits for Asynchronous Apex Jobs (Beta)" page or `apex_limits_tips.htm`.
+> - **Not quoted:** Several rows on the same page weren't quoted:
+>   - push notification calls per transaction
+>   - Apex cursor limits
+>   - inbound email limits
+>   - the 450,000 `MAX_DML_ROWS` limit in tests
+> - **"Lightweight limits":** This isn't a section name in the docs.
+>
+> ## Sources
+> - https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_gov_limits.htm
+> - https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_gov_limits_emails.htm
+>
+> The pages are cached locally, so you can check any quote with `grep -c -F '<quote>' <cache path>`. The cache is under `~/.claude/sf-docs/cache/developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/`.
+>
+> I can have the agent fetch the 262 and 264 versioned pages to pin down the release, or cover the elastic limits page.
+
+</details>
+
+<details>
+<summary><b>Opus 5.5, effort high, through the agent</b>: 89 seconds, 39k agent tokens</summary>
+<br>
+
+> I read the Apex Developer Guide page **Execution Governors and Limits**. I spot-checked several of the quotes against the cached copy of the page and they match.
+>
+> **Which release:** the page doesn't name its release. Its links point to the 264.0 doc set, and its list of older versions starts at Summer '26 (API 67.0). So this is most likely **Winter '27 (API 68.0)**, but that's my inference, not something the page says. The page also doesn't mark any limit as new or changed in this release.
+>
+> ### Per-transaction Apex limits (synchronous / asynchronous)
+> | Limit | Sync | Async |
+> |---|---|---|
+> | SOQL queries | 100 | 200 |
+> | SOQL rows retrieved | 50,000 | 50,000 |
+> | `Database.getQueryLocator` rows | 10,000 | 10,000 |
+> | SOSL queries / rows per query | 20 / 2,000 | 20 / 2,000 |
+> | DML statements / rows | 150 / 10,000 | 150 / 10,000 |
+> | Trigger recursion stack depth | 16 | 16 |
+> | Callouts / cumulative callout timeout | 100 / 120 s | 100 / 120 s |
+> | `@future` calls | 50 | 0 in batch and future; 50 in queueable |
+> | `System.enqueueJob` | 50 | 1 |
+> | `sendEmail` calls | 10 | 10 |
+> | Heap | 10 MB | 25 MB |
+> | CPU time | 10,000 ms | 60,000 ms |
+> | Maximum execution time | 10 min | 10 min |
+> | `EventBus.publish` calls (publish immediately) | 150 | 150 |
+> | Apex cursor rows / `Cursor.fetch` calls | 50M / 100 | 50M / 100 |
+> | Pagination cursors: rows / instances / rows per page | 100,000 / 50 / 2,000 | same |
+>
+> **Notes that change how these apply:**
+> - **Scheduled Apex** runs under the synchronous limits.
+> - **Bulk API** transactions get the higher of the sync and async values.
+> - **Parent-child subqueries** each count as an extra query.
+> - **Custom metadata queries** don't count toward the SOQL limit.
+> - **Email services** get a 50 MB heap.
+> - **CPU time** leaves out time spent waiting on the database and on callouts.
+> - **Batch Apex** limits reset for each `execute` chunk.
+>
+> ### Org-wide Platform limits
+> - **Async executions per 24 hours:** 250,000 or 200 × licenses, whichever is greater. Batch Apex checks up front that the whole job fits under this limit before it starts.
+> - **Elastic async executions (beta)** can add up to 2 million more per day.
+> - **Cursors per 24 hours:** 10,000 cursor instances, 100M cursor rows, and 200,000 pagination cursors.
+> - **Long-running synchronous transactions (over 5 s):** 1 per 100 licenses, minimum 10 and maximum 50.
+> - **Scheduled classes:** 100 (5 in Developer Edition).
+> - **Batch Apex:**
+>   - Flex queue jobs in Holding status: 100
+>   - Jobs queued or active: 5
+>   - Concurrent `start` methods: 1
+> - **Test classes queued per 24 hours:** the greater of 500 or 10× your test classes in production (20× in sandbox and Developer Edition).
+>
+> ### Static and size limits
+> - **Callouts:** 10 s default timeout; request or response up to 6 MB sync or 12 MB async, and this counts toward heap.
+> - **SOQL run time:** 120 s.
+> - **Deployments:** 7,500 code units each.
+> - **Trigger batch size:** 200, or 2,000 for platform events and Change Data Capture.
+> - **`QueryLocator`:** 50M records.
+> - **Code size:**
+>   - 1M characters per class or trigger.
+>   - 6 MB of Apex per org (10 MB in scratch orgs). Support can raise it, and managed-package and `@isTest` code don't count.
+>   - 65,535 bytecode instructions per method.
+>
+> ### Certified managed packages
+> - Each certified namespace gets its own copy of the per-transaction limits.
+> - The total across namespaces is capped at 11× the per-namespace limit: for example, 1,100 SOQL queries or 1,650 DML statements.
+> - Heap, CPU time, execution time and the number of namespaces are shared across the whole transaction.
+> - Code in non-certified packages counts against your org's own limits.
+>
+> ### Other limits on the page
+> - **Single email:** 5,000 external addresses per day and 150 recipients per message.
+> - **Push notifications:** 20,000 iOS and 10,000 Android per hour per org.
+> - **Tests:** 450,000 DML rows per synchronous test run.
+> - **ConnectApi:** each write costs one DML statement.
+> - **Data.com Clean:** 200 SOQL queries and 10 future calls per batch.
+>
+> **Not covered:** I didn't read the Asynchronous Callout Limits page or the Winter '27 release notes. If you need to know what changed since Summer '26, the release notes are the next place to look.
+>
+> **Source:** https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_gov_limits.htm
+
+</details>
+
+## Install
+
+User scope:
+```
+npx sf-docs-agent            # for all your projects
+```
+Project scope:
+```
+npx sf-docs-agent --project  # for the project in the current folder only
+```
+
+Needs Node 18.17+ and Claude Code. The installer adds `playwright-core` (8.5 MB). It also needs a headless Chromium
+(about 180 MB). On Linux, also run `npx playwright-core install-deps chromium` once.
+
+To update, run it again. To remove it, delete `~/.claude/agents/sf-docs.md` (or `.claude/agents/sf-docs.md`
+in the project) and `~/.claude/sf-docs/`. If `CLAUDE_CONFIG_DIR` is set, the installer uses that instead of
+`~/.claude`.
+
+Pages stay cached for 24 hours, so a follow-up question does not fetch them again. To change that, set `SF_DOCS_CACHE_HOURS` in your Claude Code `settings.json`
+(`0` fetches every time):
+
+```json
+{ "env": { "SF_DOCS_CACHE_HOURS": "72" } }
+```
+
+## Limitations
+
+- On help, admin, SLDS 1, API reference pages and the atlas guides, the agent finds the article text by where it sits on
+  the page. If Salesforce changes a layout, it reads the largest block of text instead, which can be one section of the
+  article, and an article under 1,500 characters can't be read. A daily check in this repo flags the change.
+- A rendered page can take up to 80 seconds before the agent gives up on it (45 s to load, 20 s for content, 15 s for the
+  `.md` copy of a page it redirected to).
+- No Help search. Help's `robots.txt` disallows it. Help's sitemaps list article ids but not titles.
+- It reads the current docs, which don't always name their release.
+- It follows at most one link from a page it read. An answer that sits further away comes back as a gap.
+- If a site starts blocking headless browsers, the agent stops and reports it. It does not try to get around the block.
+- What leaves your machine: the pages the agent fetches from those sites (and each site's `robots.txt`, which raw
+  fetches load first). No telemetry. Installing downloads `playwright-core` from npm and, if you agree, Chromium from
+  Playwright's servers.
+- The agent has Bash. Its brief limits it to the script and the cache, but that is an instruction to the model, not a
+  sandbox.
+
+## Develop
+
+```
+git clone https://github.com/drsaavedra/sf-docs-agent && cd sf-docs-agent && npm install
+mkdir -p "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents"
+sed "s|/path/to/sf-docs-agent|$PWD|g" agents/sf-docs.md > "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents/sf-docs.md"
+npm test
+```
+
+`agents/sf-docs.md` names its script and cache as `/path/to/sf-docs-agent`. The `sed` line writes your copy with your
+clone's path; the installer does the same for everyone else. Run it again after you edit the agent.
+
+## License
+
+MIT

package/agents/sf-docs.md

@@ -0,0 +1,155 @@
+---
+name: sf-docs
+description: Answers a question from official Salesforce docs (developer, architect, help, admin and lightningdesignsystem.com) with verbatim quotes the script copies from the cached page, each tied to its official URL and line. Use it proactively whenever the user wants something read, scanned, checked or looked up in Salesforce documentation, even without naming this agent ("what does Help say about X", "check the Apex guide for Y", "scan the docs on Z"), and when you do not know which page holds the answer. Brief it with the question, the site or product if known, and the width ("the one concept page" or "the whole doc set"). Delegate even for one page you already know, with its URL in the brief: a page is thousands of tokens in your context and the agent's report is about 400. A URL on one of those sites in the question is for this agent too; do not WebFetch or curl it, those get a 403 or an empty JavaScript shell. Show the user its Answer and Sources. To check a quote, run `grep -c -F '<quote>' <cache path>`. Reads docs only. Not for org state.
+model: claude-sonnet-5-5
+tools: Bash, Read
+---
+
+## Role
+
+You read official Salesforce docs and report what they say, quoted. You do not infer support from silence and
+you do not fill gaps from memory. If the docs do not say it, the answer is "not found", with the pages you checked.
+
+## The sites
+
+| Site | How pages are read | Where to find pages |
+|---|---|---|
+| developer.salesforce.com, new docs (`/docs/platform/...` and other paths in a per-product index) | `.md` twin, fetched raw | `developer.salesforce.com/docs/llms.txt` lists one `/docs/llms-<product>.txt` per product (see Find for the two that terms can miss) |
+| developer.salesforce.com, atlas docs (`/docs/atlas.en-us.*`: Apex Developer Guide, Metadata API, Object Reference and more) | `.htm` page, rendered. There is no `.md` twin, but an atlas URL that redirects to new docs is read as the new page's `.md` (`[twin ...]` in the output) | `developer.salesforce.com/docs/llms-product-docs.txt` (3 MB, 19,000+ `.htm` links) |
+| architect.salesforce.com | `.md`, fetched raw | `https://architect.salesforce.com/llms.txt` |
+| help.salesforce.com | rendered, about 10 s a page | `'https://help.salesforce.com/s/articleView?id=<id>.htm&type=5'`. With an id from the brief, a doc, or a fetched Help page's `.links.txt` (`/apex/HTViewHelpDoc?id=<id>.htm` lines; knowledge articles are `?id=<number>&type=1`), fetch it. With no id, use the sitemaps: fetch `'https://help.salesforce.com/apex/Help_SiteMapIndexExternal?producttype=<platform|service|xcloud|sales|ai|data|experience|analytics|mktg|commerce|cc|ind|sfdo|slack|release-notes>'` with `--terms`; an index prints every page sitemap it lists, whatever the terms (46 for platform). Fetch those 20 a call with `--terms '<word_word>'`. A sitemap line is a URL with no title, so only the id form matches: words joined by `_`, as specific as the question (`salesforce_connect_xorg`, not `external_object`). Each match prints the article's `<loc>` line, up to 40 a page. A child article that is not among them is one hop away through the fetched article's `.links.txt`. Do not use Help search: robots.txt disallows `/s/search-result` |
+| admin.salesforce.com | rendered | `admin.salesforce.com/sitemap_index.xml` lists the post sitemaps (`/post-sitemap.xml`, `/post-sitemap2.xml` ...); fetch them all in one call with `--terms` and use the matching `<loc>` URLs. `/blog` shows only the latest 3 posts |
+| lightningdesignsystem.com | `.md` twin, fetched raw (the home page itself is rendered) | the `.links.txt` of the home page, as `/2e1ef8501/p/<id>-<slug>` |
+| v1.lightningdesignsystem.com (SLDS 1, still used by orgs not on SLDS 2) | rendered | the `.links.txt` of `https://v1.lightningdesignsystem.com/`, as `/components/<name>/` and `/utilities/<name>/` |
+
+## The script
+
+```
+node "/path/to/sf-docs-agent/fetch-docs.mjs" <url> [<url> ...]
+```
+
+Each argument is a URL on one of the sites above (`https://` may be left off). Always write the host: a bare
+`/docs/...` path means developer.salesforce.com, but Git Bash on Windows rewrites a leading `/` into a Windows path.
+Quote any URL that holds `?` or `&`. Pass many URLs in one call: it opens one browser.
+Pass `--budget 480` on every fetch and `timeout: 600000` on its Bash call. The script starts no page after 480 s and
+prints `not fetched (time limit) <url>` for each one left: rerun only those URLs. A call that passes the Bash limit is
+moved to the background and you lose its output, though every page it printed is cached. Up to 20 URLs a call; past
+that, the printed output is the limit, not time.
+
+- A `.md`, `.txt` or `.xml` URL is fetched raw. A new developer docs, architect or LDS page given as `.html` or a bare
+  path is fetched as its `.md` twin, and rendered only if the twin is missing. Any other URL is rendered and its main content saved as `.txt`; the page's
+  same-site links go to a sidecar `<file>.links.txt`.
+- One line per URL: `<status> <chars> <url> [<selector>] -> <file>`, with `<file>` relative to the cache dir.
+  `duplicate-of <url>` means the body matches an earlier URL: read only the first copy. `same <url> as <url>` means
+  two arguments are one page, fetched once. `(cached)` means it came from disk. Status `0` carries the error.
+  `[redirected <url>]` means the page moved and the Source line names where: check that it is the page you asked for,
+  since a mistyped atlas topic redirects to its guide's landing page, which is not evidence. That rule also decides a
+  line that adds `[twin <path>]` (the redirected page read as its `.md`) or `[twin failed: <reason>]` (its rendered
+  text kept); a cached run shows `(cached) [redirected <url>]` and no `[twin]`. `not saved` means a shell, login wall or missing page (Help
+  answers 200 for a missing article), or `[api docs did not load]` on an API reference page: not evidence, but a rerun
+  may work. `not saved: <code>` means the page loaded but the cache write failed: rerun. `not saved: left the doc
+  sites` means the page redirected to another domain, and `refused <url>` means the URL is not on the sites above:
+  neither is evidence. `[fallback]` means the page's layout was not recognised and the text is the largest block on
+  it, which can be one section of the article: quote it, but name the page in Gaps if the answer is not there.
+- `--terms 'a,b'` (comma-separated, any case) prints, after the per-URL lines, each saved page's lines that hold a
+  term, numbered, under `== <file>`, then the matching lines of its `.links.txt`. Past 20 lines (10 for links), those with
+  the rarest terms win: add a term to narrow. A page of up to 40 lines and 4,000 chars prints whole,
+  marked `(short page, shown whole)`: read it all before saying it lacks something. To search a page you already have for other terms, fetch it again with them; it comes from the cache.
+  `--search 'a,b'` [`--site <host>`] prints the same ranked lines across every cached page except indexes and
+  sitemaps, at most 3 a file, with the file.
+- Never pass `--out`. The cache dir every run shares is
+  `"/path/to/sf-docs-agent/cache"`, and a page written there within the
+  cache window (24 h unless `SF_DOCS_CACHE_HOURS` says otherwise) is served from disk. Each fetch run first deletes
+  pages older than the window.
+
+## The route
+
+Every tool call costs you the whole conversation again, so use as few Bash calls as the route needs and keep Reads small.
+
+1. **Find.** developer.salesforce.com has two levels. Fetch `developer.salesforce.com/docs/llms.txt
+   developer.salesforce.com/docs/llms-product-docs.txt` with
+   `--terms '<product words>'`: the matching `llms.txt` line names the product index (`/docs/llms-<product>.txt`),
+   and `llms-product-docs.txt` lines are atlas pages (Apex, Metadata API, Object Reference and more). Two product
+   indexes are easy to miss there: the Platform line has no topic words, and it holds the REST, SOAP and Bulk APIs,
+   SOQL and SOSL, Platform Events, Streaming, Change Data Capture and the app limits
+   (`developer.salesforce.com/docs/llms-platform.txt`); the Salesforce DX line names VS Code and the CLI but not
+   scratch orgs or Salesforce DX (`developer.salesforce.com/docs/llms-salesforcedx.txt`).
+   Then fetch the product index with `--terms '<topic words>'`. Take
+   index paths from those lines or this list, never from memory: a guessed `/docs/llms-<name>.txt` is a 404. Other
+   sites: the table's index. When the cache may already hold the page, add
+   `&& node "/path/to/sf-docs-agent/fetch-docs.mjs" --search '<a phrase the answer page would contain>'` (it skips indexes). Fetch comes
+   first because it clears expired pages. Never Read an index: `/docs/llms.txt` is about 4k tokens and
+   `llms-product-docs.txt` about 780k. Do not guess paths from the site sidebar. A cache hit counts only if its path is
+   under the site and product the brief names.
+2. **Fetch and locate.** Fetch the pages you picked with `--terms`. On Help or LDS, the `.links.txt` matches name the
+   next page.
+3. **Look.** To see the lines around a match, use Read with `offset` and `limit`, or `grep -n -C3 -e '<term>' <file>`:
+   both number lines as `--quote` counts them. `sed -n` and `head` do not, so never take a line number from them.
+   Never read a page whole.
+4. **One hop.** If a matched line, a `.links.txt` match or a sentence you will quote names another page that holds
+   part of the answer (a child article, a "Limitations for ..." heading with no text under it, an index entry whose
+   title matches the question, another post), fetch it now with `--terms`. One hop only: a page named by that page
+   stays a Gap. A parent Help article often lists no editions or permissions, and its child article does.
+5. **Quote.** Pick the line numbers that carry the answer, from the matches or the Read. Then let the script copy them:
+   `node "/path/to/sf-docs-agent/fetch-docs.mjs" --quote <cache file>:<line>,<line> [<cache file>:<line> ...]`
+   (cache file relative to the cache dir or absolute). It prints the Evidence and Sources blocks verbatim, with the
+   official URL from each file's first line. Never type a quote yourself.
+
+## Hard limits
+
+- Run the script as written. Do not add a stealth plugin, a spoofed user agent or any other bot-check bypass:
+  plain headless Chromium gets 200 today. If the site answers 403 or a challenge page, stop and report
+  `BLOCKED: <status>`; do not try another route. WebFetch and curl get 403 and are not routes.
+- If the script prints a `BLOCKED:` line, or Node cannot find `playwright-core`, stop and report the error lines as
+  printed (after `BLOCKED:` they include the install command). Do not install anything yourself.
+- Bash is for running the script and reading the cache dir. Write nothing anywhere else.
+- Run every command in the foreground and wait for it. Never run one in the background or wait on a monitor: your
+  last message is the report, so a run that ends while a fetch is still going returns no answer.
+- Only the sites above: the script refuses any other host. A third-party blog or forum is never evidence, even when a
+  doc links to it.
+
+## Reading discipline
+
+- Go to the exact concept page. A landing, overview or index page that only links onward is not evidence. The
+  caller's width ("the one concept page") still allows the child pages that hold what the question asks for.
+- Quote verbatim. Carry every option an enumerating sentence lists, and quote any sentence that limits the scope
+  of the one you rely on ("X is intended only for Y").
+- Two lines that disagree, on two pages or on one: quote both, name the files, do not pick one.
+- Absence is not "unsupported". Say "not found" only for pages you searched or read, and list them.
+- An example is not a schema: say when a list of fields or values comes only from a sample request.
+- Note Beta, Pilot or Developer Preview labels when a page carries one.
+
+## Before you write
+
+Check the draft against the page, then write. Each check is one grep or one look at output you already have.
+
+1. Title against quote. The page title is the `title:` line in the frontmatter on an LDS page, otherwise the first `# ` line. If a quote names a release, version or
+   date that contradicts one in the title, or the title names a different product than the brief, that is a conflict: run --quote again with the title line
+   added, and name it in Gaps. "Gaps: none" is wrong while this check is open. With no such conflict, do not quote the
+   title or a section heading.
+2. Every value in the Answer. Each number, name and option the question asks for is in the Answer, not only
+   in Evidence or Gaps. A scan question gets one Answer sentence per item it asks for.
+3. A conflict is two statements about the same quantity on the same subject. Two different limits that share
+   a number are not a conflict.
+4. A quote that states the fact settles it. Do not add a Gap that doubts a quote you chose, unless another quote contradicts it.
+
+## Output
+
+The caller reads this, then shows the user the Answer and the Sources. Return exactly this shape, then stop. Do not
+keep exploring once the brief is answered.
+
+```
+Answer: <one to three plain sentences, or one per item for a scan, that state the values or facts themselves, not where they are. Every claim must be carried by a quote below>
+<the Evidence and Sources blocks exactly as --quote printed them>
+Gaps: <conflicts (between pages or on one page), and what you looked for and did not find, with the pages checked; or "none">
+Strength: strong | weak (<why>). Pages fetched N, cached c, read r.
+```
+
+- Quote only the lines that carry the Answer, and the title line when check 1 names a conflict. More detail stays on the page the Source links to.
+- Gaps holds at most three lines, and only what limits the Answer: a conflict, something unconfirmed, something
+  not found. Do not list what you chose not to quote.
+- Paste the --quote output unchanged. Do not reformat, renumber, add or remove quotes. To drop a quote, run
+  --quote again without its line.
+
+**strong** means a quote on the exact concept page states the answer. **weak** means the answer comes from an
+example, an index or landing page, a Beta, Pilot or Developer Preview page, or needs two quotes joined.

package/bin/install.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// npx sf-docs-agent [--project] [--yes]: install the sf-docs subagent for Claude Code.
+// The runtime (script, playwright-core, cache home) is always user-level; only the agent file follows the scope.
+import { cpSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync, execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+
+const pkg = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const config = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+const project = process.argv.includes('--project');
+const runtime = join(config, 'sf-docs');
+const agents = project ? resolve('.claude', 'agents') : join(config, 'agents');
+
+mkdirSync(runtime, { recursive: true });
+cpSync(join(pkg, 'fetch-docs.mjs'), join(runtime, 'fetch-docs.mjs'));
+// A devDependency: npx would otherwise download playwright-core once for the installer and again for the runtime.
+const version = JSON.parse(readFileSync(join(pkg, 'package.json'), 'utf8')).devDependencies['playwright-core'];
+writeFileSync(join(runtime, 'package.json'),
+  JSON.stringify({ private: true, type: 'module', dependencies: { 'playwright-core': version } }, null, 2) + '\n');
+console.log(`Installing playwright-core ${version} in ${runtime}`);
+// A shell command string: on Windows npm is npm.cmd, which Node only spawns through a shell (CVE-2024-27980),
+// and args alongside shell: true are deprecated (DEP0190). The args are constants, so nothing needs quoting.
+try {
+  execSync('npm install --no-audit --no-fund --loglevel=error', { cwd: runtime, stdio: 'inherit' });
+} catch {
+  // npm has already printed why; the agent is not installed yet, so a rerun starts clean.
+  console.error('\nnpm install failed (see above). The agent was not installed. Run the same command again once npm works.');
+  process.exit(1);
+}
+// The browser is the one large download, so it is never fetched without consent: ask at a terminal, take --yes in
+// scripts, and otherwise print the command. If Chromium is missing at first use, the agent reports BLOCKED.
+const cli = join(runtime, 'node_modules/playwright-core/cli.js');
+let present = false;
+try {
+  const { chromium } = await import(pathToFileURL(join(runtime, 'node_modules/playwright-core/index.mjs')).href);
+  await (await chromium.launch({ headless: true })).close();
+  present = true;
+} catch { /* launch failing is the signal that the browser is missing */ }
+const ask = async q => {
+  if (!process.stdin.isTTY) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const a = await rl.question(q).catch(() => ''); // Ctrl+D or closed input means no
+  rl.close();
+  return /^y(es)?$/i.test(a.trim());
+};
+if (present) console.log('Headless Chromium is already installed.');
+else if (process.argv.includes('--yes') || await ask('Download headless Chromium (about 180 MB)? [y/N] ')) {
+  try { execFileSync(process.execPath, [cli, 'install', '--only-shell', 'chromium'], { stdio: 'inherit' }); }
+  catch { console.error(`\nBrowser download failed (see above). Retry later with:\n  node "${cli}" install --only-shell chromium`); }
+} else console.log(`Skipped the browser download. Before first use, run:\n  node "${cli}" install --only-shell chromium`);
+
+// Point the agent at the installed script. rm first: a symlinked agent file would otherwise be written through.
+// The source names its own checkout dir (script and cache); swap every occurrence for the runtime dir.
+const source = readFileSync(join(pkg, 'agents/sf-docs.md'), 'utf8');
+const devDir = source.match(/node "([^"]+)\/fetch-docs\.mjs"/)[1];
+// Forward slashes: the agent runs these paths in Git Bash on Windows, where a backslash is an escape. A function
+// replacement, so a $ in the path is taken literally.
+const agent = source.replaceAll(devDir, () => runtime.replaceAll('\\', '/'));
+mkdirSync(agents, { recursive: true });
+rmSync(join(agents, 'sf-docs.md'), { force: true });
+writeFileSync(join(agents, 'sf-docs.md'), agent);
+console.log(`Installed agent: ${join(agents, 'sf-docs.md')}\nUse subagent_type "sf-docs". If it is not listed yet, start a new Claude Code session.`);

package/fetch-docs.mjs

@@ -0,0 +1,488 @@
+#!/usr/bin/env node
+// Fetch Salesforce doc pages through headless Chromium and write each unique body to disk.
+// .md/.txt/.xml URLs, Help sitemaps and the .md twins of new docs, architect and LDS pages are fetched raw; any other
+// URL is rendered and its main content extracted as text.
+// Usage: node fetch-docs.mjs [--out <dir>] [--budget <s>] [--terms a,b] <url | /docs/path.md> ...   (default out: ./cache here)
+//        node fetch-docs.mjs --search a,b [--site <host>]   (ranked matching lines across the cached pages)
+//        node fetch-docs.mjs --quote <cache file>:<line>[,<line>...] ...   (prints Evidence and Sources verbatim)
+import { chromium } from 'playwright-core';
+import { createHash } from 'node:crypto';
+import { closeSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// First selector with real text wins, so a wrapper of several topics (atlas nested0 or nested1, Help KB blocks)
+// ranks above one topic; doc-amf-reference and doc-content serve pages whose text is all in shadow DOM.
+const CONTENT = ['.slds-text-longform', 'div.container:has(.article-content)', '.post.entry', 'div.nested0',
+  'div.container:has(> div.nested1)', 'div.body', 'doc-amf-reference', 'doc-content', 'article', 'main'];
+
+const args = process.argv.slice(2);
+let out = join(dirname(fileURLToPath(import.meta.url)), 'cache');
+const oi = args.indexOf('--out');
+if (oi >= 0) out = args.splice(oi, 2)[1];
+// No page starts after the budget: each one left is printed 'not fetched (time limit)', so the caller can rerun it.
+const bi = args.indexOf('--budget');
+const deadline = bi >= 0 ? Date.now() + Number(args.splice(bi, 2)[1]) * 1000 : Infinity;
+// --terms a,b: after the fetch, print each saved page's lines that hold a term, so the caller needs no grep.
+const termsOf = v => (v ?? '').split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+const ti = args.indexOf('--terms');
+const terms = ti >= 0 ? termsOf(args.splice(ti, 2)[1]) : [];
+if (!args.length || !out || Number.isNaN(deadline) || (ti >= 0 && !terms.length)) { console.error('usage: node fetch-docs.mjs [--out dir] [--budget seconds] [--terms a,b] <url | /docs/path.md> ...\n       node fetch-docs.mjs [--out dir] --search a,b [--site <host>]\n       node fetch-docs.mjs [--out dir] --quote <cache file>:<line>[,<line>...] ...'); process.exit(2); }
+const fileFor = u => join(out, u.host, (u.pathname + u.search.replace(/[^\w.-]+/g, '_')).replace(/\/$/, '/index') + (/\.(md|txt|xml)$/.test(u.pathname) ? '' : '.txt'));
+// Cache window: SF_DOCS_CACHE_HOURS (default 24; 0 means always fetch). An empty value counts as unset.
+const hours = Number(process.env.SF_DOCS_CACHE_HOURS || 24);
+const MAX_AGE = (Number.isFinite(hours) && hours >= 0 ? hours : 24) * 3600 * 1000;
+// Never delete a page younger than 10 minutes: a short window would otherwise remove pages another run, or this
+// agent's own previous step, fetched moments ago. Serving still follows MAX_AGE.
+const PRUNE_AGE = Math.max(MAX_AGE, 10 * 60 * 1000);
+// A raw fetch that hangs (Help sitemaps do) would otherwise stall the whole call past the caller's tool timeout.
+const RAW_TIMEOUT_MS = 30000;
+// A file from before the Source: line existed is stale, so --quote can always name the official page. Only the first
+// 8 bytes are read, once per URL per run: indexes run to megabytes.
+const fresh = new Map();
+const isFresh = u => {
+  if (!fresh.has(u.href)) {
+    let ok = false;
+    try {
+      if (Date.now() - statSync(fileFor(u)).mtimeMs < MAX_AGE) {
+        const fd = openSync(fileFor(u), 'r'), b = Buffer.alloc(8);
+        try { readSync(fd, b, 0, 8, 0); } finally { closeSync(fd); }
+        // A fallback read may be one section or a sidebar of a slow page: refetch it rather than trust it for a day.
+        ok = b.toString() === 'Source: ' && !statSync(`${fileFor(u)}.fallback`, { throwIfNoEntry: false });
+      }
+    } catch { /* missing or unreadable: not fresh */ }
+    fresh.set(u.href, ok);
+  }
+  return fresh.get(u.href);
+};
+// A twin that answered 404 or a shell leaves an empty <file>.missing, so later runs render without asking again;
+// a transient failure (status 0, 5xx) leaves none and the twin is retried.
+const noTwin = t => { try { return Date.now() - statSync(`${fileFor(t)}.missing`).mtimeMs < MAX_AGE; } catch { return false; } };
+// Failing to write a marker only costs a retry later, so it is reported and the run goes on.
+const markMissing = t => {
+  const f = `${fileFor(t)}.missing`;
+  try { mkdirSync(dirname(f), { recursive: true }); writeFileSync(f, ''); }
+  catch (e) { console.error(`could not record missing twin ${slash(f)}: ${e.message}`); }
+};
+// The page a person would open: developer serves .md twins at .html, architect at the bare path.
+const official = u => !u.pathname.endsWith('.md') ? u.href
+  : u.href.replace(/\.md$/, u.host === 'developer.salesforce.com' ? '.html' : '');
+const SOURCE = /^Source: [^\n]*\n/;
+// An HTML app shell where text was expected (a .md path with no twin answers 200 with one).
+const isShell = b => /^\s*<(!doctype|html)/i.test(b);
+// A twin is missing (render instead, and remember it) on a 404, or a 200 whose body is an HTML shell or empty.
+const missingTwin = (status, body) => status === 404 || (status === 200 && (isShell(body) || !body.trim()));
+// One page, whatever the #anchor or trailing slash; a Help article is told apart by its ?id=.
+const sameDoc = (a, b) => a.origin === b.origin && a.pathname.replace(/\/$/, '') === b.pathname.replace(/\/$/, '')
+  && a.searchParams.get('id') === b.searchParams.get('id');
+// Paths the agent will paste into Git Bash on Windows: forward slashes, which Node accepts too.
+const slash = p => p.split(sep).join('/');
+
+// --terms and --search: lines holding a term, numbered as --quote counts them; past a cap the rarest-term lines win, in
+// page order. Caps set on a clean 20-question sample (looser caps printed twice the old grep's 2k chars a call).
+const MAX_HITS = 20, MAX_LINKS = 10, SHORT_LINES = 40, SHORT_CHARS = 4000, PER_FILE = 3;
+const matches = (name, text, t) => text.split('\n').flatMap((line, i, ls) => {
+  const low = i || !ls[0].startsWith('Source: ') ? line.toLowerCase() : '', hit = t.filter(s => low.includes(s)); // a page's line 1 is its Source line; a sidecar has none
+  return hit.length ? [{ name, n: i + 1, line, hit, at: Math.min(...hit.map(s => low.indexOf(s))) }] : [];
+});
+const rank = (ms, max = MAX_HITS) => {
+  if (ms.length <= max) return ms;
+  const df = Object.create(null); // a term like 'constructor' must not read Object.prototype
+  for (const m of ms) for (const s of m.hit) df[s] = (df[s] || 0) + 1;
+  const score = m => m.hit.reduce((a, s) => a + 1 / df[s], 0);
+  return ms.map((m, k) => [score(m), k, m]).sort((a, b) => b[0] - a[0] || a[1] - b[1]).slice(0, max)
+    .sort((a, b) => a[1] - b[1]).map(x => x[2]);
+};
+const show = m => `${m.n}: ${m.line.length > 300 ? `...${m.line.slice(Math.max(0, m.at - 100), m.at + 200)}...` : m.line}`;
+const more = (all, top) => all.length > top.length ? [`(${all.length - top.length} more lower-ranked lines: add a term to narrow)`] : [];
+// A page this short is printed whole: its answer can sit on a line no term matches (a Help page's "95%" line).
+// Index files by shape (Help's /apex/Help_*SiteMap* pages, *sitemap*.xml), on the path under the cache dir: a doc
+// page about sitemaps, or an --out dir named for them, is neither.
+const indexKind = rel => /(^|\/)apex\/Help_\w*SiteMapIndex|sitemap_index[^/]*\.xml$/i.test(rel) ? 'index'
+  : /(^|\/)apex\/Help_\w*SiteMap|[^/]*sitemap[^/]*\.xml$/i.test(rel) ? 'map' : '';
+const grep = (file, t) => {
+  const text = readFileSync(file, 'utf8'), lines = text.split('\n'), kind = indexKind(slash(relative(out, file)));
+  if (!file.endsWith('.links.txt') && lines.length <= SHORT_LINES && text.length <= SHORT_CHARS)
+    return ['(short page, shown whole)', ...lines.slice(1, text.endsWith('\n') ? -1 : undefined).map((l, i) => `${i + 2}: ${l}`)]; // line 1 is the Source line
+  // A sitemap index names page sitemaps, not topics, so no term can pick among them: print every <loc> line.
+  if (kind === 'index') return matches(null, text, ['<loc>']).map(show);
+  // A sitemap lists each article twice (<loc> and its alternates): keep the <loc> line and show 40 articles.
+  const map = kind === 'map', all = matches(null, text, t).filter(m => !map || m.line.includes('<loc>'));
+  const top = rank(all, map ? 40 : file.endsWith('.links.txt') ? MAX_LINKS : MAX_HITS);
+  return [...top.map(show), ...more(all, top)];
+};
+
+// --quote: the agent picks line numbers, the script copies the lines, so quotes are verbatim by construction.
+if (args[0] === '--quote') {
+  const files = [], ev = [];
+  for (const spec of args.slice(1)) {
+    const at = spec.lastIndexOf(':');
+    const file = isAbsolute(spec.slice(0, at)) ? spec.slice(0, at) : join(out, spec.slice(0, at));
+    // Only cached official pages: inside the cache dir and starting with their Source: line.
+    const inside = relative(out, file);
+    let lines;
+    try { lines = inside.startsWith('..') || isAbsolute(inside) ? [] : readFileSync(file, 'utf8').split('\n'); }
+    catch { lines = []; }
+    if (!lines[0]?.startsWith('Source: ')) { console.error(`not a cached page: ${slash(file)}`); continue; }
+    if (!files.includes(file)) files.push(file);
+    for (const n of spec.slice(at + 1).split(',').map(Number)) {
+      const text = (lines[n - 1] || '').trim();
+      if (text && n > 1) ev.push(`- "${text}" [${files.indexOf(file) + 1}:${n}]`);
+      else console.error(`skipped ${slash(relative(out, file))}:${n}: empty, out of range or the Source line`);
+    }
+  }
+  console.log(['Evidence:', ...ev, 'Sources:', ...files.map((f, i) => {
+    const src = (readFileSync(f, 'utf8').match(SOURCE) || ['Source: (unknown) '])[0].slice(8).trim();
+    return `[${i + 1}] ${src}\n    cache: ${slash(f)}`;
+  })].join('\n'));
+  process.exit(ev.length ? 0 : 1);
+}
+
+// The official doc sites: the only hosts fetched, saved or pruned, so every cached page and quote is Salesforce's own.
+const SITES = ['developer.salesforce.com', 'architect.salesforce.com', 'help.salesforce.com', 'admin.salesforce.com',
+  'www.lightningdesignsystem.com', 'v1.lightningdesignsystem.com'];
+// Every file under the given site folders, sorted. A missing folder is a site not cached yet; any other error is printed.
+const cacheFiles = (sites, label) => sites.flatMap(s => {
+  try { return readdirSync(join(out, s), { recursive: true }).sort().map(rel => join(out, s, rel)); }
+  catch (e) { if (e.code !== 'ENOENT') console.error(`${label}: ${e.message}`); return []; }
+});
+
+// --search: ranked lines across the cache, at most PER_FILE a file. It does not fetch, so it can see expired pages:
+// fetch first in a run, which clears them.
+if (args[0] === '--search') {
+  const t = termsOf(args[1]?.startsWith('-') ? '' : args[1]);
+  const si = args.indexOf('--site'), site = (si >= 0 ? args[si + 1] || '' : '').replace(/^lightningdesignsystem\.com$/, 'www.$&');
+  // --site with no value is an error, not a search of every site.
+  if (!t.length || (si >= 0 && !SITES.includes(site))) { console.error(`usage: --search a,b [--site <one of ${SITES.join(', ')}>]`); process.exit(2); }
+  const all = [];
+  let total = 0;
+  for (const f of cacheFiles(site ? [site] : SITES, 'search')) {
+    const rel = slash(relative(out, f));
+    // Sidecars and markers are not pages; a file another run pruned mid-walk is skipped.
+    if (/\.(links\.txt|missing|tmp|fallback)$/.test(rel) || !statSync(f, { throwIfNoEntry: false })?.isFile()) continue;
+    if (/(^|\/)llms[^/]*\.txt$/i.test(rel) || indexKind(rel)) continue; // indexes: --terms on the index already shows them
+    // At most PER_FILE lines a file, so ties across files cannot all come from the one that sorts first.
+    try { const ms = matches(rel, readFileSync(f, 'utf8'), t); total += ms.length; all.push(...rank(ms, PER_FILE)); }
+    catch (e) { if (e.code !== 'ENOENT') throw e; }
+  }
+  const top = rank(all), rest = total - top.length;
+  console.log([...top.map(m => `${m.name}:${show(m)}`), ...(rest ? [`(${rest} more lower-ranked lines: add a term or --site to narrow)`] : [])].join('\n') || `no match in ${site || 'the cache'}`);
+  process.exit(0);
+}
+// A scheme-less host would resolve as a developer.salesforce.com path; sitemap <loc> lines write & as &#38; or &amp;.
+// Anything that is not an http(s) URL (a stray flag, 'https://', ftp:) is refused rather than crashing the call.
+const parse = a => {
+  const s = a.replace(/&(#38|amp);/g, '&'), v = /^([\w-]+\.)*(salesforce|lightningdesignsystem)\.com([/?]|$)/i.test(s) ? `https://${s}` : s;
+  if (s.startsWith('-') || !URL.canParse(v, 'https://developer.salesforce.com')) return null;
+  const u = new URL(v, 'https://developer.salesforce.com');
+  // lightningdesignsystem.com serves the same site as www., which the twin route and the cache prune expect.
+  if (u.hostname === 'lightningdesignsystem.com') u.hostname = 'www.lightningdesignsystem.com';
+  return /^https?:$/.test(u.protocol) ? u : null;
+};
+// One pass over the arguments: a URL on a doc site is fetched, anything else is refused with its reason.
+const given = [], refused = [];
+for (const a of args) {
+  const u = parse(a);
+  if (u && SITES.includes(u.host)) given.push(u);
+  else refused.push(u ? `${u.href}: not an official doc site` : `${a}: not a URL`);
+}
+// New developer docs, architect and LDS pages have a .md twin: fetch it raw rather than render the HTML page.
+const twinOf = u => {
+  const p = u.pathname.replace(/\.html$/, '').replace(/\/$/, '');
+  const has = !u.search && !/\.(md|txt|xml|htm)$/.test(p) && (
+    u.host === 'developer.salesforce.com' ? /^\/docs\/(?!atlas\.|component-library\/)[^/]+\/[^/]+\/[^/]+\/./.test(p)
+      : u.host === 'architect.salesforce.com' ? /^\/docs\/architect\/./.test(p)
+        : u.host === 'www.lightningdesignsystem.com' && /^\/\w+\/(v\/\d+\/)?p\/./.test(p));
+  return has ? new URL(`${u.origin}${p}.md`) : null;
+};
+const asked = new Map(); // twin href -> URL as given, rendered instead when the twin is missing
+// foo.html and foo are one page (one twin): fetch it once, and print 'same <arg> as <first arg>' for the others.
+const urls = [], sameAs = [], first = new Map();
+for (const u of given) {
+  const t = twinOf(u), k = t ? t.href : u.href;
+  // A .md given before its page: this page becomes the fallback (or is rendered now, if the twin is known missing).
+  const mdFirst = t && !asked.has(t.href) && urls.some(x => x.href === t.href);
+  if (mdFirst && noTwin(t)) { urls.push(u); continue; }
+  if (mdFirst) asked.set(t.href, u);
+  if (first.has(k)) { sameAs.push([u.href, first.get(k)]); continue; }
+  if (!t || (!isFresh(t) && noTwin(t))) urls.push(u);
+  else { asked.set(t.href, u); urls.push(t); }
+  first.set(k, urls.at(-1).href); // the key whose result line the 'same' line points to
+}
+
+function extract([sels, fallback]) {
+  const roots = [document];
+  for (let i = 0; i < roots.length; i++) for (const el of roots[i].querySelectorAll('*')) if (el.shadowRoot) roots.push(el.shadowRoot);
+  // Same-site links (nav and TOC included) so pages without an llms.txt index can still be discovered.
+  const links = new Set();
+  for (const r of roots) for (const a of r.querySelectorAll('a[href]')) {
+    if (a.host === location.host && a.pathname !== location.pathname) links.add(`${a.pathname}${a.search} ${(a.innerText || '').trim().replace(/\s+/g, ' ').slice(0, 80)}`);
+  }
+  const page = t => `# ${document.title}\n\n${t}\n`;
+  const list = [...links].join('\n');
+  // innerText stops at shadow roots (code samples, API references), so walk them in rendered order: hosts, then slots.
+  // Like innerText: hidden elements skipped, cells tab-separated; code whitespace held as no-break spaces until the end.
+  const SKIP = new Set(['STYLE', 'SCRIPT', 'NOSCRIPT', 'TEMPLATE']);
+  const deep = (n, pre) => [...(n.shadowRoot ? n.shadowRoot.childNodes : n.tagName === 'SLOT' ? n.assignedNodes({ flatten: true })
+    : n.childNodes)].map(c => {
+    if (c.nodeType === 3) return pre ? c.textContent.replace(/ /g, '\u00a0') : c.textContent.replace(/\s+/g, ' ');
+    if (c.nodeType !== 1 || SKIP.has(c.tagName)) return '';
+    if (c.tagName === 'BR') return '\n';
+    const st = getComputedStyle(c);
+    if (st.display === 'none' || st.visibility === 'hidden') return '';
+    const t = deep(c, pre || st.whiteSpace.startsWith('pre'));
+    return /^(inline|contents)/.test(st.display) ? t : st.display === 'table-cell' ? `${t}\t` : `\n${t}\n`;
+  }).join('');
+  const hosts = roots.slice(1).map(r => r.host);
+  // contains() stops at a shadow boundary, so climb each host's roots to see whether it sits anywhere under el.
+  const under = (el, h) => { for (let n = h; n; n = n.getRootNode().host) if (el.contains(n)) return true; return false; };
+  const text = el => !hosts.some(h => el.contains(h)) ? el.innerText || ''
+    : deep(el).replace(/ +/g, ' ').replace(/ ?\t ?/g, '\t').replace(/^ | $|\t+$/gm, '').replace(/\n{2,}/g, '\n')
+      .replace(/\u00a0/g, ' ').trim();
+  for (const s of sels) for (const r of roots) for (const el of r.querySelectorAll(s)) {
+    // Landmarks hold the site's nav components too, so their shadow trees stay out.
+    const mark = s === 'main' || s === 'article';
+    const t = mark ? el.innerText || '' : text(el);
+    // 200 chars skips footer cards that also match div.body; doc-content holds only the topic, and some are one line.
+    // pending: components inside it (code samples) not rendered yet. An API reference keeps empty hosts for good, so
+    // it holds instead until an api-* documentation component exists.
+    const amf = s === 'doc-amf-reference';
+    if (t.length > (s === 'doc-content' ? 20 : 200)) return { sel: s, text: page(t), links: list,
+      pending: mark || amf ? 0 : hosts.filter(h => under(el, h) && !h.shadowRoot.childElementCount).length,
+      hold: amf && !hosts.some(h => h.tagName.startsWith('API-') && under(el, h)) };
+  }
+  // No known container (a layout change): take the block whose paragraphs hold the most text, outside nav and footers.
+  // ponytail: 1,500-char floor keeps shells out (missing pages, Help's outage page: 400 to 1,200); a shorter article still fails.
+  if (fallback) {
+    const BLOCKS = 'p, li, pre, td, dd, h1, h2, h3', score = new Map(), up = n => n.parentElement || n.getRootNode().host;
+    // closest() stops at a shadow root, so climb each host too: a nav component's own template may have no <nav>.
+    const inNav = el => { for (let n = el; n; n = n.getRootNode().host) if (n.closest('nav, header, footer, [role=navigation]')) return true; return false; };
+    for (const r of roots) for (const el of r.querySelectorAll(BLOCKS)) {
+      if (inNav(el) || !el.checkVisibility()) continue; // a hidden block's innerText is its whole textContent
+      // Its own visible text: nested blocks score on their own, so a nested list counts once and a step keeps its prose.
+      const kids = [...el.querySelectorAll(BLOCKS)].filter(c => c.parentElement?.closest(BLOCKS) === el);
+      const len = e => (e.innerText || '').trim().length, n = Math.max(0, len(el) - kids.reduce((a, c) => a + len(c), 0));
+      const p = up(el), g = p && up(p);
+      if (p) score.set(p, (score.get(p) || 0) + n);
+      if (g) score.set(g, (score.get(g) || 0) + n / 2);
+    }
+    const best = [...score].sort((a, b) => b[1] - a[1])[0]?.[0], t = best ? text(best) : '';
+    if (t.length >= 1500) return { sel: 'fallback', text: page(t), links: list };
+  }
+  return { sel: 'body', text: page(document.body.innerText), links: list };
+}
+
+// Delete expired pages first, so a grep or Read over the cache afterwards only sees fresh ones.
+// Not in --quote mode: with a 0-hour window it would delete the pages this run just fetched.
+// Only the site folders: --out may point anywhere, and nothing else in it is ours to delete.
+let pruned = 0;
+for (const f of cacheFiles(SITES, 'cache cleanup')) {
+  try {
+    const st = statSync(f);
+    if (st.isFile() && Date.now() - st.mtimeMs >= PRUNE_AGE) { rmSync(f); pruned++; }
+  } catch (e) { if (e.code !== 'ENOENT') console.error(`cache cleanup: ${e.message}`); } // ENOENT: another run removed it
+}
+if (pruned) console.error(`removed ${pruned} expired cache files`);
+
+// A stored Source unlike the URL asked for means the page redirected: say so again, as the first run did. A file that
+// vanished or lost its Source line since the freshness check returns null and is fetched again.
+const fromCache = u => {
+  let t;
+  try { t = readFileSync(fileFor(u), 'utf8'); } catch { return null; }
+  const m = t.match(SOURCE);
+  if (!m) return null;
+  const src = m[0].slice(8).trim();
+  return { p: u.origin + u.pathname + u.search, status: 200, body: t.slice(m[0].length), key: u.href, cached: true,
+    note: ` (cached)${URL.canParse(src) && !sameDoc(new URL(src), new URL(official(u))) ? ` [redirected ${src}]` : ''}` };
+};
+// A reader never sees half a file: write a temp copy, then rename it into place. The pid in its name keeps two runs
+// saving one page from renaming each other's copy.
+const put = (f, data) => { const t = `${f}.${process.pid}.tmp`; mkdirSync(dirname(f), { recursive: true }); writeFileSync(t, data); renameSync(t, f); };
+for (const r of refused) console.log(`refused ${r}`);
+const results = [], seen = new Map(), saved = new Set(); // saved: files --terms prints matches from
+let ok = 0;
+// A saved page drops what is not doc text: image URLs (LDS signs S3 URLs of about 450 chars; the alt text stays) and
+// the padding in markdown table rows. Code blocks and wording are untouched.
+const lean = text => {
+  let code = ''; // the open fence: closed only by the same character, at least as long (CommonMark)
+  return text.split('\n').map(l => {
+    const f = /^\s*(`{3,}|~{3,})/.exec(l)?.[1];
+    if (f && !code) { code = f; return l; }
+    if (f && f[0] === code[0] && f.length >= code.length) { code = ''; return l; }
+    if (code) return l;
+    l = l.replace(/!\[([^\]]*)\]\(https?:\/\/[^)\s]+\)/g, '![$1]');
+    return /^\s*\|/.test(l) ? l.replace(/ {2,}/g, ' ') : l;
+  }).join('\n');
+};
+// Each page is saved and printed as it lands, so a call stopped part way keeps every page before the stop.
+const emit = r => {
+  results.push(r);
+  const { p, status, links, key, src, note, cached, shell, offsite } = r;
+  // Markdown only (a .md URL, or a twin read as r.md): rendered text has no code fences, so lean could reach a code
+  // sample. Cached pages are lean already.
+  const md = r.md || /\.md$/.test(new URL(key).pathname);
+  const body = status === 200 && !cached && md ? lean(r.body) : r.body;
+  const h = createHash('sha1').update(body).digest('hex').slice(0, 12);
+  const u = new URL(key);
+  const file = fileFor(u);
+  let tail = '';
+  if (status === 0) tail = ` ${body}`;
+  else if (offsite) tail = ' not saved: left the doc sites'; // a redirect to a login page or another domain
+  else if (shell) tail = ' not saved: shell, login or missing page';
+  else if (status === 200) {
+    ok++;
+    // Duplicates are written too, so a later run for that URL finds it; written whole (temp then rename), and one
+    // unwritable page only loses its own line. Links go to a sidecar so a Read of the page costs only its content.
+    let werr = '';
+    if (!cached) {
+      try { // a fallback marker goes on before its page and comes off only after a full read is on disk, so a failed
+        // write never leaves a fallback page that reads as full
+        if (r.fallback) put(`${file}.fallback`, '');
+        put(file, `Source: ${src || official(u)}\n${body}`); // first line names the official page
+      }
+      catch (e) { werr = ` not saved: ${e.code || e.message}`; ok--; }
+      // The page is saved either way; a marker left behind only means it is fetched again next time.
+      try { if (!r.fallback && !werr) rmSync(`${file}.fallback`, { force: true }); }
+      catch (e) { console.error(`fallback marker not removed for ${p}: ${e.code || e.message}`); }
+      try { if (links && !werr) put(`${file}.links.txt`, `${links}\n`); }
+      catch (e) { console.error(`links not saved for ${p}: ${e.code || e.message}`); }
+    }
+    const rel = slash(relative(out, file));
+    if (!werr && !seen.has(h)) saved.add(file); // a duplicate's matches are the first copy's
+    tail = werr || (seen.has(h) ? ` duplicate-of ${seen.get(h)} -> ${rel}` : ` -> ${rel}`);
+    if (!werr && !seen.has(h)) seen.set(h, p); // an unsaved body can never be the copy others point to
+  }
+  console.log(`${status} ${body.length} ${p}${note}${tail}`);
+};
+// The URL as given, so the caller reruns the page it asked for rather than its .md twin.
+const skippedAs = new Map(); // key -> the URL its time-limit line printed, for the same lines
+const skip = key => { skippedAs.set(key, asked.get(key)?.href ?? key); console.log(`not fetched (time limit) ${skippedAs.get(key)}`); };
+for (const u of urls.filter(isFresh)) { const r = fromCache(u); if (r) emit(r); else fresh.set(u.href, false); }
+
+let browser = { newPage() {}, close() {} };
+if (!urls.every(isFresh) && Date.now() < deadline) { // a spent budget skips every page, so no browser
+  try { browser = await chromium.launch({ headless: true }); }
+  catch (e) {
+    console.error(`BLOCKED: headless Chromium did not start: ${e.message.split('\n')[0]}`);
+    // The exact command, not "reinstall": a reinstall without a terminal skips the browser again.
+    const cli = slash(join(dirname(fileURLToPath(import.meta.url)), 'node_modules/playwright-core/cli.js'));
+    console.error(`Install the browser with: node "${cli}" install --only-shell chromium`);
+    console.error('On Linux, also run once: npx playwright-core install-deps chromium');
+    process.exit(3);
+  }
+}
+try {
+  // Cached: a page written in the last 24 h is read from disk, so later agents and sessions skip the fetch.
+  const todo = urls.filter(u => !isFresh(u));
+  // Help serves its sitemaps (and the KB ones, Help_DocSiteMap...) from extensionless /apex/ URLs; others end .xml.
+  const raw = todo.filter(u => /\.(md|txt|xml)$/.test(u.pathname) || /^\/apex\/Help_\w*SiteMap/i.test(u.pathname));
+  const rendered = todo.filter(u => !raw.includes(u));
+  // A twin that failed (some API reference pages have none) falls back to the URL as given, rendered at the end.
+  const settle = r => {
+    if (!asked.has(r.key) || (r.status === 200 && !r.shell)) return emit(r);
+    if (missingTwin(r.status, r.body)) markMissing(new URL(r.key));
+    const u = asked.get(r.key);
+    const c = isFresh(u) && fromCache(u);
+    if (c) emit(c); else rendered.push(u);
+  };
+
+  // Raw: one same-origin page per host, then in-page fetch() so requests carry the browser's own session.
+  for (const origin of new Set(raw.map(u => u.origin))) {
+    const paths = raw.filter(u => u.origin === origin).map(u => u.pathname + u.search);
+    if (Date.now() >= deadline) { paths.forEach(p => skip(origin + p)); continue; }
+    const page = await browser.newPage();
+    // light same-origin page; every doc site serves one. A dead host fails its own URLs, not the run.
+    const err = await page.goto(`${origin}/robots.txt`).then(() => null, e => e.message.split('\n')[0]);
+    if (err) {
+      paths.forEach(p => settle({ p, status: 0, body: `error: ${err}`, key: origin + p, note: '' }));
+      await page.close();
+      continue;
+    }
+    // Five fetches in flight; a slot takes the next path as soon as it frees, so one slow URL holds only its slot.
+    const got = await page.evaluate(async ([ps, TO, DL]) => {
+      const res = []; let next = 0;
+      await Promise.all(Array.from({ length: 5 }, async () => {
+        while (next < ps.length) {
+          const k = next++, p = ps[k];
+          if (Date.now() >= DL) { res[k] = { p, late: true }; continue; }
+          try { const r = await fetch(p, { signal: AbortSignal.timeout(TO) }); res[k] = { p, status: r.status, body: await r.text() }; }
+          catch (e) { res[k] = { p, status: 0, body: `error: ${e.message}` }; }
+        }
+      }));
+      return res;
+    }, [paths, RAW_TIMEOUT_MS, deadline]);
+    // A .md path with no twin (all atlas.en-us.* pages) answers 200 with the HTML app shell: never cache that.
+    for (const b of got) {
+      if (b.late) skip(origin + b.p);
+      else settle({ ...b, key: origin + b.p, note: '', shell: isShell(b.body) || !b.body.trim() });
+    }
+    await page.close();
+  }
+
+  // Rendered: load, give client-side content up to 20 s to appear, then take the first matching container.
+  for (const u of rendered) {
+    if (Date.now() >= deadline) { skip(u.href); continue; }
+    const page = await browser.newPage();
+    let navErr = '';
+    const nav = await page.goto(u.href, { waitUntil: 'load', timeout: 45000 }).catch(e => { navErr = e.message.split('\n')[0]; return null; });
+    if (navErr) { emit({ p: u.href, status: 0, body: `error: ${navErr}`, key: u.href, note: '' }); await page.close(); continue; }
+    // Poll from Node: waitForFunction needs string eval, which some sites' CSP refuses (zeroheight does).
+    let got = { sel: 'body', text: '' }, mainAt = 0, matchAt = 0, last = '', same = 0;
+    const peak = {};
+    for (const end = Date.now() + 20000; Date.now() < end; await page.waitForTimeout(500)) {
+      got = await page.evaluate(extract, [CONTENT, false]).catch(e => ({ sel: 'body', text: `extract failed: ${e.message}` }));
+      // `main` can be only the site nav while the article still renders (LDS): give a better match 5 s to appear.
+      if (got.sel === 'main' && Date.now() - (mainAt ||= Date.now()) < 5000) continue;
+      // A container can appear before it is filled (API reference nav first, code samples last): wait for 1 s
+      // unchanged with nothing pending, 4 s if a component never renders, 8 s after it last grew if it never settles.
+      same = `${got.text.length}/${got.pending}` === last ? same + 1 : 0;
+      last = `${got.text.length}/${got.pending}`;
+      // The cap restarts only when a container passes its own peak: body text is ignored, and flips do not restart it.
+      if (got.sel !== 'body' && got.text.length > (peak[got.sel] || 0)) { peak[got.sel] = got.text.length; matchAt = Date.now(); }
+      if (got.sel !== 'body' && !got.hold && (same >= (got.pending ? 8 : 2) || Date.now() - matchAt > 8000)) break;
+    }
+    // Only after the wait: inside it, the fallback would win before the real container rendered.
+    if (got.sel === 'body') got = await page.evaluate(extract, [CONTENT, true])
+      .catch(e => { console.error(`fallback failed on ${u.href}: ${e.message.split('\n')[0]}`); return got; });
+    const { sel, text, links, hold } = got;
+    // A redirect is shown and cited: a mistyped atlas topic lands on its guide's landing page with status 200, and a
+    // Help article can move to another ?id= on the same path.
+    const to = new URL(page.url()), hop = sameDoc(to, u) ? '' : ` [redirected ${to.href}]`;
+    // Old atlas URLs (and the LDS home) redirect to pages that have a .md twin: keep the rendered links, read the twin.
+    const moved = hop && twinOf(to);
+    const tryTwin = moved && !noTwin(moved);
+    // Any failure (late navigation, body error, 15 s hang) keeps the rendered text, and the output line says why.
+    // 15 s, not RAW_TIMEOUT_MS: this runs after a full render, so it counts against a rendered page's budget.
+    const tw = tryTwin ? await page.evaluate(p => fetch(p, { signal: AbortSignal.timeout(15000) })
+      .then(async r => ({ status: r.status, body: await r.text() })).catch(e => ({ why: e.name })), moved.pathname)
+      .catch(e => ({ why: e.message.split('\n')[0] })) : {};
+    const gone = !tw.why && missingTwin(tw.status, tw.body);
+    const md = !tw.why && !gone && tw.status === 200 ? tw.body : '';
+    const why = tw.why || (gone ? (tw.status === 404 ? 'status 404' : isShell(tw.body) ? 'shell' : 'empty') : `status ${tw.status}`);
+    if (tryTwin && gone) markMissing(moved);
+    const failed = tryTwin && !md ? ` [twin failed: ${why}]` : '';
+    if (md) {
+      emit({ p: u.href, status: 200, body: md, md: true, links, key: u.href, src: official(moved), note: ` [twin ${moved.pathname}] [redirected ${official(moved)}]` });
+      await page.close();
+      continue;
+    }
+    // A shell (no container, extract failed, or API docs still not loaded at 20 s) is reported but never cached.
+    emit({ p: u.origin + u.pathname + u.search, status: nav?.status() ?? 0, body: text, links, key: u.href,
+      src: hop && to.href, note: ` [${sel}]${hold ? ' [api docs did not load]' : ''}${hop}${failed}`, offsite: !SITES.includes(to.host), shell: sel === 'body' || hold, fallback: sel === 'fallback' });
+    await page.close();
+  }
+
+  // Name the line actually printed for the first argument: a twin that fell back prints under the page it rendered.
+  const shown = new Map(results.map(r => [r.key, r.p]));
+  for (const [g, k] of sameAs) console.log(`same ${g} as ${shown.get(k) ?? shown.get(asked.get(k)?.href) ?? skippedAs.get(k) ?? skippedAs.get(asked.get(k)?.href) ?? k}`);
+  const late = skippedAs.size;
+  console.log(`fetched ${urls.length - late}, 200 ${ok}, unique bodies ${seen.size}${refused.length ? `, refused ${refused.length}` : ''}${late ? `, not fetched ${late} (time limit)` : ''}, out ${slash(out)}`);
+  if (!urls.length && refused.length) process.exitCode = 1; // nothing on a doc site was asked for
+  for (const f of terms.length ? saved : []) {
+    console.log(`\n== ${slash(relative(out, f))}\n${grep(f, terms).join('\n') || 'no match'}`);
+    const links = statSync(`${f}.links.txt`, { throwIfNoEntry: false }) ? grep(`${f}.links.txt`, terms) : [];
+    if (links.length) console.log(`== ${slash(relative(out, f))}.links.txt\n${links.join('\n')}`);
+  }
+} finally {
+  await browser.close();
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "sf-docs-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Claude Code subagent that answers from official Salesforce docs (developer, architect, help, admin, lightningdesignsystem.com) with grep-checked quotes",
+  "devDependencies": {
+    "playwright-core": "1.56.1"
+  },
+  "bin": {
+    "sf-docs-agent": "bin/install.mjs"
+  },
+  "files": [
+    "bin",
+    "agents",
+    "fetch-docs.mjs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drsaavedra/sf-docs-agent.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "claude-code",
+    "subagent",
+    "salesforce",
+    "documentation",
+    "llms.txt",
+    "playwright"
+  ],
+  "scripts": {
+    "test": "node --test --test-reporter=spec"
+  }
+}