npm - agentic-flow - Versions diffs - 2.0.1 → 2.0.2-alpha - Mend

agentic-flow 2.0.1 → 2.0.2-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1851) hide show

package/package.json CHANGED Viewed

@@ -1,63 +1,89 @@
 {
   "name": "agentic-flow",
-  "version": "2.0.1",
-  "description": "Production-ready AI agent orchestration platform with 66 specialized agents, 213 MCP tools, ReasoningBank learning memory, and autonomous multi-agent swarms. Built by @ruvnet with Claude Agent SDK, neural networks, memory persistence, GitHub integration, and distributed consensus protocols.",
+  "version": "2.0.2-alpha",
+  "description": "Production-ready AI agent orchestration platform with 66 specialized agents, 213 MCP tools, ReasoningBank learning memory, quantum-resistant Jujutsu VCS, and autonomous multi-agent swarms. Built by @ruvnet with Claude Agent SDK, neural networks, memory persistence, GitHub integration, and distributed consensus protocols.",
   "type": "module",
-  "main": "dist/index.js",
+  "main": "agentic-flow/dist/index.js",
+  "types": "agentic-flow/dist/index.d.ts",
   "bin": {
-    "agentic-flow": "dist/cli-proxy.js",
-    "agentdb": "dist/agentdb/cli/agentdb-cli.js"
+    "agentic-flow": "agentic-flow/dist/cli-proxy.js",
+    "agentdb": "agentic-flow/dist/agentdb/cli/agentdb-cli.js",
+    "ajj-billing": "agentic-flow/dist/billing/cli.js",
+    "agentic-jujutsu": "packages/agentic-jujutsu/bin/cli.js",
+    "jj-agent": "packages/agentic-jujutsu/bin/cli.js"
   },
   "exports": {
-    ".": "./dist/index.js",
+    ".": "./agentic-flow/dist/index.js",
+    "./package.json": "./package.json",
+    "./wrappers": "./agentic-flow/dist/core/index.js",
+    "./wrappers/gnn": "./agentic-flow/dist/core/gnn-wrapper.js",
+    "./wrappers/agentdb-fast": "./agentic-flow/dist/core/agentdb-fast.js",
+    "./wrappers/attention": "./agentic-flow/dist/core/attention-fallbacks.js",
+    "./wrappers/embedding": "./agentic-flow/dist/core/embedding-service.js",
     "./reasoningbank": {
-      "node": "./dist/reasoningbank/index.js",
-      "browser": "./dist/reasoningbank/wasm-adapter.js",
-      "default": "./dist/reasoningbank/index.js"
+      "node": "./agentic-flow/dist/reasoningbank/index.js",
+      "browser": "./agentic-flow/dist/reasoningbank/wasm-adapter.js",
+      "default": "./agentic-flow/dist/reasoningbank/index.js"
     },
-    "./reasoningbank/backend-selector": "./dist/reasoningbank/backend-selector.js",
-    "./reasoningbank/wasm-adapter": "./dist/reasoningbank/wasm-adapter.js",
-    "./router": "./dist/router/index.js",
-    "./agent-booster": "./dist/agent-booster/index.js",
-    "./transport/quic": "./dist/transport/quic.js",
-    "./embeddings": "./dist/embeddings/index.js"
+    "./reasoningbank/backend-selector": "./agentic-flow/dist/reasoningbank/backend-selector.js",
+    "./reasoningbank/wasm-adapter": "./agentic-flow/dist/reasoningbank/wasm-adapter.js",
+    "./router": "./agentic-flow/dist/router/index.js",
+    "./agent-booster": "./agentic-flow/dist/agent-booster/index.js",
+    "./transport/quic": "./agentic-flow/dist/transport/quic.js",
+    "./agentdb": "./agentic-flow/dist/agentdb/index.js",
+    "./billing": "./agentic-flow/dist/billing/index.js",
+    "./agentic-jujutsu": {
+      "require": "./packages/agentic-jujutsu/index.js",
+      "import": "./packages/agentic-jujutsu/index.js",
+      "types": "./packages/agentic-jujutsu/index.d.ts"
+    },
+    "./agentic-jujutsu/quantum": {
+      "require": "./packages/agentic-jujutsu/src/quantum_bridge.js",
+      "import": "./packages/agentic-jujutsu/src/quantum_bridge.js",
+      "types": "./packages/agentic-jujutsu/quantum-bridge.d.ts"
+    }
   },
   "scripts": {
-    "postinstall": "node scripts/postinstall.js || true",
-    "start": "node --enable-source-maps dist/index.js",
-    "build": "(npm run build:wasm || true) && (tsc -p config/tsconfig.json --skipLibCheck || true) && mkdir -p dist/reasoningbank && (cp -r src/reasoningbank/prompts dist/reasoningbank/ 2>/dev/null || true) && (cp -r src/reasoningbank/config dist/reasoningbank/ 2>/dev/null || true)",
-    "build:wasm": "cd ../reasoningbank && wasm-pack build --target bundler --out-dir pkg/bundler crates/reasoningbank-wasm && wasm-pack build --target web --out-dir pkg/web crates/reasoningbank-wasm && mkdir -p ../agentic-flow/wasm/reasoningbank && cp -r crates/reasoningbank-wasm/pkg/bundler/* ../agentic-flow/wasm/reasoningbank/ && cp -r crates/reasoningbank-wasm/pkg/web ../agentic-flow/wasm/reasoningbank/",
-    "build:wasm:clean": "rm -rf ../reasoningbank/crates/reasoningbank-wasm/pkg && rm -rf wasm/reasoningbank",
-    "dev": "tsx src/index.ts",
-    "prepublishOnly": "npm run build",
-    "test": "npm run test:retry && npm run test:logging",
-    "test:retry": "tsx validation/quick-wins/test-retry.ts",
-    "test:logging": "tsx validation/quick-wins/test-logging.ts",
-    "test:wasm:e2e": "tsx validation/test-wasm-e2e.ts",
-    "test:wasm:docker": "docker build -f Dockerfile.e2e -t agentic-flow-e2e . && docker run --rm agentic-flow-e2e",
-    "validate": "tsx validation/quick-wins/validate-all.ts",
-    "validate:sdk": "tsx validation/sdk-integration-test.ts",
-    "validate:health": "bash validation/quick-wins/test-health.sh",
-    "validate:openrouter": "tsx tests/validation/test-openrouter-fixes.ts",
-    "validate:claude-flow": "npm run test:memory && npm run test:coordination && npm run test:hybrid",
-    "test:memory": "tsx tests/validation/claude-flow/test-memory.ts",
-    "test:coordination": "tsx tests/validation/claude-flow/test-coordination.ts",
-    "test:hybrid": "tsx tests/validation/claude-flow/test-hybrid.ts",
-    "test:fastmcp": "bash scripts/test-fastmcp-poc.sh",
-    "test:quic": "tsx validation/test-quic-integration.ts",
-    "test:quic:wasm": "tsx validation/test-quic-wasm.ts",
-    "mcp:fastmcp-poc": "node dist/mcp/fastmcp/servers/poc-stdio.js",
-    "mcp:http": "node dist/mcp/fastmcp/servers/http-sse.js",
-    "mcp:stdio": "node dist/mcp/standalone-stdio.js",
-    "claude-code": "node dist/cli/claude-code-wrapper.js",
-    "example:goal-planner": "tsx src/examples/use-goal-planner.ts",
-    "example:multi-agent": "tsx src/examples/multi-agent-orchestration.ts",
-    "example:embedding-geometry": "tsx src/examples/embedding-geometry.ts",
-    "proxy": "node dist/proxy/anthropic-to-openrouter.js",
-    "proxy:dev": "tsx src/proxy/anthropic-to-openrouter.ts",
-    "proxy:quic": "node dist/proxy/quic-proxy.js",
-    "proxy:quic:dev": "tsx src/proxy/quic-proxy.ts",
-    "benchmark:embeddings": "tsx src/benchmarks/embeddings-benchmark.ts"
+    "postinstall": "cd agentic-flow && node scripts/postinstall.js || true",
+    "prepare": "bash scripts/setup-husky.sh || true",
+    "build": "npm run build:main && npm run build:packages",
+    "build:main": "cd agentic-flow && npm run build",
+    "build:packages": "npm run build:agent-booster && npm run build:reasoningbank && npm run build:jujutsu",
+    "build:agent-booster": "cd packages/agent-booster && npm run build || true",
+    "build:reasoningbank": "cd packages/reasoningbank && npm run build || true",
+    "build:jujutsu": "cd packages/agentic-jujutsu && npm run build || echo 'Jujutsu uses pre-built binaries'",
+    "test": "npm run test:main && npm run test:parallel",
+    "test:main": "cd agentic-flow && npm test",
+    "test:billing": "npx tsx test/billing/billing-system.test.ts",
+    "test:parallel": "node tests/parallel/benchmark-suite.js",
+    "test:mesh": "node tests/parallel/mesh-swarm-test.js",
+    "test:hierarchical": "node tests/parallel/hierarchical-swarm-test.js",
+    "test:ring": "node tests/parallel/ring-swarm-test.js",
+    "test:coverage": "jest --coverage --config=config/jest.config.js",
+    "test:watch": "jest --watch --config=config/jest.config.js",
+    "coverage:check": "jest --coverage --config=config/jest.config.js --coverageThreshold='{\"global\":{\"branches\":80,\"functions\":80,\"lines\":80,\"statements\":80}}'",
+    "bench:quic": "node benchmarks/quic-transport.bench.js",
+    "bench:report": "node scripts/generate-benchmark-report.js",
+    "bench:parallel": "BENCHMARK_MODE=true ITERATIONS=10 node tests/parallel/benchmark-suite.js",
+    "bench:attention": "node benchmarks/attention-gnn-benchmark.js",
+    "bench:sona": "npx tsx tests/sona/sona-performance.bench.ts",
+    "bench:sona:quick": "BENCHMARK_QUICK=1 npx tsx tests/sona/sona-performance.bench.ts",
+    "bench:sona:gc": "node --expose-gc --loader tsx tests/sona/benchmark-runner.ts --gc",
+    "test:attention": "jest tests/integration/attention-gnn.test.ts --config=config/jest.config.cjs",
+    "docker:test": "cd tests/docker && docker-compose -f docker-compose.parallel.yml up --build",
+    "docker:bench": "cd tests/docker && docker-compose -f docker-compose.parallel.yml up --build benchmark",
+    "profile": "0x -- node benchmarks/quic-transport.bench.js",
+    "lint": "eslint . --ext .ts,.js --config config/.eslintrc.strict.js",
+    "lint:fix": "eslint . --ext .ts,.js --config config/.eslintrc.strict.js --fix",
+    "lint:report": "eslint . --ext .ts,.js --config config/.eslintrc.strict.js --format json --output-file eslint-report.json",
+    "format": "prettier --write --config config/.prettierrc.js \"**/*.{ts,js,json,md,yml,yaml}\" --ignore-path config/.prettierignore",
+    "format:check": "prettier --check --config config/.prettierrc.js \"**/*.{ts,js,json,md,yml,yaml}\" --ignore-path config/.prettierignore",
+    "typecheck": "tsc --noEmit --project ./agentic-flow/config/tsconfig.json",
+    "typecheck:strict": "tsc --noEmit --project ./agentic-flow/config/tsconfig.strict.json",
+    "complexity": "npx complexity-report --format json --output complexity-report.json agentic-flow/src/**/*.ts || echo 'Complexity report generated'",
+    "quality:check": "npm run lint && npm run format:check && npm run typecheck:strict && npm run test:coverage",
+    "quality:fix": "npm run lint:fix && npm run format",
+    "prepublishOnly": "npm run build || true"
   },
   "keywords": [
     "ai",
@@ -92,6 +118,11 @@
     "goap",
     "hive-mind",
     "huggingface",
+    "jujutsu",
+    "jujutsu-vcs",
+    "quantum-resistant",
+    "quantum-cryptography",
+    "quantumdag",
     "llm",
     "llm-orchestration",
     "machine-learning",
@@ -108,6 +139,7 @@
     "orchestration",
     "pagerank",
     "parallel-processing",
+    "quic",
     "raft",
     "ruv",
     "ruvnet",
@@ -117,11 +149,14 @@
     "swarm-intelligence",
     "task-orchestration",
     "typescript",
+    "version-control",
+    "vcs",
     "workflow",
     "workflow-automation"
   ],
   "author": {
     "name": "ruv",
+    "email": "contact@ruv.io",
     "url": "https://github.com/ruvnet"
   },
   "contributors": [
@@ -140,71 +175,104 @@
   },
   "homepage": "https://github.com/ruvnet/agentic-flow#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.0.0",
+    "npm": ">=8.0.0"
   },
+  "files": [
+    "agentic-flow/dist",
+    "agentic-flow/docs",
+    "agentic-flow/.claude",
+    "agentic-flow/wasm",
+    "agentic-flow/certs",
+    "agentic-flow/scripts",
+    "agent-booster/dist",
+    "reasoningbank/dist",
+    "packages/agentic-jujutsu",
+    "docs/AGENTIC_JUJUTSU_QUICKSTART.md",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.1.5",
+    "@anthropic-ai/claude-code": "^2.0.35",
     "@anthropic-ai/sdk": "^0.65.0",
     "@google/genai": "^1.22.0",
-    "@ruvector/core": "^0.1.29",
-    "@ruvector/edge-full": "^0.1.0",
-    "@ruvector/router": "^0.1.25",
-    "@ruvector/ruvllm": "^0.2.3",
-    "@ruvector/tiny-dancer": "^0.1.15",
+    "@ruvector/attention": "^0.1.2",
+    "@ruvector/gnn": "^0.1.21",
+    "@ruvector/ruvllm": "^0.2.0",
+    "@ruvector/sona": "^0.1.3",
     "@supabase/supabase-js": "^2.78.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "@vitejs/plugin-react-swc": "^4.2.0",
     "@xenova/transformers": "^2.17.2",
+    "agentdb": "^2.0.0-alpha.2.11",
+    "agentic-payments": "^0.1.13",
+    "autoprefixer": "^10.4.21",
     "axios": "^1.12.2",
+    "better-sqlite3": "^11.10.0",
     "dotenv": "^16.4.5",
     "express": "^5.1.0",
     "fastmcp": "^3.19.0",
-    "glob": "^13.0.0",
-    "gun": "^0.2020.1241",
     "http-proxy-middleware": "^3.0.5",
-    "ruvector": "^0.1.85",
-    "ruvector-onnx-embeddings-wasm": "^0.1.2",
+    "lucide-react": "^0.548.0",
+    "postcss": "^8.5.6",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^7.9.4",
+    "tailwindcss": "^4.1.16",
+    "tailwindcss-animate": "^1.0.7",
     "tiktoken": "^1.0.22",
     "ulid": "^3.0.1",
+    "vite": "^7.1.12",
     "ws": "^8.18.3",
     "yaml": "^2.8.1",
     "zod": "^3.25.76"
   },
-  "optionalDependencies": {
-    "@ruvector/attention": "^0.1.4",
-    "@ruvector/sona": "^0.1.4",
-    "agentdb": "^2.0.0-alpha.3.4",
-    "better-sqlite3": "^11.10.0",
-    "onnxruntime-node": "^1.23.2",
-    "sharp": "^0.32.6",
-    "sql.js": "^1.11.0"
-  },
-  "overrides": {
-    "@xenova/transformers": {
-      "sharp": "$sharp"
-    }
-  },
   "devDependencies": {
+    "@commitlint/cli": "^20.1.0",
+    "@commitlint/config-conventional": "^20.0.0",
+    "@e2b/code-interpreter": "^2.3.1",
     "@types/better-sqlite3": "^7.6.13",
+    "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
+    "@types/helmet": "^4.0.0",
+    "@types/inquirer": "^9.0.9",
+    "@types/jest": "^29.5.8",
     "@types/node": "^20.19.19",
     "@types/uuid": "^11.0.0",
     "@types/ws": "^8.18.1",
-    "@vitest/coverage-v8": "^4.0.14",
-    "patch-package": "^8.0.1",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "0x": "^5.6.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.2",
+    "eslint-plugin-prettier": "^5.5.4",
+    "husky": "^8.0.3",
+    "jest": "^29.7.0",
+    "lint-staged": "^15.5.2",
+    "prettier": "^3.7.3",
+    "ts-jest": "^29.1.1",
     "tsx": "^4.19.0",
-    "typescript": "^5.6.3",
-    "vitest": "^4.0.14"
+    "typescript": "^5.9.3"
   },
-  "files": [
-    "dist",
-    "docs",
-    ".claude",
-    "validation",
-    "scripts",
-    "wasm",
-    "certs",
-    "README.md",
-    "LICENSE",
-    "VALIDATION-RESULTS.md",
-    "CHANGELOG.md"
-  ]
+  "peerDependencies": {
+    "claude-flow": "^2.7.0",
+    "flow-nexus": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "claude-flow": {
+      "optional": true
+    },
+    "flow-nexus": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@ruvector/attention-linux-x64-gnu": "^0.1.1",
+    "@ruvector/attention-darwin-arm64": "^0.1.1",
+    "@ruvector/attention-darwin-x64": "^0.1.1",
+    "@ruvector/attention-win32-x64-msvc": "^0.1.1"
+  }
 }

package/packages/agentic-jujutsu/.cargo/config.toml ADDED Viewed

@@ -0,0 +1,14 @@
+[target.x86_64-apple-darwin]
+rustflags = [
+  "-C", "link-arg=-undefined",
+  "-C", "link-arg=dynamic_lookup",
+]
+[target.aarch64-apple-darwin]
+rustflags = [
+  "-C", "link-arg=-undefined",
+  "-C", "link-arg=dynamic_lookup",
+]
+[target.x86_64-pc-windows-msvc]
+rustflags = ["-C", "link-arg=/FORCE:UNRESOLVED"]

package/packages/agentic-jujutsu/BUILD.md ADDED Viewed

@@ -0,0 +1,292 @@
+# Building agentic-jujutsu Native Binaries
+This document explains how to build and publish agentic-jujutsu with native binaries for all supported platforms.
+## Supported Platforms
+agentic-jujutsu supports 8 platforms through NAPI-RS:
+1. **Linux x64 GNU** (`linux-x64-gnu`) - Standard Linux distributions
+2. **Linux ARM64 GNU** (`linux-arm64-gnu`) - ARM64 Linux (Raspberry Pi 4+)
+3. **Linux x64 MUSL** (`linux-x64-musl`) - Alpine Linux x64
+4. **Linux ARM64 MUSL** (`linux-arm64-musl`) - Alpine Linux ARM64
+5. **Linux ARMv7** (`linux-arm-gnueabihf`) - ARM32 devices
+6. **macOS x64** (`darwin-x64`) - Intel Macs
+7. **macOS ARM64** (`darwin-arm64`) - Apple Silicon Macs (M1/M2/M3)
+8. **Windows x64** (`win32-x64-msvc`) - Windows 64-bit
+## Automated Builds via GitHub Actions
+The repository includes a GitHub Actions workflow that automatically builds binaries for all platforms.
+### Workflow: `.github/workflows/build-agentic-jujutsu.yml`
+**Triggers:**
+- Push to `main` branch (paths: `packages/agentic-jujutsu/**`)
+- Pull requests to `main`
+- Tags matching `agentic-jujutsu-v*` (e.g., `agentic-jujutsu-v2.3.6`)
+- Manual workflow dispatch
+**Build Matrix:**
+- Uses ubuntu-22.04 for all Linux builds
+- Uses macos-13 for Intel Mac builds
+- Uses macos-14 for Apple Silicon builds
+- Uses windows-2022 for Windows builds
+**Process:**
+1. Checks out code
+2. Sets up Node.js 20 and Rust toolchain
+3. Installs cross-compilation tools (for ARM targets)
+4. Builds native module with `napi build`
+5. Tests on native platforms
+6. Uploads artifacts
+### Publishing Process
+When a tag `agentic-jujutsu-v*` is pushed, the workflow automatically:
+1. **Downloads all platform binaries** from build artifacts
+2. **Creates platform-specific packages**:
+   - `agentic-jujutsu-darwin-x64`
+   - `agentic-jujutsu-darwin-arm64`
+   - `agentic-jujutsu-linux-x64-gnu`
+   - `agentic-jujutsu-linux-x64-musl`
+   - `agentic-jujutsu-linux-arm64-gnu`
+   - `agentic-jujutsu-linux-arm64-musl`
+   - `agentic-jujutsu-linux-arm-gnueabihf`
+   - `agentic-jujutsu-win32-x64-msvc`
+3. **Publishes platform packages** to npm
+4. **Publishes main package** with optionalDependencies
+## Manual Build Instructions
+### Prerequisites
+- Node.js 16+ (recommended: 20)
+- Rust toolchain (via rustup)
+- NAPI-RS CLI: `npm install -g @napi-rs/cli`
+### Building for Your Platform
+```bash
+cd packages/agentic-jujutsu
+npm install
+npm run build  # or: napi build --platform --release
+```
+This creates a `.node` file for your current platform:
+- `agentic-jujutsu.linux-x64-gnu.node` (on Linux)
+- `agentic-jujutsu.darwin-arm64.node` (on Apple Silicon Mac)
+- etc.
+### Cross-Compilation (Advanced)
+#### Linux ARM64 from x64:
+```bash
+# Install cross-compilation tools
+sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
+# Add target
+rustup target add aarch64-unknown-linux-gnu
+# Build
+CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc \
+  napi build --platform --release --target aarch64-unknown-linux-gnu
+```
+#### MUSL targets:
+```bash
+# Install musl tools
+sudo apt-get install musl-tools
+# Add target
+rustup target add x86_64-unknown-linux-musl
+# Build
+napi build --platform --release --target x86_64-unknown-linux-musl
+```
+## Releasing a New Version
+### Step 1: Update Version
+```bash
+cd packages/agentic-jujutsu
+npm version 2.3.6  # or patch/minor/major
+```
+### Step 2: Create and Push Tag
+```bash
+git add package.json
+git commit -m "chore: bump agentic-jujutsu to v2.3.6"
+git tag agentic-jujutsu-v2.3.6
+git push origin main --tags
+```
+### Step 3: Monitor GitHub Actions
+1. Go to: https://github.com/ruvnet/agentic-flow/actions
+2. Watch the "Build Agentic-Jujutsu Native Modules" workflow
+3. Verify all 8 platforms build successfully
+4. Verify publish job completes
+### Step 4: Verify npm Packages
+```bash
+# Check main package
+npm view agentic-jujutsu@2.3.6
+# Check platform packages
+npm view agentic-jujutsu-darwin-arm64@2.3.6
+npm view agentic-jujutsu-linux-x64-gnu@2.3.6
+# ... etc for all 8 platforms
+```
+## Testing Installation
+### Test on Your Platform
+```bash
+npm install agentic-jujutsu@2.3.6
+node -e "const {JjWrapper} = require('agentic-jujutsu'); console.log('✓ Loaded')"
+```
+### Test Platform-Specific Package
+```bash
+npm install agentic-jujutsu-darwin-arm64@2.3.6
+ls node_modules/agentic-jujutsu-darwin-arm64/*.node
+```
+## Troubleshooting
+### Build Fails on ARM Targets
+Ensure cross-compilation tools are installed:
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+  gcc-aarch64-linux-gnu \
+  g++-aarch64-linux-gnu \
+  gcc-arm-linux-gnueabihf \
+  g++-arm-linux-gnueabihf
+```
+### Wrong .node File Name
+NAPI-RS creates files with platform suffix. The workflow handles mapping:
+- Build output: `agentic-jujutsu.linux-x64-gnu.node`
+- Artifact location: `npm/linux-x64-gnu/agentic-jujutsu.linux-x64-gnu.node`
+### Platform Package Not Found
+Platform packages must be published BEFORE the main package. The workflow does this automatically, but for manual publishing:
+```bash
+# 1. Build all platforms
+# 2. Publish platform packages first
+cd npm/darwin-arm64
+npm publish --access public
+# 3. Then publish main package
+cd ../..
+npm publish --access public
+```
+## Architecture
+### NAPI-RS Structure
+```
+packages/agentic-jujutsu/
+├── src/                       # Rust source code
+│   ├── lib.rs                 # NAPI bindings
+│   ├── operations.rs          # Jujutsu operations
+│   └── ...
+├── index.js                   # JavaScript entry point
+├── index.d.ts                 # TypeScript definitions
+├── *.node                     # Built native modules (gitignored)
+└── npm/                       # Platform packages (created by CI)
+    ├── darwin-arm64/
+    │   ├── package.json
+    │   └── agentic-jujutsu.darwin-arm64.node
+    ├── linux-x64-gnu/
+    │   ├── package.json
+    │   └── agentic-jujutsu.linux-x64-gnu.node
+    └── ...
+```
+### Loading Mechanism
+The main `index.js` checks your platform and loads the appropriate `.node` file:
+1. Tries local file (e.g., `./agentic-jujutsu.darwin-arm64.node`)
+2. Falls back to platform package (e.g., `require('agentic-jujutsu-darwin-arm64')`)
+This is why optionalDependencies are needed in `package.json`.
+## CI/CD Environment Variables
+The workflow requires the following GitHub secret:
+- `NPM_TOKEN` - npm access token with publish permissions
+**CRITICAL**: The automated workflow will fail without this secret configured. All platform builds will succeed, but the publish job will fail with `ENEEDAUTH` errors.
+To set up:
+1. Generate token at https://www.npmjs.com/settings/YOUR_USERNAME/tokens
+   - Token type: "Automation" (for CI/CD)
+   - Permissions: "Read and write" (for publishing)
+2. Add as repository secret at https://github.com/ruvnet/agentic-flow/settings/secrets/actions
+   - Name: `NPM_TOKEN`
+   - Value: Your npm automation token
+3. Verify in workflow runs that `NODE_AUTH_TOKEN` is set (masked in logs)
+### Manual Publishing (if NPM_TOKEN not configured)
+If the GitHub secret is not configured, you can publish manually after builds complete:
+```bash
+# Wait for all 8 platform builds to complete
+gh run watch <run-id>
+# Download artifacts
+gh run download <run-id> -D /tmp/artifacts
+# Build local binary
+cd packages/agentic-jujutsu
+npm install
+npm run build
+# Publish (requires npm login)
+npm whoami  # Verify authentication
+npm publish --access public
+```
+The main package includes the linux-x64-gnu binary by default, so it will work on Linux platforms immediately after manual publishing.
+## Performance Notes
+### Build Times (approximate)
+- Linux x64 GNU: ~3-4 minutes
+- Linux ARM64 (cross): ~4-5 minutes
+- macOS x64: ~4-5 minutes
+- macOS ARM64: ~3-4 minutes
+- Windows x64: ~5-6 minutes
+- MUSL targets: ~4-5 minutes
+### Binary Sizes
+- Linux GNU: ~27 MB
+- Linux MUSL: ~28 MB
+- macOS: ~4-5 MB (Apple's stripping)
+- Windows: ~4-5 MB
+## References
+- NAPI-RS Documentation: https://napi.rs/
+- GitHub Actions: https://docs.github.com/en/actions
+- Cross-compilation: https://rust-lang.github.io/rustup/cross-compilation.html