docs: expand tools overview with JS SDK, PocketIC, and ic-wasm cleanup

.docs-plan/decisions.md

@@ -4,6 +4,15 @@ Record decisions that constrain future work — things an agent needs to know th
 
 ---
 
+## 2026-04-24: Developer Tools is a top-level sidebar item, not a section
+
+**Context:** The tools overview page (`reference/developer-tools.md`) is a toolchain catalog — not a how-to guide, concept explanation, or specification. It doesn't fit cleanly in any Diataxis quadrant. It was previously under `guides/tools/` and then considered for Reference.
+**Decision:** Expose it as a single flat top-level sidebar link between Concepts and Languages. The sidebar order is: Getting Started → Guides → Concepts → Developer Tools → Languages → Reference. The file lives at `docs/reference/developer-tools.md` with `sidebar: hidden: true` to suppress it from the Reference autogenerate; `sidebar.mjs` references it explicitly via `{ slug: "reference/developer-tools", label: "Developer Tools" }`.
+**Rationale:** A catalog page warrants top-level visibility. Placing it between Concepts and Languages follows the natural developer flow: understand the platform, know the tools, then go deep on your language. Single flat link (no collapsible) is correct while it remains one page.
+**When to revisit:** If the tools section grows to multiple pages (dedicated icp-cli reference, JS SDK getting-started, PocketIC advanced guide), convert to a collapsible group with `autogenerate` from a new `docs/tools/` directory and update this decision.
+
+---
+
 ## 2026-04-23: icp-brand-guidelines skill lives directly in the repo
 
 **Context:** The `icp-brand-guidelines` skill was added to support design/brand work on the docs (CSS tokens, typography, voice). No upstream repo exists for it yet.

docs/getting-started/choose-your-path.md

@@ -43,7 +43,7 @@ The biggest shift: on Ethereum, smart contracts are minimal programs that rely o
 
 ICP has a set of [ICP skills](https://skills.internetcomputer.org): structured knowledge files that AI agents can load to write canister code, debug deployments, and navigate the platform. If you work with tools like Claude Code, Cursor, or Copilot, ICP skills give them the context they need.
 
-**Learn more:** [AI coding agents](../guides/tools/ai-coding-agents.md)
+**Learn more:** [AI coding agents](../guides/ai-coding-agents.md)
 
 ## Backend development
 

docs/getting-started/quickstart.md

@@ -129,7 +129,7 @@ Each canister name maps to a directory containing its own `canister.yaml` with b
 - [Project structure](project-structure.md): understand how icp-cli projects are organized
 - [Choose your path](choose-your-path.md): pick a development path based on what you want to build
 - [Concepts: Canisters](../concepts/canisters.md): learn what canisters are and how they work
-- [AI coding agents](../guides/tools/ai-coding-agents.md): use ICP skills to build on the Internet Computer with AI
+- [AI coding agents](../guides/ai-coding-agents.md): use ICP skills to build on the Internet Computer with AI
 - [icp-cli documentation](https://cli.internetcomputer.org/): full CLI reference and guides
 
 <!-- Upstream: informed by dfinity/icp-cli docs/quickstart.md, docs/tutorial.md -->

docs/guides/tools/ai-coding-agents.md → docs/guides/ai-coding-agents.md

@@ -1,8 +1,6 @@
 ---
 title: "AI Coding Agents"
 description: "ICP skills are agent-readable instruction files that teach AI coding agents how to build correctly on the Internet Computer."
-sidebar:
-  order: 3
 ---
 
 AI coding agents frequently hallucinate canister IDs, use deprecated APIs, and miss ICP-specific constraints. ICP skills solve this: structured markdown files containing accurate canister IDs, tested code patterns, and documented pitfalls: so your agent writes correct ICP code on the first attempt.
@@ -47,7 +45,7 @@ Each ICP skill covers one capability area and includes:
 
 Skills are maintained by DFINITY and updated frequently. The full list is at [skills.internetcomputer.org](https://skills.internetcomputer.org).
 
-ICP skills follow the [Agent Skills](https://agentskills.io/specification) open standard: [published by Anthropic](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) in December 2025 to define a portable SKILL.md format that works across coding agents. The registry uses the [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) so agents can auto-discover and load skills without manual configuration.
+ICP skills follow the [Agent Skills open standard](https://agentskills.io/specification). Anthropic [published the SKILL.md format](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) in December 2025 to define a portable format that works across coding agents. The registry uses the [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) so agents can auto-discover and load skills without manual configuration.
 
 ## How discovery works
 
@@ -79,7 +77,7 @@ This docs site implements the [Agent-Friendly Documentation Spec](https://agentd
 
 **[`/llms.txt`](/llms.txt)**: a discovery index listing every page with links to its clean markdown endpoint, plus the ICP skills registry URL.
 
-**`/<path>.md`**: every page is available as clean markdown. HTML, navigation, and site chrome are stripped, leaving only the content. For example, this page is available at [`/guides/tools/ai-coding-agents.md`](/guides/tools/ai-coding-agents.md).
+**`/<path>.md`**: every page is available as clean markdown. HTML, navigation, and site chrome are stripped, leaving only the content. For example, this page is available at [`/guides/ai-coding-agents.md`](/guides/ai-coding-agents.md).
 
 A discovery link in every page's `<head>` points to `/llms.txt`, so agents that crawl docs pages find the index automatically.
 
@@ -95,12 +93,10 @@ ICP skills are available without authentication:
 | Skill zip bundle | `https://skills.internetcomputer.org/.well-known/skills/{name}/SKILL.zip` |
 | Skills discovery index | `https://skills.internetcomputer.org/llms.txt` |
 
-
 ## Next steps
 
 - [skills.internetcomputer.org](https://skills.internetcomputer.org): browse all available ICP skills
-- [Developer tools overview](overview.md): icp-cli, CDKs, and other tools in the ICP toolchain
-- [Quickstart](../../getting-started/quickstart.md): deploy your first canister with icp-cli
-- [Migrating from dfx](migrating-from-dfx.md): upgrade an existing project from the legacy dfx tool
+- [Developer tools](../reference/developer-tools.md): icp-cli, CDKs, and other tools in the ICP toolchain
+- [Quickstart](../getting-started/quickstart.md): deploy your first canister with icp-cli
 
 <!-- Upstream: informed by dfinity/icskills — README.md, skills/*/SKILL.md -->

docs/guides/canister-calls/offchain-calls.md

@@ -61,16 +61,7 @@ Crate documentation: [docs.rs/ic-agent](https://docs.rs/ic-agent/latest/ic_agent
 
 ### Community agents
 
-The following agents are community-maintained. Check their repositories for current status and security review history before using in production:
-
-| Language | Package |
-|----------|---------|
-| Go | [`agent-go` by Aviate Labs](https://github.com/aviate-labs/agent-go) |
-| Java / Android | [`ic4j-agent` by IC4J](https://github.com/ic4j/ic4j-agent) |
-| Dart / Flutter | [`agent_dart` by AstroX](https://github.com/AstroxNetwork/agent_dart) |
-| .NET | [`ICP.NET` by Gekctek](https://github.com/Gekctek/ICP.NET) |
-| Elixir | [`icp_agent`](https://github.com/diodechain/icp_agent) |
-| C | [`agent-c` by Zondax](https://github.com/Zondax/icp-client-cpp) |
+Community-maintained agents are available for Go, Java/Android, Dart/Flutter, .NET, Elixir, and C. See [Developer Tools](../../reference/developer-tools.md#community-agents) for the full list.
 
 ## JavaScript / TypeScript: using the agent
 

docs/guides/index.md

@@ -7,6 +7,8 @@ sidebar:
 
 Practical how-to guides organized by development stage. Each guide solves a specific task with working code.
 
+- **[AI Coding Agents](ai-coding-agents.md)**: Use ICP skills to give AI coding agents accurate canister IDs, tested code patterns, and ICP-specific context.
+
 ## Build
 
 - **[Backends](backends/data-persistence.md)**: Data persistence, HTTPS outcalls, timers, randomness, and other backend patterns.
@@ -25,7 +27,3 @@ Practical how-to guides organized by development stage. Each guide solves a spec
 - **[Chain Fusion](chain-fusion/bitcoin.md)**: Native Bitcoin, Ethereum, Solana, and Dogecoin integration.
 - **[DeFi](defi/token-ledgers.md)**: Token ledgers, chain-key tokens, and the Rosetta API.
 - **[Governance](governance/launching.md)**: Launch and manage an SNS DAO for your app.
-
-## Developer tools
-
-- **[Tools](tools/overview.md)**: Developer toolchain overview, icp-cli, CDKs, and AI coding agents with ICP skills.

docs/index.mdx

@@ -36,7 +36,7 @@ Teach your AI agent canister patterns, API integrations, CLI commands, and deplo
 
 <div class="skills-actions">
 <button class="skills-primary" id="skills-give-btn"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg><span id="skills-give-label">Give your agent ICP skills</span></button>
-<a class="skills-cta" href="/guides/tools/ai-coding-agents/"><span>Learn more</span><svg class="arrow-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 18 15 12 9 6"></polyline></svg></a>
+<a class="skills-cta" href="/guides/ai-coding-agents/"><span>Learn more</span><svg class="arrow-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 18 15 12 9 6"></polyline></svg></a>
 </div>
 
 </div>