diff --git a/AGENTS.md b/AGENTS.md
index 7a3eaa02e..b1164cf79 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,7 +11,7 @@ See [docs/architecture.mermaid](docs/architecture.mermaid) for a visual architec
- `src/cli.ts`: one-shot CLI adapter for setup, diagnostics, analysis, and decompilation.
- `src/config.ts`: Zod-validated parsing of environment configuration into `AppConfig`.
- `src/domain/`: pure, side-effect-free modules. `errors.ts` (tagged error algebra), `result.ts` (`Result`/`ok`/`err`), `hopperValues.ts` (boundary parsers for Hopper JSON), `symbolAnalysis.ts` (Swift/ObjC name parsing).
-- `src/contracts/`: caller-visible schemas for 31 direct, 8 enhanced, and 3 session tools; `enhancedInputs.ts` owns enhanced input parsing.
+- `src/contracts/`: caller-visible schemas for 33 direct, 10 enhanced, 5 native, 2 artifact, and 18 session tools; `enhancedInputs.ts` owns enhanced input parsing.
- `src/hopper/`: Hopper launch and Unix-socket protocol mechanics. `BridgeLauncher.ts` spawns the Hopper app with the in-process bridge, `HopperClient.ts` correlates request/response over the socket with timeouts and cancellation, `protocol.ts` frames bridge messages.
- `bridge/hopper_bridge.py`: runs inside Hopper and adapts declared operations to Hopper's public Python API. Hopper's bundled MCP server is not used.
- `src/application/`: shared CLI/MCP session composition, setup and diagnostics, and the 8 enhanced workflows.
@@ -34,7 +34,7 @@ See [docs/architecture.mermaid](docs/architecture.mermaid) for a visual architec
- `npm run jscpd`: detect duplicate code blocks.
- `npm run scan:todos`: scan for TODO, FIXME, and HACK markers.
- `npm run verify:hopper`: build and run the real-Hopper verifier with two distinct binaries.
-- `npm run verify:package`: pack and test the CLI, setup transaction, skill, and 42-tool target-free MCP server in an isolated environment.
+- `npm run verify:package`: pack and test the CLI, setup transaction, skill, and 68-tool target-free MCP server in an isolated environment.
- `npm run docs:generate`: generate API documentation from JSDoc comments into `docs/api/` using TypeDoc.
- `npm run config:print -- /path/to/binary`: print an MCP server config with absolute paths.
- `HOPPER_TARGET_PATH=/path/to/binary npm start`: launch Hopper and run the built stdio MCP server.
@@ -54,7 +54,7 @@ Use ESM TypeScript, two-space indentation, and Prettier defaults. Keep compiler
## Testing Guidelines
-Name tests `*.test.ts`. Use Vitest and production seams (`tests/fixtures/`) rather than module mocks. Domain tests assert pure behavior; adapter tests use the fake launcher/socket; MCP tests connect with the beta.3 client. Preserve the 31 direct, 8 enhanced, and 3 session tool inventory (42 total). Cover malformed input, cancellation, timeouts, process exit, concurrency, limits, and clean shutdown. Real Hopper claims cannot be replaced by mocks — use `npm run verify:hopper` with two distinct binaries for end-to-end verification.
+Name tests `*.test.ts`. Use Vitest and production seams (`tests/fixtures/`) rather than module mocks. Domain tests assert pure behavior; adapter tests use the fake launcher/socket; MCP tests connect with the beta.3 client. Preserve the 33 direct, 10 enhanced, 5 native, 2 artifact, and 18 session tool inventory (68 total). Cover malformed input, cancellation, timeouts, process exit, concurrency, limits, and clean shutdown. Real Hopper claims cannot be replaced by mocks — use `npm run verify:hopper` with two distinct binaries for end-to-end verification.
## Commit & Pull Request Guidelines
diff --git a/docs/architecture.mermaid b/docs/architecture.mermaid
index 7eb648e5c..d2dbe281b 100644
--- a/docs/architecture.mermaid
+++ b/docs/architecture.mermaid
@@ -1,6 +1,6 @@
graph TD
subgraph "Entry Points"
- CLI["src/cli.ts
One-shot CLI adapter
setup, diagnostics, analysis, decompilation"]
+ CLI["src/cli.ts
One-shot CLI adapter
setup, diagnostics, analysis, inventory, extraction"]
MAIN["src/main.ts
MCP stdio server adapter
config, session, process lifetime"]
DISPATCH["scripts/rea.mjs
Executable dispatcher
routes mcp / one-shot"]
end
@@ -18,12 +18,17 @@ graph TD
HOPPER["src/hopper/
Hopper launch & Unix-socket protocol
BridgeLauncher, HopperClient, protocol"]
end
+ subgraph "Provider Adapters"
+ ARTIFACTS["src/artifacts/
Directory, ZIP/APK/IPA, ASAR, Mach-O slices
safe transactional output"]
+ NATIVE["src/native/
Bounded native macOS semantic inspection"]
+ end
+
subgraph "Contracts Layer"
- CONTRACTS["src/contracts/
Caller-visible tool schemas
31 direct, 8 enhanced, 3 session tools"]
+ CONTRACTS["src/contracts/
Caller-visible tool schemas
33 direct, 10 enhanced, 5 native, 2 artifact, 18 session"]
end
subgraph "Domain Layer"
- DOMAIN["src/domain/
Pure side-effect-free modules
errors, Result, hopperValues, symbolAnalysis"]
+ DOMAIN["src/domain/
Pure side-effect-free modules
errors, Result, evidence, artifactGraph, residualUnknowns"]
end
subgraph "Configuration"
@@ -43,9 +48,14 @@ graph TD
SERVER --> CONTRACTS
SERVER --> APP
APP --> HOPPER
+ APP --> ARTIFACTS
+ APP --> NATIVE
HOPPER --> BRIDGE
APP --> DOMAIN
CONTRACTS --> DOMAIN
HOPPER --> DOMAIN
+ ARTIFACTS --> DOMAIN
+ NATIVE --> DOMAIN
TESTS -.-> MAIN
TESTS -.-> HOPPER
+ TESTS -.-> ARTIFACTS