sf-docs-agent 0.1.1 → 0.1.3

package/README.md

@@ -1,312 +1,113 @@
 # sf-docs-agent
 
-[![npm](https://img.shields.io/npm/v/sf-docs-agent)](https://www.npmjs.com/package/sf-docs-agent)
-
-A Claude Code subagent that answers Salesforce questions from the official docs and hands back quotes, not pages.
+**Read the docs, keep your context.** A Claude Code agent that reads the official Salesforce docs for you and returns just the lines that answer, each with its official URL.
 
-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.
+[![npm](https://img.shields.io/npm/v/sf-docs-agent)](https://www.npmjs.com/package/sf-docs-agent)
 
-I built this because every docs lookup was dumping whole pages into my session. I only wanted the lines that answer my question.
+**84% fewer tokens** added to your session than Salesforce's own docs skill · **117 of 117** cited lines still on today's page · **every line** checkable with one `grep`
 
-## Why an agent, not a skill
+[Install](#install) · [Use](#use) · [How it works](#how-it-works) · [How it compares](#how-it-compares) · [Limitations](#limitations) · [Benchmarks](https://github.com/drsaavedra/sf-docs-agent/blob/main/docs/benchmarks.md)
 
-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."
+| Salesforce's platform-docs-get skill · 4,578 tokens | sf-docs-agent · 303 tokens |
+|---|---|
+| Every page it read lands in your session | Only the lines that answer, each with its official URL |
 
-Here is how the two compare:
+*"How many versions can a flow have?"* Same right answer. 4,578 tokens become 303.
 
-| | 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 agent reads the pages in its own context. The model picks the lines and a script copies them word for word from the cached page, so no quote is written from the model's memory.
 
-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 copied word for word from the page, not written from the model's memory, and you can
-check it with one `grep` against the cached copy, which saves curly quotes as straight ones and drops image links and
-the padding in table rows.
+I built this because every docs lookup was dumping whole pages into my Claude Code session. I only wanted the lines that answer my question.
 
-## 84% less in your context, 63% fewer tokens overall
+## Install
 
-On 10 questions against Salesforce's own platform-docs-get skill, the agent
-added 84% fewer tokens to your context and used 63% fewer tokens over the whole session, with the right answer on
-10 of 10.
+Needs Node 22+ and Claude Code.
 
-Below are the measurements, each read as platform-docs-get → sf-docs.
+```
+npx sf-docs-agent
+```
 
-| Question | Site | Tokens added to context | Saved | Session token usage | Saved |
-|---|---|---|---|---|---|
-| 1. Scratch org editions | developer | 2,178 → **289** | **86.7%** | 338,852 → **119,355** | **64.8%** |
-| 2. Platform event allocation | developer | 4,107 → **490** | **88.1%** | 387,598 → **120,396** | **68.9%** |
-| 3. QueryLocator batch limits | developer | 2,568 → **581** | **77.4%** | 406,878 → **113,611** | **72.1%** |
-| 4. Integration patterns | architect | 1,104 → **484** | **56.2%** | 154,068 → **125,540** | **18.5%** |
-| 5. Salesforce Connect editions | help | 1,948 → **322** | **83.5%** | 382,751 → **157,746** | **58.8%** |
-| 6. Flow version limits | help | 4,578 → **290** | **93.7%** | 339,464 → **164,888** | **51.4%** |
-| 7. Headless 360 | admin | 3,772 → **380** | **89.9%** | 427,542 → **117,258** | **72.6%** |
-| 8. SLDS tooltips | lightningdesignsystem | 3,876 → **414** | **89.3%** | 340,914 → **112,252** | **67.1%** |
-| 9. Bulk API batch size | developer | 2,134 → **411** | **80.7%** | 506,340 → **125,870** | **75.1%** |
-| 10. Pub/Sub fetch limit | developer | 1,199 → **716** | **40.3%** | 236,766 → **130,110** | **45.0%** |
-| **All** | | 27,464 → **4,377** | **84.1%** | 3,521,173 → **1,287,026** | **63.4%** |
+Then start a new Claude Code session. The agent is listed as `sf-docs`. Add `--project` to install it for the current project only.
 
 <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?
+<summary>Headless browser, Linux, update, remove, cache</summary>
 
-</details>
+- **Headless browser:** some sites have no `.md` copy of their pages, so the agent opens them in a headless browser. The installer asks before it downloads Chromium (about 200 MB). Pass `--yes` to skip the question.
+- **Linux:** also run `node "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/sf-docs/node_modules/playwright-core/cli.js" install-deps chromium` once.
+- **Update:** `npx sf-docs-agent@latest`
+- **Remove:** delete `~/.claude/agents/sf-docs.md` (or `.claude/agents/sf-docs.md` in the project), then `~/.claude/sf-docs/` once no project uses it. Chromium stays in Playwright's cache (`~/Library/Caches/ms-playwright` on macOS, `~/.cache/ms-playwright` on Linux); delete that too if nothing else uses Playwright.
+- **Cache:** pages stay cached for 24 hours. Set `SF_DOCS_CACHE_HOURS` in your Claude Code `settings.json` to change it (`0` fetches every time).
 
-## 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 |
+</details>
 
 ## 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.
+Ask in your own words. Name the site or product if you know it, or paste a Salesforce docs link and ask about it.
 
 ```
 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>
+Part of what came back (Opus 5.5, 89 seconds):
 
 > 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
+> **Not covered:** I didn't read the Asynchronous Callout Limits page or the Winter '27 release notes.
 
-</details>
+It tells you what it did not read. A gap you can see beats a guess you can't.
 
-## Install
+It covers developer.salesforce.com, architect.salesforce.com, help.salesforce.com, admin.salesforce.com and lightningdesignsystem.com. Full outputs on Opus and Sonnet: [docs/examples.md](https://github.com/drsaavedra/sf-docs-agent/blob/main/docs/examples.md)
+
+## How it works
 
-Needs Node 22+ and Claude Code. The installer is on npm as
-[`sf-docs-agent`](https://www.npmjs.com/package/sf-docs-agent).
+1. **Finds the page.** It searches the site's `llms.txt` index or sitemaps, or starts from the link you give it.
+2. **Reads the cleanest copy.** Where Salesforce publishes a `.md` copy of a page (the new developer docs, architect, SLDS 2), it reads that. Help, admin and some older guides have none, so it renders them in a headless browser. No fake user agent, no stealth plugin.
+3. **Picks lines, not prose.** The model reads the cached page in the agent's own context and picks line numbers. A script copies those lines, each with its official URL.
+4. **Names what it missed.** A page it did not read, or a link it did not follow, comes back as a gap.
+
+To check a line, replace `<cache path>` (the agent's Sources name it) and `<quote>` below. Apostrophes are safe, and the cache saves curly quotes as straight ones, so a quote you retype still matches. Keep one quote on one line with no blank line around it, since grep counts a blank line as matching every line. Any count above 0 means the line is on the page.
 
 ```
-npx sf-docs-agent            # for all your projects
-npx sf-docs-agent --project  # for the project in the current folder only
+grep -c -F -f - <cache path> <<'EOF'
+<quote>
+EOF
 ```
 
-The installer adds `playwright-core` (13 MB) and asks before it downloads headless Chromium (about 200 MB). Pass
-`--yes` to skip the question in scripts. If you say no, it prints the command to run before first use. On Linux, also
-run `node "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/sf-docs/node_modules/playwright-core/cli.js" install-deps chromium` once
-for the system libraries. It asks for your password itself.
+Every site, and how it reads each one: [docs/how-it-works.md](https://github.com/drsaavedra/sf-docs-agent/blob/main/docs/how-it-works.md)
 
-Then start a new Claude Code session. The agent is listed as `sf-docs`.
+## How it compares
 
-**Update:** `npx sf-docs-agent@latest`. Without `@latest`, npx runs any copy already installed globally or in the
-current project.
+Salesforce has two official options for the same job. I ran both on the same 10 questions.
 
-**Remove:** delete `~/.claude/agents/sf-docs.md` (or `.claude/agents/sf-docs.md` in the project). The script and cache
-live in `~/.claude/sf-docs/` for every scope, so delete that folder last, once no project uses the agent. If
-`CLAUDE_CONFIG_DIR` is set, the installer uses that instead of `~/.claude`.
+**[platform-docs-get](https://github.com/forcedotcom/sf-skills/tree/main/skills/platform-docs-get)**, a skill in Salesforce's sf-skills library, pulls every page it reads into your session. Against it, sf-docs-agent added 84% fewer tokens to your session and used 34% fewer tokens overall. Both got 39 of 40 runs right.
 
-**Cache:** 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):
+**[Salesforce Docs MCP](https://labs.agentforce.com/docs/salesforce-docs-mcp)** searches a closed index with no dates on its results. It is the same trade-off you accept with [Context7](https://github.com/upstash/context7), whose README says its parsing and crawling engines are private: you can't see what the index holds or when it was taken. In my runs it returned no page from admin.salesforce.com or SLDS 2. In a subagent it got 24 of 30 right against sf-docs-agent's 29 of 30, and only 135 of its 177 quotes were on today's page, against 117 of 117. Called from the main session it got 28 of 30, but added 10 times as many tokens to your session.
 
-```json
-{ "env": { "SF_DOCS_CACHE_HOURS": "72" } }
-```
+**Where sf-docs-agent loses:** the MCP in a subagent is faster and cheaper: 218 seconds against 346 for all 10 questions, and 29% fewer tokens. If you are fine trusting the index, it is a good choice. I wanted something I control and can check against the live sites.
+
+My numbers are from a rerun on 2 November 2026, after the agent started following two links. The other tools ran on 30 and 31 October 2026 and were not rerun, and the docs changed in between.
+
+Every number, per question, with the method: [docs/benchmarks.md](https://github.com/drsaavedra/sf-docs-agent/blob/main/docs/benchmarks.md)
 
 ## 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.
-- On a long list or table, the agent now and then stops a row early, for example five of six integration patterns.
-  Every quote it gives is still right; the missing row is the problem.
-- 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.
+- Help, admin and some older developer guides have no `.md` copy, so those pages are slower. If Salesforce changes their layout, the agent may read only part of an article. A daily check in this repo flags it.
+- No Help search, because Help's `robots.txt` disallows it.
+- From a page it found, it follows at most two more links in a row, and only toward a missing part of the answer. Anything further comes back as a gap.
+- On a long list it sometimes stops a row early. The quotes it gives are still right.
+- If a site blocks headless browsers, it stops and tells you. It does not try to get around the block.
+- The agent has Bash. Its instructions limit it to its script and cache, but that is an instruction to the model, not a sandbox.
+- No telemetry. Only the docs pages it fetches leave your machine.
+
+How it reads each site, and the full list: [docs/how-it-works.md](https://github.com/drsaavedra/sf-docs-agent/blob/main/docs/how-it-works.md)
 
 ## Develop
 
@@ -317,8 +118,9 @@ sed "s|/path/to/sf-docs-agent|$PWD|g" agents/sf-docs.md > "${CLAUDE_CONFIG_DIR:-
 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.
+`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. Run it again after you edit the agent.
+
+**Release:** open a PR that only bumps the version (`npm version patch --no-git-tag-version`, which changes `package.json` and `package-lock.json`). Merging it runs [`release.yml`](.github/workflows/release.yml): the tests, an install of the packed tarball, `npm publish` through npm trusted publishing (no token), a check that npm holds the tarball that was tested, then the `v<version>` tag and GitHub Release.
 
 ## License
 

package/agents/sf-docs.md

@@ -1,6 +1,6 @@
 ---
 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.
+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, an empty JavaScript shell or a raw HTML page. Show the user its Answer and Sources. To check a quote, run `grep -c -F -f - <cache path>` with the quote on stdin through a quoted heredoc (`<<'EOF'`), so an apostrophe in it cannot break the shell: one quote on one line, no blank line, since grep counts a blank line as matching every line. Reads docs only. Not for org state.
 model: claude-sonnet-5-5
 tools: Bash, Read
 ---
@@ -43,8 +43,8 @@ that, the printed output is the limit, not time.
   `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
+  since a mistyped atlas topic redirects to its guide's landing page, which is not evidence; in the Apex Developer
+  Guide, which moved to the new docs, it answers 404 and nothing is saved. 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
@@ -85,13 +85,17 @@ Every tool call costs you the whole conversation again, so use as few Bash calls
    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.
+   Leave quote marks out of a grep term and search the words on either side: a `'` ends the shell quote, and a
+   curly one from the question misses a page saved with straight ones.
    Never read a page whole. When the answer is a list or a table (patterns, editions, values), Read from its first
    item to the next heading before you quote: a `--terms` match list stops at its cap, and the last rows may not
    hold your term.
-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.
+4. **Two hops at most.** 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`. From that page, follow one more link
+   the same way when that link names the part still missing. A page named by the page the second hop reached stays a
+   Gap. Follow a link only for a missing part of the answer. 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
@@ -102,7 +106,8 @@ Every tool call costs you the whole conversation again, so use as few Bash calls
 
 - 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.
+  `BLOCKED: <status>`; do not try another route. WebFetch and curl are not routes: they get a 403, an empty
+  JavaScript shell on Help, or raw HTML with no Source line for `--quote`.
 - 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.
@@ -114,7 +119,8 @@ Every tool call costs you the whole conversation again, so use as few Bash calls
 ## 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.
+  caller's width ("the one concept page") still allows the linked pages, up to two hops (step 4), 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.

package/fetch-docs.mjs

@@ -74,8 +74,9 @@ const SOURCE = /^Source: [^\n]*\n/;
 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(/\/$/, '')
+// One page, whatever the scheme (0.1.2 saved http:// Source lines), #anchor or trailing slash; a Help article is
+// told apart by its ?id=.
+const sameDoc = (a, b) => a.host === b.host && 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('/');
@@ -119,8 +120,9 @@ const grep = (file, t) => {
 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));
+    const m = spec.match(/^(.+):(\d+(?:,\d+)*)$/); // greedy: a Windows C:\... colon stays in the path
+    if (!m) { console.error(`not <cache file>:<line>[,<line>...]: ${spec}`); continue; }
+    const file = isAbsolute(m[1]) ? m[1] : join(out, m[1]);
     // Only cached official pages: inside the cache dir and starting with their Source: line.
     const inside = relative(out, file);
     let lines;
@@ -128,7 +130,7 @@ if (args[0] === '--quote') {
     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)) {
+    for (const n of m[2].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`);
@@ -186,7 +188,7 @@ const parse = a => {
 const given = [], refused = [];
 for (const a of args) {
   const u = parse(a);
-  if (u && SITES.includes(u.host)) given.push(u);
+  if (u && SITES.includes(u.host)) { u.protocol = 'https:'; given.push(u); } // all https: one key, one Source line
   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.
@@ -451,8 +453,8 @@ try {
     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.
+    // A redirect is shown and cited: a mistyped atlas topic lands on its guide's landing page with status 200 (a 404 in
+    // a guide that moved to the new docs), 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sf-docs-agent",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Claude Code subagent that answers from official Salesforce docs (developer, architect, help, admin, lightningdesignsystem.com) with grep-checked quotes",
   "devDependencies": {