Merge pull request #12 from triggerdotdev/docs/intent-install-copy

ericallam · web-flow · commit 8b63eadde12d · 2026-03-10T15:13:01.000Z
docs: clarify that intent install is agent-facing
diff --git a/.changeset/fix-docs-urls.md b/.changeset/fix-docs-urls.md
@@ -0,0 +1,5 @@
+---
+"agentcrumbs": patch
+---
+
+Fix docs URLs from docs.agentcrumbs.dev to agentcrumbs.dev/docs
diff --git a/README.md b/README.md
@@ -14,18 +14,15 @@ Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/crum
 
 ```bash
 npm install agentcrumbs
-npx @tanstack/intent install
 ```
 
-Then tell your agent: **"Run the agentcrumbs/init skill."**
+Then tell your agent: **"Run `npx @tanstack/intent@latest install` to set up agentcrumbs skills, then run the agentcrumbs/init skill."**
 
-The init skill scans your repo, discovers services and modules, and builds a **namespace catalog** that gets written to your agent config (CLAUDE.md, .cursorrules, etc.). Without the catalog, every agent invents its own namespace names: `auth`, `auth-service`, `authService`, `authentication`, all pointing at the same thing. The catalog locks it down. Every agent, every session, same names.
-
-After init, the agent knows which namespaces to use and how to drop crumbs correctly.
+The agent will wire the skills into your agent config (CLAUDE.md, .cursorrules, etc.), then scan your repo to build a namespace catalog so all agents use consistent names.
 
 ## Agent skills
 
-agentcrumbs ships with [@tanstack/intent](https://tanstack.com/blog/from-docs-to-agents) skills inside the npm package. Running `npx @tanstack/intent install` wires them into your agent config so the agent learns correct usage patterns, common mistakes to avoid, and the namespace catalog for your project.
+agentcrumbs ships with [@tanstack/intent](https://tanstack.com/blog/from-docs-to-agents) skills inside the npm package. When your agent runs `npx @tanstack/intent install`, it sets up skill-to-task mappings in your agent config so it knows when to load agentcrumbs patterns.
 
 | Skill | What it teaches |
 | --- | --- |
@@ -87,7 +84,7 @@ The only cost is the function call itself, which V8 will likely inline after war
 
 ## API overview
 
-All methods are documented in detail at [docs.agentcrumbs.dev/api](https://docs.agentcrumbs.dev/api).
+All methods are documented in detail at [agentcrumbs.dev/docs/api](https://agentcrumbs.dev/docs/api).
 
 | Method | Purpose |
 | --- | --- |
@@ -103,7 +100,7 @@ All methods are documented in detail at [docs.agentcrumbs.dev/api](https://docs.
 
 ## Crumb markers
 
-Mark crumb lines with `// @crumbs` (single line) or `// #region @crumbs` / `// #endregion @crumbs` (block) so they can be stripped before merge. See the [markers docs](https://docs.agentcrumbs.dev/markers) for details and examples.
+Mark crumb lines with `// @crumbs` (single line) or `// #region @crumbs` / `// #endregion @crumbs` (block) so they can be stripped before merge. See the [markers docs](https://agentcrumbs.dev/docs/markers) for details and examples.
 
 ## Environment variable
 
@@ -154,7 +151,7 @@ Time units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days).
 
 ## Multi-service architecture
 
-All services write to the same collector. `agentcrumbs tail` shows interleaved output with namespace-colored labels. See the [multi-service docs](https://docs.agentcrumbs.dev/multi-service) for setup patterns.
+All services write to the same collector. `agentcrumbs tail` shows interleaved output with namespace-colored labels. See the [multi-service docs](https://agentcrumbs.dev/docs/multi-service) for setup patterns.
 
 ## Cross-language compatibility
 
@@ -174,7 +171,7 @@ Verified compatible with **Node.js 18+** and **Bun**.
 
 ## Docs
 
-Full documentation at [docs.agentcrumbs.dev](https://docs.agentcrumbs.dev).
+Full documentation at [agentcrumbs.dev/docs](https://agentcrumbs.dev/docs).
 
 ## License
 
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx
@@ -31,20 +31,17 @@ Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/crum
 - **Strip before merge.** `agentcrumbs strip` removes all `// @crumbs` lines and `#region @crumbs` blocks. Clean diffs, no debug code on main.
 - **HTTP collector.** `agentcrumbs collect` receives crumbs from all services via fire-and-forget HTTP. Tail, query, and replay from the CLI.
 - **Works with any agent.** Claude Code, Cursor, Copilot, Aider, custom agents. If the agent can write code, it can write crumbs.
-- **Ships with agent skills.** Built on [@tanstack/intent](https://tanstack.com/blog/from-docs-to-agents). Install the package, run `npx @tanstack/intent install`, and the agent learns how to use crumbs from the package itself. No stale training data.
+- **Ships with agent skills.** Built on [@tanstack/intent](https://tanstack.com/blog/from-docs-to-agents). Install the package, tell your agent to run `npx @tanstack/intent install`, and it learns how to use crumbs from the package itself. No stale training data.
 
 ## Install
 
 ```bash
 npm install agentcrumbs
-npx @tanstack/intent install
 ```
 
-Then tell your agent: **"Run the agentcrumbs/init skill."**
+Then tell your agent: **"Run `npx @tanstack/intent@latest install` to set up agentcrumbs skills, then run the agentcrumbs/init skill."**
 
-This is the critical step. The [init skill](/skills#the-init-skill) scans your repo, discovers services and modules, and builds a namespace catalog that gets written to your agent config (CLAUDE.md, .cursorrules, etc.). Without the catalog, every agent invents its own namespace names. With it, every agent, every session, same names.
-
-See the [quickstart](/quickstart) for the full setup.
+The agent wires skills into your agent config (CLAUDE.md, .cursorrules, etc.) and scans your repo to build a namespace catalog. See the [quickstart](/quickstart) for the full setup.
 
 ## How it works
 
diff --git a/docs/content/docs/quickstart.mdx b/docs/content/docs/quickstart.mdx
@@ -9,25 +9,18 @@ description: "Install agentcrumbs and set up your agent in 2 minutes"
 npm install agentcrumbs
 ```
 
-## Wire the skills
+## Set up skills
 
-```bash
-npx @tanstack/intent install
-```
-
-This pulls agentcrumbs' [@tanstack/intent](https://tanstack.com/blog/from-docs-to-agents) skills into your agent config (CLAUDE.md, .cursorrules, etc.).
-
-## Run the init skill
-
-This is the most important step. Tell your agent:
+Tell your agent:
 
-> "Run the agentcrumbs/init skill to set up debug tracing in this project."
+> "Run `npx @tanstack/intent@latest install` to set up agentcrumbs skills, then run the agentcrumbs/init skill."
 
-The agent scans your repo, discovers services and modules, and proposes a **namespace catalog**: a table of every service name and what it maps to. You confirm or adjust, and the agent writes it to your config file.
+The agent will:
 
-Why this matters: without the catalog, every agent invents its own names. One session uses `auth`, another uses `auth-service`, another uses `authentication`. Crumbs become impossible to query across sessions. The catalog locks down the names so every agent, every time, uses the same ones.
+1. Run `npx @tanstack/intent install` which gives it a prompt to wire skill-to-task mappings into your agent config (CLAUDE.md, .cursorrules, etc.)
+2. Run the [init skill](/skills#the-init-skill) to scan your repo, discover services and modules, and write a namespace catalog to your config
 
-After init, the agent knows which namespaces to use and how to drop crumbs correctly. See [Skills](/skills#the-init-skill) for the full details.
+The namespace catalog is a table of service names your agents should use. It keeps naming consistent across sessions. See [Skills](/skills#the-init-skill) for details.
 
 ## Manual setup
 
diff --git a/docs/content/docs/skills.mdx b/docs/content/docs/skills.mdx
@@ -3,7 +3,7 @@ title: "Agent skills"
 description: "How agents learn to use agentcrumbs via @tanstack/intent"
 ---
 
-agentcrumbs ships with agent skills inside the npm package, built on the [@tanstack/intent](https://tanstack.com/blog/from-docs-to-agents) standard. When you install the package and run `npx @tanstack/intent install`, your agent automatically learns how to use crumbs correctly.
+agentcrumbs ships with agent skills inside the npm package, built on the [@tanstack/intent](https://tanstack.com/blog/from-docs-to-agents) standard. Tell your agent to run `npx @tanstack/intent install` and it will set up skill-to-task mappings in your agent config so it knows when to load agentcrumbs patterns.
 
 Skills travel with the package version. The agent always has docs matching the installed code, not stale training data from 6 months ago.
 
@@ -13,10 +13,9 @@ The fastest way to set up agentcrumbs in a project is to let the agent do it:
 
 ```bash
 npm install agentcrumbs
-npx @tanstack/intent install
 ```
 
-This scans `node_modules` for intent-enabled packages and wires the skills into your agent config file (CLAUDE.md, .cursorrules, etc.). Then tell your agent:
+Then tell your agent:
 
 > "Run the agentcrumbs/init skill to set up debug tracing in this project."
 
@@ -76,4 +75,4 @@ node_modules/agentcrumbs/skills/agentcrumbs/SKILL.md
 node_modules/agentcrumbs/skills/agentcrumbs/init/SKILL.md
 ```
 
-Or add a reference in your agent config file manually. But `npx @tanstack/intent install` handles all of this automatically.
+Or add a reference in your agent config file manually. But telling your agent to run `npx @tanstack/intent install` handles all of this automatically.
diff --git a/docs/src/app/home.css b/docs/src/app/home.css
@@ -75,14 +75,17 @@
 
 /* INSTALL */
 .hp-install-section { padding: 32px 0 64px; }
-.hp-install-steps { display: flex; flex-direction: column; gap: 12px; max-width: 520px; margin: 0 auto; }
+.hp-install-steps { display: flex; flex-direction: column; gap: 12px; max-width: 600px; margin: 0 auto; }
 .hp-install-step { display: flex; align-items: center; gap: 12px; }
 .hp-install-step-num { font-family: var(--hp-mono); font-size: 12px; color: var(--hp-accent); width: 20px; text-align: center; flex-shrink: 0; }
 .hp-install-step-text { font-family: var(--hp-mono); font-size: 14px; color: var(--hp-text-dim); padding: 14px 0; }
-.hp-install-bar { display: flex; align-items: center; background: var(--hp-bg-raised); border: 1px solid var(--hp-border-bright); border-radius: 8px; padding: 14px 20px; gap: 16px; font-family: var(--hp-mono); font-size: 15px; transition: border-color 0.15s; }
+.hp-install-bar { display: flex; align-items: center; background: var(--hp-bg-raised); border: 1px solid var(--hp-border-bright); border-radius: 8px; padding: 14px 20px; gap: 12px; font-family: var(--hp-mono); font-size: 15px; transition: border-color 0.15s; flex: 1; }
 .hp-install-bar:hover { border-color: #333; }
-.hp-prompt-sign { color: var(--hp-accent); user-select: none; }
+.hp-prompt-sign { color: var(--hp-accent); user-select: none; width: 44px; text-align: right; flex-shrink: 0; }
 .hp-install-bar code { color: var(--hp-text); white-space: nowrap; background: transparent !important; padding: 0 !important; font-size: inherit; }
+.hp-install-bar-agent { font-size: 14px; }
+.hp-install-bar-agent code { white-space: normal; color: var(--hp-text-dim); }
+.hp-agent-label { color: var(--hp-accent); user-select: none; font-size: 12px; text-transform: uppercase; letter-spacing: 0.05em; width: 44px; text-align: right; flex-shrink: 0; }
 .hp-copy-btn { background: none; border: 1px solid var(--hp-border-bright); border-radius: 4px; color: var(--hp-text-dim); font-family: var(--hp-mono); font-size: 12px; padding: 4px 10px; cursor: pointer; transition: all 0.15s; white-space: nowrap; }
 .hp-copy-btn:hover { color: var(--hp-text); border-color: #444; }
 
diff --git a/docs/src/app/page.tsx b/docs/src/app/page.tsx
@@ -155,16 +155,11 @@ export default function HomePage() {
             </div>
             <div className="hp-install-step">
               <div className="hp-install-step-num">2</div>
-              <div className="hp-install-bar">
-                <span className="hp-prompt-sign">$</span>
-                <code id="intent-cmd">npx @tanstack/intent install</code>
-                <button className="hp-copy-btn" onClick={(e) => copyCmd('intent-cmd', e.currentTarget)}>copy</button>
+              <div className="hp-install-bar hp-install-bar-agent">
+                <span className="hp-agent-label">agent</span>
+                <code>Run npx @tanstack/intent install, then run the agentcrumbs/init skill</code>
               </div>
             </div>
-            <div className="hp-install-step">
-              <div className="hp-install-step-num">3</div>
-              <div className="hp-install-step-text">Tell your agent: <span style={{ color: 'var(--hp-text)' }}>&quot;Run the agentcrumbs/init skill&quot;</span></div>
-            </div>
           </div>
         </div>
       </section>
diff --git a/packages/agentcrumbs/README.md b/packages/agentcrumbs/README.md
@@ -14,18 +14,15 @@ Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/crum
 
 ```bash
 npm install agentcrumbs
-npx @tanstack/intent install
 ```
 
-Then tell your agent: **"Run the agentcrumbs/init skill."**
+Then tell your agent: **"Run `npx @tanstack/intent@latest install` to set up agentcrumbs skills, then run the agentcrumbs/init skill."**
 
-The init skill scans your repo, discovers services and modules, and builds a **namespace catalog** that gets written to your agent config (CLAUDE.md, .cursorrules, etc.). Without the catalog, every agent invents its own namespace names: `auth`, `auth-service`, `authService`, `authentication`, all pointing at the same thing. The catalog locks it down. Every agent, every session, same names.
-
-After init, the agent knows which namespaces to use and how to drop crumbs correctly.
+The agent will wire the skills into your agent config (CLAUDE.md, .cursorrules, etc.), then scan your repo to build a namespace catalog so all agents use consistent names.
 
 ## Agent skills
 
-agentcrumbs ships with [@tanstack/intent](https://tanstack.com/blog/from-docs-to-agents) skills inside the npm package. Running `npx @tanstack/intent install` wires them into your agent config so the agent learns correct usage patterns, common mistakes to avoid, and the namespace catalog for your project.
+agentcrumbs ships with [@tanstack/intent](https://tanstack.com/blog/from-docs-to-agents) skills inside the npm package. When your agent runs `npx @tanstack/intent install`, it sets up skill-to-task mappings in your agent config so it knows when to load agentcrumbs patterns.
 
 | Skill | What it teaches |
 | --- | --- |
@@ -87,7 +84,7 @@ The only cost is the function call itself, which V8 will likely inline after war
 
 ## API overview
 
-All methods are documented in detail at [docs.agentcrumbs.dev/api](https://docs.agentcrumbs.dev/api).
+All methods are documented in detail at [agentcrumbs.dev/docs/api](https://agentcrumbs.dev/docs/api).
 
 | Method | Purpose |
 | --- | --- |
@@ -103,7 +100,7 @@ All methods are documented in detail at [docs.agentcrumbs.dev/api](https://docs.
 
 ## Crumb markers
 
-Mark crumb lines with `// @crumbs` (single line) or `// #region @crumbs` / `// #endregion @crumbs` (block) so they can be stripped before merge. See the [markers docs](https://docs.agentcrumbs.dev/markers) for details and examples.
+Mark crumb lines with `// @crumbs` (single line) or `// #region @crumbs` / `// #endregion @crumbs` (block) so they can be stripped before merge. See the [markers docs](https://agentcrumbs.dev/docs/markers) for details and examples.
 
 ## Environment variable
 
@@ -154,7 +151,7 @@ Time units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days).
 
 ## Multi-service architecture
 
-All services write to the same collector. `agentcrumbs tail` shows interleaved output with namespace-colored labels. See the [multi-service docs](https://docs.agentcrumbs.dev/multi-service) for setup patterns.
+All services write to the same collector. `agentcrumbs tail` shows interleaved output with namespace-colored labels. See the [multi-service docs](https://agentcrumbs.dev/docs/multi-service) for setup patterns.
 
 ## Cross-language compatibility
 
@@ -174,7 +171,7 @@ Verified compatible with **Node.js 18+** and **Bun**.
 
 ## Docs
 
-Full documentation at [docs.agentcrumbs.dev](https://docs.agentcrumbs.dev).
+Full documentation at [agentcrumbs.dev/docs](https://agentcrumbs.dev/docs).
 
 ## License
 
diff --git a/packages/agentcrumbs/package.json b/packages/agentcrumbs/package.json
@@ -37,7 +37,7 @@
   "intent": {
     "version": 1,
     "repo": "triggerdotdev/agentcrumbs",
-    "docs": "https://docs.agentcrumbs.dev"
+    "docs": "https://agentcrumbs.dev/docs"
   },
   "scripts": {
     "build": "tsc",

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"agentcrumbs": patch
 +---
++
 +Fix docs URLs from docs.agentcrumbs.dev to agentcrumbs.dev/docs