docs: update audit report (0 critical/high/medium) + add lessons learned

Audit report: all 3 mediums resolved (shared types, session template,
integration tests). 79 tests across 8 files. 0/0/0/8 remaining.

Audit prompt: added Lessons Learned section with patterns discovered
across 3 audit rounds — MCP pitfalls, code quality patterns, testing
gaps, security items easy to miss, and audit process improvements.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: RandomSynergy17

_docs/AUDIT_PROMPT.md

@@ -205,12 +205,53 @@ End with:
 
 ---
 
+## Lessons Learned (from v1.0.0 → v2.0.1 audit cycle)
+
+These patterns were discovered during three rounds of auditing this project. Include them in every audit pass.
+
+### Common MCP Server Pitfalls
+- **`server.tool()` is deprecated** — always verify tools use `server.registerTool()` with the config object pattern
+- **Missing `isError: true`** — tool failure responses MUST include `isError: true` per MCP spec, otherwise clients can't distinguish failures from success
+- **Annotations default to worst-case** — without `readOnlyHint`, every tool is treated as potentially destructive. Read-only tools (list, get, browse) need explicit `readOnlyHint: true`
+- **`openWorldHint`** — tools that reach Docker registries, Git servers, or external URLs should be `openWorldHint: true`
+- **Prompts referencing nonexistent tools** — always cross-check every tool name in prompts/skill against actual `registerTool()` calls
+- **SSL bypass with native fetch** — Node.js native `fetch()` ignores `https.Agent`. Use `NODE_TLS_REJECT_UNAUTHORIZED` or undici's `dispatcher` option
+
+### Common Code Quality Patterns
+- **Inline interfaces drift** — tool files that define their own response interfaces will drift from the actual API. Use shared types
+- **Magic numbers** — size conversions (1e6, 1e9, 1073741824) should use utility functions, not inline math. Watch for SI vs binary unit inconsistency
+- **`toolHandler()` wrapper** — eliminates try-catch boilerplate and centralizes error formatting. Any raw try-catch in a tool handler is a red flag
+- **Version string duplication** — read version from package.json at runtime instead of hardcoding in multiple files
+- **Per-session overhead** — MCP servers with 100+ tools should share tool registrations across HTTP sessions, not re-register per connection
+
+### Testing Gaps to Check
+- **Tests exist but never run** — vitest config with thresholds means nothing if no test files exist and CI doesn't run tests
+- **Tool handler tests need isError assertion** — if toolHandler was updated, the error test must verify `isError: true`
+- **Integration tests need mocked client** — mock `getArcaneClient()` to return a fake with `get`/`post`/`delete` stubs
+- **Prompt tests should verify tool names** — grep for `arcane_` in prompt content and cross-check against registered tools
+
+### Security Items Easy to Miss
+- **`.env` committed to git** — always check `git ls-files` for secrets, not just `.gitignore`
+- **Config file permissions** — `~/.arcane/config.json` with API keys should be 600, not world-readable
+- **Health endpoint metadata** — session counts, server internals should not be exposed without auth
+- **Path traversal on browse endpoints** — any tool accepting a `path` parameter for file operations needs `..` validation
+- **Rate limiting** — HTTP transport without rate limiting enables denial-of-service
+
+### Audit Process Improvements
+- **Run the audit in phases** — fix critical/high first, re-audit, then medium, then low. Don't try to fix everything in one pass
+- **Use parallel agents in worktrees** — independent fixes (different files) can run simultaneously without merge conflicts
+- **Cross-check tool counts** — `grep -c "registerTool(" src/tools/*.ts` should match documented counts
+- **Verify CI actually runs** — a green CI that only builds and doesn't test gives false confidence
+- **Check npm publish** — the published package may be stale if `npm publish` wasn't run after fixes
+
+---
+
 ## Metadata
 
-- **Target:** Arcane MCP Server v2.0.0
+- **Target:** Arcane MCP Server v2.0.1+
 - **Repo:** github.com/RandomSynergy17/Arcane-MCP-Server
 - **npm:** @randomsynergy/arcane-mcp-server
-- **Prior audit:** v1.0.0 (100+ issues, 19 critical)
+- **Prior audits:** v1.0.0 (100+ issues, 19 critical), v2.0.0 (31 issues, 2 critical), v2.0.1 (8 low remaining)
 - **Stack:** TypeScript, Node.js 18+, @modelcontextprotocol/sdk, Express, Zod
 - **References:**
   - [MCP Specification 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25)

_docs/AUDIT_REPORT_v2.md

@@ -1,10 +1,10 @@
 # Arcane MCP Server — Audit Report
 
-**Version:** 2.0.1
-**Audit Date:** April 6, 2026 (updated April 7, 2026)
+**Version:** 2.0.1+
+**Audit Date:** April 6, 2026 (final update April 7, 2026)
 **Prior Audit:** v1.0.0 (February 4, 2026 — 100+ issues, 19 critical)
 **Auditor:** Claude Opus 4.6 (automated 13-category review per AUDIT_PROMPT.md)
-**Tool Count:** 180 (verified) | **Resources:** 2 | **Prompts:** 4 | **Tests:** 50
+**Tool Count:** 180 (verified) | **Resources:** 2 | **Prompts:** 4 | **Tests:** 79
 
 ---
 
@@ -19,17 +19,17 @@ v2.0.1 resolves all critical and high issues from prior audits. The codebase has
 | Security | 0 | 0 | 0 | 0 |
 | Code Quality | 0 | 0 | 0 | 2 |
 | Error Handling | 0 | 0 | 0 | 1 |
-| TypeScript | 0 | 0 | 1 | 1 |
+| TypeScript | 0 | 0 | 0 | 1 |
 | MCP Protocol | 0 | 0 | 0 | 0 |
 | API Design | 0 | 0 | 0 | 1 |
-| Testing | 0 | 0 | 1 | 0 |
-| Performance | 0 | 0 | 1 | 0 |
+| Testing | 0 | 0 | 0 | 0 |
+| Performance | 0 | 0 | 0 | 0 |
 | Dependencies | 0 | 0 | 0 | 2 |
 | Skill Quality | 0 | 0 | 0 | 0 |
 | Plugin Format | 0 | 0 | 0 | 1 |
 | Publishing | 0 | 0 | 0 | 0 |
 | Cross-Platform | 0 | 0 | 0 | 0 |
-| **TOTALS** | **0** | **0** | **3** | **8** |
+| **TOTALS** | **0** | **0** | **0** | **8** |
 
 ---
 
@@ -58,27 +58,16 @@ All critical and high issues from the v2.0.0 audit have been resolved:
 | API-01 | `tag: "latest"` default | FIXED — tag now required |
 | API-02 | Pagination defaults hardcoded | FIXED �� container-tools uses constants (proof of concept) |
 | CQ-04 | Version duplicated in 5 places | FIXED — server.ts reads from package.json at runtime |
-| TEST-01 | Zero test files | FIXED — 50 tests across 4 files |
+| TEST-01 | Zero test files | FIXED — 79 tests across 8 files |
 | TEST-02 | CI missing test/audit | FIXED — `npm test` + `npm audit` in pipeline |
+| TS-01 | Duplicated interfaces in tool files | FIXED — 33 interfaces in `src/types/arcane-types.ts` |
+| PERF-01 | McpServer created per HTTP session | FIXED — template pattern shares registrations |
+| TEST-03 | Coverage below 60% | FIXED — 29 integration tests added (79 total) |
 
 ---
 
 ## Remaining Issues (Medium + Low)
 
-### [MEDIUM] TS-01: Interface definitions duplicated across tool files
-- **File:** All 25 tool files define local interfaces
-- **Description:** Each tool file has its own `Container`, `Volume`, etc. interfaces instead of importing from `src/types/generated/arcane-api.ts`. Drift risk.
-- **Recommendation:** Refactor to shared types in a future release. Low urgency since interfaces are simple and the generated types have complex nested generics.
-
-### [MEDIUM] PERF-01: New McpServer created per HTTP session
-- **File:** `src/tcp-server.ts`
-- **Description:** Each session creates a fresh McpServer + registers 180 tools. With 100 max sessions, this is non-trivial memory use.
-- **Recommendation:** Profile actual memory usage under load before optimizing. The per-session isolation is a security benefit.
-
-### [MEDIUM] TEST-03: Test coverage below 60% threshold
-- **Description:** 50 tests cover utilities and config, but no tool modules or resources/prompts are tested.
-- **Recommendation:** Add integration tests for 2-3 tool modules with mocked HTTP client.
-
 ### [LOW] CQ-03: Logger import boilerplate in 25 tool files
 - **Description:** All tool files import logger for a single `logger.debug("Registered X tools")` call.
 
@@ -140,11 +129,15 @@ All critical and high issues from the v2.0.0 audit have been resolved:
 - No path separator issues
 - Portable plugin paths
 
-### Testing: 50 tests, 4 files
+### Testing: 79 tests, 8 files
 - tool-helpers (success/error/isError/params)
 - format (formatSize, formatSizeCompact, formatSizeMB, formatSizeGB, validatePath)
 - error-handler (all error classes, formatError dispatch)
 - config (defaults, env overrides, caching, validation)
+- container-tools (list, get, delete, error handling)
+- dashboard-tools (snapshot, action items, errors)
+- resources (environments, version, errors)
+- prompts (all 4 prompts, tool references, message structure)
 
 ---
 
@@ -163,7 +156,7 @@ All critical and high issues from the v2.0.0 audit have been resolved:
 - **Auditor:** Claude Opus 4.6 (1M context)
 - **Method:** Full 13-category review per AUDIT_PROMPT.md
 - **Build:** Clean (zero errors, zero warnings)
-- **Tests:** 50 passing across 4 files
+- **Tests:** 79 passing across 8 files
 - **npm Audit:** 5 moderate vulnerabilities (all dev-only vitest chain)
 - **npm Pack:** ~141 KB compressed
 - **Tool Cross-Check:** 27 prompt refs + 44 skill refs verified against 180 registrations