@newtype-os/cli 0.0.0-main-202603270907

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 opencode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/bin/nt

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+const childProcess = require("child_process")
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+
+function run(target) {
+  const result = childProcess.spawnSync(target, process.argv.slice(2), {
+    stdio: "inherit",
+  })
+  if (result.error) {
+    console.error(result.error.message)
+    process.exit(1)
+  }
+  const code = typeof result.status === "number" ? result.status : 0
+  process.exit(code)
+}
+
+const envPath = process.env.OPENCODE_BIN_PATH
+if (envPath) {
+  run(envPath)
+}
+
+const scriptPath = fs.realpathSync(__filename)
+const scriptDir = path.dirname(scriptPath)
+
+const platformMap = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+}
+const archMap = {
+  x64: "x64",
+  arm64: "arm64",
+  arm: "arm",
+}
+
+let platform = platformMap[os.platform()]
+if (!platform) {
+  platform = os.platform()
+}
+let arch = archMap[os.arch()]
+if (!arch) {
+  arch = os.arch()
+}
+const base = "@newtype-os/cli-" + platform + "-" + arch
+const binary = platform === "windows" ? "nt.exe" : "nt"
+
+function supportsAvx2() {
+  if (arch !== "x64") return false
+
+  if (platform === "linux") {
+    try {
+      return /(^|\s)avx2(\s|$)/i.test(fs.readFileSync("/proc/cpuinfo", "utf8"))
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === "darwin") {
+    try {
+      const result = childProcess.spawnSync("sysctl", ["-n", "hw.optional.avx2_0"], {
+        encoding: "utf8",
+        timeout: 1500,
+      })
+      if (result.status !== 0) return false
+      return (result.stdout || "").trim() === "1"
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === "windows") {
+    const cmd =
+      '(Add-Type -MemberDefinition "[DllImport(""kernel32.dll"")] public static extern bool IsProcessorFeaturePresent(int ProcessorFeature);" -Name Kernel32 -Namespace Win32 -PassThru)::IsProcessorFeaturePresent(40)'
+
+    for (const exe of ["powershell.exe", "pwsh.exe", "pwsh", "powershell"]) {
+      try {
+        const result = childProcess.spawnSync(exe, ["-NoProfile", "-NonInteractive", "-Command", cmd], {
+          encoding: "utf8",
+          timeout: 3000,
+          windowsHide: true,
+        })
+        if (result.status !== 0) continue
+        const out = (result.stdout || "").trim().toLowerCase()
+        if (out === "true" || out === "1") return true
+        if (out === "false" || out === "0") return false
+      } catch {
+        continue
+      }
+    }
+
+    return false
+  }
+
+  return false
+}
+
+const names = (() => {
+  const avx2 = supportsAvx2()
+  const baseline = arch === "x64" && !avx2
+
+  if (platform === "linux") {
+    const musl = (() => {
+      try {
+        if (fs.existsSync("/etc/alpine-release")) return true
+      } catch {
+        // ignore
+      }
+
+      try {
+        const result = childProcess.spawnSync("ldd", ["--version"], { encoding: "utf8" })
+        const text = ((result.stdout || "") + (result.stderr || "")).toLowerCase()
+        if (text.includes("musl")) return true
+      } catch {
+        // ignore
+      }
+
+      return false
+    })()
+
+    if (musl) {
+      if (arch === "x64") {
+        if (baseline) return [`${base}-baseline-musl`, `${base}-musl`, `${base}-baseline`, base]
+        return [`${base}-musl`, `${base}-baseline-musl`, base, `${base}-baseline`]
+      }
+      return [`${base}-musl`, base]
+    }
+
+    if (arch === "x64") {
+      if (baseline) return [`${base}-baseline`, base, `${base}-baseline-musl`, `${base}-musl`]
+      return [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`]
+    }
+    return [base, `${base}-musl`]
+  }
+
+  if (arch === "x64") {
+    if (baseline) return [`${base}-baseline`, base]
+    return [base, `${base}-baseline`]
+  }
+  return [base]
+})()
+
+function findBinary(startDir) {
+  let current = startDir
+  for (;;) {
+    const modules = path.join(current, "node_modules")
+    if (fs.existsSync(modules)) {
+      for (const name of names) {
+        const candidate = path.join(modules, name, "bin", binary)
+        if (fs.existsSync(candidate)) return candidate
+      }
+    }
+    const parent = path.dirname(current)
+    if (parent === current) {
+      return
+    }
+    current = parent
+  }
+}
+
+const resolved = findBinary(scriptDir)
+if (!resolved) {
+  console.error(
+    "It seems that your package manager failed to install the right version of the Newtype CLI for your platform. You can try manually installing " +
+      names.map((n) => `\"${n}\"`).join(" or ") +
+      " package",
+  )
+  process.exit(1)
+}
+
+run(resolved)

package/bin/nt

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+const childProcess = require("child_process")
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+
+function run(target) {
+  const result = childProcess.spawnSync(target, process.argv.slice(2), {
+    stdio: "inherit",
+  })
+  if (result.error) {
+    console.error(result.error.message)
+    process.exit(1)
+  }
+  const code = typeof result.status === "number" ? result.status : 0
+  process.exit(code)
+}
+
+const envPath = process.env.OPENCODE_BIN_PATH
+if (envPath) {
+  run(envPath)
+}
+
+const scriptPath = fs.realpathSync(__filename)
+const scriptDir = path.dirname(scriptPath)
+
+const platformMap = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+}
+const archMap = {
+  x64: "x64",
+  arm64: "arm64",
+  arm: "arm",
+}
+
+let platform = platformMap[os.platform()]
+if (!platform) {
+  platform = os.platform()
+}
+let arch = archMap[os.arch()]
+if (!arch) {
+  arch = os.arch()
+}
+const base = "@newtype-os/cli-" + platform + "-" + arch
+const binary = platform === "windows" ? "nt.exe" : "nt"
+
+function supportsAvx2() {
+  if (arch !== "x64") return false
+
+  if (platform === "linux") {
+    try {
+      return /(^|\s)avx2(\s|$)/i.test(fs.readFileSync("/proc/cpuinfo", "utf8"))
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === "darwin") {
+    try {
+      const result = childProcess.spawnSync("sysctl", ["-n", "hw.optional.avx2_0"], {
+        encoding: "utf8",
+        timeout: 1500,
+      })
+      if (result.status !== 0) return false
+      return (result.stdout || "").trim() === "1"
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === "windows") {
+    const cmd =
+      '(Add-Type -MemberDefinition "[DllImport(""kernel32.dll"")] public static extern bool IsProcessorFeaturePresent(int ProcessorFeature);" -Name Kernel32 -Namespace Win32 -PassThru)::IsProcessorFeaturePresent(40)'
+
+    for (const exe of ["powershell.exe", "pwsh.exe", "pwsh", "powershell"]) {
+      try {
+        const result = childProcess.spawnSync(exe, ["-NoProfile", "-NonInteractive", "-Command", cmd], {
+          encoding: "utf8",
+          timeout: 3000,
+          windowsHide: true,
+        })
+        if (result.status !== 0) continue
+        const out = (result.stdout || "").trim().toLowerCase()
+        if (out === "true" || out === "1") return true
+        if (out === "false" || out === "0") return false
+      } catch {
+        continue
+      }
+    }
+
+    return false
+  }
+
+  return false
+}
+
+const names = (() => {
+  const avx2 = supportsAvx2()
+  const baseline = arch === "x64" && !avx2
+
+  if (platform === "linux") {
+    const musl = (() => {
+      try {
+        if (fs.existsSync("/etc/alpine-release")) return true
+      } catch {
+        // ignore
+      }
+
+      try {
+        const result = childProcess.spawnSync("ldd", ["--version"], { encoding: "utf8" })
+        const text = ((result.stdout || "") + (result.stderr || "")).toLowerCase()
+        if (text.includes("musl")) return true
+      } catch {
+        // ignore
+      }
+
+      return false
+    })()
+
+    if (musl) {
+      if (arch === "x64") {
+        if (baseline) return [`${base}-baseline-musl`, `${base}-musl`, `${base}-baseline`, base]
+        return [`${base}-musl`, `${base}-baseline-musl`, base, `${base}-baseline`]
+      }
+      return [`${base}-musl`, base]
+    }
+
+    if (arch === "x64") {
+      if (baseline) return [`${base}-baseline`, base, `${base}-baseline-musl`, `${base}-musl`]
+      return [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`]
+    }
+    return [base, `${base}-musl`]
+  }
+
+  if (arch === "x64") {
+    if (baseline) return [`${base}-baseline`, base]
+    return [base, `${base}-baseline`]
+  }
+  return [base]
+})()
+
+function findBinary(startDir) {
+  let current = startDir
+  for (;;) {
+    const modules = path.join(current, "node_modules")
+    if (fs.existsSync(modules)) {
+      for (const name of names) {
+        const candidate = path.join(modules, name, "bin", binary)
+        if (fs.existsSync(candidate)) return candidate
+      }
+    }
+    const parent = path.dirname(current)
+    if (parent === current) {
+      return
+    }
+    current = parent
+  }
+}
+
+const resolved = findBinary(scriptDir)
+if (!resolved) {
+  console.error(
+    "It seems that your package manager failed to install the right version of the Newtype CLI for your platform. You can try manually installing " +
+      names.map((n) => `\"${n}\"`).join(" or ") +
+      " package",
+  )
+  process.exit(1)
+}
+
+run(resolved)

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@newtype-os/cli",
+  "bin": {
+    "nt": "./bin/nt"
+  },
+  "scripts": {
+    "postinstall": "bun ./postinstall.mjs || node ./postinstall.mjs"
+  },
+  "version": "0.0.0-main-202603270907",
+  "license": "MIT",
+  "optionalDependencies": {
+    "@newtype-os/cli-linux-x64-baseline-musl": "0.0.0-main-202603270907",
+    "@newtype-os/cli-darwin-x64": "0.0.0-main-202603270907",
+    "@newtype-os/cli-linux-x64-musl": "0.0.0-main-202603270907",
+    "@newtype-os/cli-linux-x64": "0.0.0-main-202603270907",
+    "@newtype-os/cli-windows-x64-baseline": "0.0.0-main-202603270907",
+    "@newtype-os/cli-darwin-arm64": "0.0.0-main-202603270907",
+    "@newtype-os/cli-darwin-x64-baseline": "0.0.0-main-202603270907",
+    "@newtype-os/cli-linux-arm64-musl": "0.0.0-main-202603270907",
+    "@newtype-os/cli-linux-arm64": "0.0.0-main-202603270907",
+    "@newtype-os/cli-windows-x64": "0.0.0-main-202603270907",
+    "@newtype-os/cli-linux-x64-baseline": "0.0.0-main-202603270907"
+  }
+}

package/postinstall.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+
+import fs from "fs"
+import path from "path"
+import os from "os"
+import { fileURLToPath } from "url"
+import { createRequire } from "module"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+
+function detectPlatformAndArch() {
+  // Map platform names
+  let platform
+  switch (os.platform()) {
+    case "darwin":
+      platform = "darwin"
+      break
+    case "linux":
+      platform = "linux"
+      break
+    case "win32":
+      platform = "windows"
+      break
+    default:
+      platform = os.platform()
+      break
+  }
+
+  // Map architecture names
+  let arch
+  switch (os.arch()) {
+    case "x64":
+      arch = "x64"
+      break
+    case "arm64":
+      arch = "arm64"
+      break
+    case "arm":
+      arch = "arm"
+      break
+    default:
+      arch = os.arch()
+      break
+  }
+
+  return { platform, arch }
+}
+
+function findBinary() {
+  const { platform, arch } = detectPlatformAndArch()
+  const packageName = `@newtype-os/cli-${platform}-${arch}`
+  const binaryName = platform === "windows" ? "newtype.exe" : "newtype"
+
+  try {
+    // Use require.resolve to find the package
+    const packageJsonPath = require.resolve(`${packageName}/package.json`)
+    const packageDir = path.dirname(packageJsonPath)
+    const binaryPath = path.join(packageDir, "bin", binaryName)
+
+    if (!fs.existsSync(binaryPath)) {
+      throw new Error(`Binary not found at ${binaryPath}`)
+    }
+
+    return { binaryPath, binaryName }
+  } catch (error) {
+    throw new Error(`Could not find package ${packageName}: ${error.message}`)
+  }
+}
+
+function prepareBinDirectory(binaryName) {
+  const binDir = path.join(__dirname, "bin")
+  const targetPath = path.join(binDir, binaryName)
+
+  // Ensure bin directory exists
+  if (!fs.existsSync(binDir)) {
+    fs.mkdirSync(binDir, { recursive: true })
+  }
+
+  // Remove existing binary/symlink if it exists
+  if (fs.existsSync(targetPath)) {
+    fs.unlinkSync(targetPath)
+  }
+
+  return { binDir, targetPath }
+}
+
+function symlinkBinary(sourcePath, binaryName) {
+  const { targetPath } = prepareBinDirectory(binaryName)
+
+  fs.symlinkSync(sourcePath, targetPath)
+  console.log(`newtype binary symlinked: ${targetPath} -> ${sourcePath}`)
+
+  // Verify the file exists after operation
+  if (!fs.existsSync(targetPath)) {
+    throw new Error(`Failed to symlink binary to ${targetPath}`)
+  }
+}
+
+async function main() {
+  try {
+    if (os.platform() === "win32") {
+      // On Windows, the .exe is already included in the package and bin field points to it
+      // No binary postinstall setup needed — config creation still runs below
+      console.log("Windows detected: binary setup not needed (using packaged .exe)")
+    } else {
+      // On non-Windows platforms, just verify the binary package exists
+      // Don't replace the wrapper script - it handles binary execution
+      const { binaryPath } = findBinary()
+      console.log(`Platform binary verified at: ${binaryPath}`)
+      console.log("Wrapper script will handle binary execution")
+    }
+  } catch (error) {
+    console.error("Failed to setup newtype binary:", error.message)
+    console.error("This is not fatal - the wrapper script will attempt to find the binary at runtime.")
+    // Don't exit(1) - postinstall failure should not block installation
+    // The bin/newtype wrapper script handles binary resolution at runtime
+  }
+
+  // Auto-create default config if it doesn't exist
+  try {
+    const configDir = path.join(os.homedir(), ".config", "newtype")
+    const configFile = path.join(configDir, "newtype-profile.json")
+
+    if (!fs.existsSync(configFile)) {
+      if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true })
+      }
+
+      const defaultConfig = {
+        agents: {
+          chief: { model: "opencode/glm-4.7-free" },
+          researcher: { model: "opencode/glm-4.7-free" },
+          archivist: { model: "opencode/glm-4.7-free" },
+          writer: { model: "opencode/glm-4.7-free" },
+        },
+      }
+
+      fs.writeFileSync(configFile, JSON.stringify(defaultConfig, null, 2) + "\n")
+      console.log(`Default config created at: ${configFile}`)
+    } else {
+      console.log(`Config already exists at: ${configFile}`)
+    }
+  } catch (error) {
+    console.error("Failed to create default config:", error.message)
+    // Non-fatal - user can create config manually
+  }
+
+  // Auto-inject SKILL.md into detected global AI agent directories
+  try {
+    // In dist package: skill-content.ts is next to postinstall.mjs
+    // In dev: it's at ../src/cli/cmd/skill-content.ts relative to script/
+    const candidates = [
+      path.join(__dirname, "skill-content.ts"),
+      path.join(__dirname, "..", "src", "cli", "cmd", "skill-content.ts"),
+    ]
+    const skillSrc = candidates.find((p) => fs.existsSync(p))
+    if (skillSrc) {
+      const raw = fs.readFileSync(skillSrc, "utf-8")
+      const match = raw.match(/export const skillContent = `([\s\S]*?)`/)
+      if (match) {
+        const content = match[1]
+        const home = os.homedir()
+        const agents = [
+          {
+            name: "claude-code",
+            root: path.join(home, ".claude"),
+            dir: path.join(home, ".claude", "skills", "newtype"),
+            file: "SKILL.md",
+          },
+          {
+            name: "codex",
+            root: path.join(home, ".codex"),
+            dir: path.join(home, ".codex", "skills", "newtype"),
+            file: "SKILL.md",
+          },
+          {
+            name: "goose",
+            root: path.join(home, ".config", "goose"),
+            dir: path.join(home, ".config", "goose", "skills", "newtype"),
+            file: "SKILL.md",
+          },
+          {
+            name: "cursor",
+            root: path.join(home, ".cursor"),
+            dir: path.join(home, ".cursor", "rules"),
+            file: "newtype.mdc",
+          },
+          {
+            name: "augment",
+            root: path.join(home, ".augment"),
+            dir: path.join(home, ".augment", "rules"),
+            file: "newtype.md",
+          },
+        ]
+        let injected = 0
+        for (const agent of agents) {
+          if (!fs.existsSync(agent.root)) continue
+          const target = path.join(agent.dir, agent.file)
+          if (fs.existsSync(target)) continue // Don't overwrite existing
+          fs.mkdirSync(agent.dir, { recursive: true })
+          if (agent.name === "cursor") {
+            const mdc = [
+              "---",
+              "description: Newtype CLI multi-agent content team",
+              "globs: ",
+              "alwaysApply: true",
+              "---",
+              "",
+              content,
+            ].join("\n")
+            fs.writeFileSync(target, mdc)
+          } else {
+            fs.writeFileSync(target, content)
+          }
+          injected++
+        }
+        if (injected > 0) {
+          console.log(`Newtype skill injected into ${injected} agent(s)`)
+        }
+      }
+    }
+  } catch (error) {
+    console.error("Failed to inject skills:", error.message)
+    // Non-fatal
+  }
+}
+
+main().catch((error) => {
+  console.error("Postinstall script error:", error.message)
+  // Exit 0 so installation is not blocked
+  process.exit(0)
+})

package/skill-content.ts

@@ -0,0 +1,358 @@
+export const skillContent = `# newtype CLI — Multi-Agent Content Team
+
+Binary: \`nt\` | Package: \`npm i -g @newtype-os/cli\`
+
+8 specialized AI agents (researcher, writer, editor, fact-checker, extractor, analyst, archivist, chief) accessible as non-interactive CLI commands. Designed for programmatic invocation by other AI agents.
+
+## When to Use
+
+- Deep research on a topic with source verification
+- Generate newsletters, essays, reports, technical docs
+- Polish existing content (structure → paragraph → sentence → word)
+- Fact-check claims or articles
+- Extract structured content from PDF, images, web pages
+- Framework-based analysis (SWOT, first-principles, PESTEL, etc.)
+- Full research-to-publish pipeline orchestration
+- Store/retrieve knowledge across sessions
+
+## Installation
+
+\`\`\`bash
+npm i -g @newtype-os/cli
+# or
+bun i -g @newtype-os/cli
+\`\`\`
+
+Verify: \`nt --version\`
+
+## Output Modes
+
+| Flag        | Behavior                | Use When                               |
+| ----------- | ----------------------- | -------------------------------------- |
+| (none)      | Plain text to stdout    | Human reading, simple piping           |
+| \`--json\`    | JSON envelope to stdout | Agent parsing results programmatically |
+| \`--stream\`  | NDJSON event stream     | Real-time progress monitoring          |
+| \`-o <file>\` | Write result to file    | Saving output, pipeline steps          |
+
+### JSON Envelope Schema
+
+\`\`\`json
+{
+  "success": true,
+  "result": "... the text output ...",
+  "metadata": {
+    "agent": "researcher",
+    "sessionID": "...",
+    "duration_ms": 45000,
+    "tools": [{ "name": "web_search", "title": "..." }]
+  }
+}
+\`\`\`
+
+On error:
+
+\`\`\`json
+{
+  "success": false,
+  "error": { "code": 2, "message": "..." },
+  "metadata": {
+    "agent": "researcher",
+    "sessionID": "...",
+    "duration_ms": 12000,
+    "tools": []
+  }
+}
+\`\`\`
+
+## Exit Codes
+
+| Code | Meaning              |
+| ---- | -------------------- |
+| 0    | Success              |
+| 1    | Input/argument error |
+| 2    | Model call failed    |
+| 3    | Timeout              |
+| 4    | Config/auth error    |
+
+## Input Methods (priority high → low)
+
+1. Positional text: \`nt research AI Agent architectures\`
+2. \`--input <file>\` — read from file
+3. \`--topic <text>\` — explicit topic string
+4. stdin pipe: \`cat notes.md | nt write\`
+
+## Global Flags
+
+| Flag              | Short | Description                               |
+| ----------------- | ----- | ----------------------------------------- |
+| \`--output <path>\` | \`-o\`  | Output file (default: stdout)             |
+| \`--json\`          |       | JSON envelope output                      |
+| \`--stream\`        |       | NDJSON event stream                       |
+| \`--verbose\`       |       | Show tool execution progress              |
+| \`--quiet\`         | \`-q\`  | Suppress non-result output                |
+| \`--model <p/m>\`   | \`-m\`  | Override model (format: \`provider/model\`) |
+| \`--lang <code>\`   |       | Output language: \`zh\`, \`en\`, \`ja\`, etc.   |
+| \`--timeout <sec>\` | \`-t\`  | Timeout in seconds (default: 300)         |
+| \`--input <file>\`  |       | Input file path                           |
+| \`--topic <text>\`  |       | Topic text                                |
+
+---
+
+## Commands
+
+### \`nt research [topic..]\` — Topic Research
+
+Agent: researcher (+ fact-checker by default)
+
+\`\`\`bash
+# Basic
+nt research "AI Agent architectures 2026" -o research.md
+
+# Deep research with focus
+nt research "MCP vs CLI" --depth deep --focus "developer experience,adoption" -o deep.md
+
+# JSON output for programmatic consumption
+nt research "Kubernetes security" --json
+
+# Skip fact-checking for speed
+nt research "quick overview of RAG" --no-fact-check -o quick.md
+
+# Pipe research into writing
+nt research "AI trends" -o /tmp/r.md && nt write --input /tmp/r.md -o draft.md
+\`\`\`
+
+| Flag                 | Default  | Description                     |
+| -------------------- | -------- | ------------------------------- |
+| \`--depth <level>\`    | \`normal\` | \`shallow\` / \`normal\` / \`deep\`   |
+| \`--sources <n>\`      | \`5\`      | Expected number of sources      |
+| \`--focus <keywords>\` |          | Focus keywords, comma-separated |
+| \`--no-fact-check\`    |          | Skip fact-checking step         |
+
+### \`nt write [topic..]\` — Content Generation
+
+Agent: writer
+
+\`\`\`bash
+# From research material
+nt write --input research.md --style newsletter -o draft.md
+
+# From scratch with topic
+nt write "Why CLI is the native language of AI Agents" --style essay --words 2000 -o article.md
+
+# Specify methodology and tone
+nt write --input notes.md --method AIDA --tone professional --audience "CTOs and VPs of Engineering" -o post.md
+\`\`\`
+
+| Flag                | Default | Description                                                                 |
+| ------------------- | ------- | --------------------------------------------------------------------------- |
+| \`--style <s>\`       |         | \`newsletter\` / \`essay\` / \`report\` / \`tweet-thread\` / \`technical\` / \`story\`  |
+| \`--method <m>\`      |         | \`WRITE\` / \`AIDA\` / \`PAS\` / \`STORYTELLING\` / \`ANALYTICAL\` / \`CONVERSATIONAL\` |
+| \`--words <n>\`       | \`1500\`  | Target word count                                                           |
+| \`--tone <t>\`        |         | \`professional\` / \`casual\` / \`academic\` / \`provocative\`                      |
+| \`--audience <desc>\` |         | Target audience description                                                 |
+
+### \`nt edit [file]\` — Content Editing
+
+Agent: editor. Four-layer refinement: structure → paragraph → sentence → word.
+
+\`\`\`bash
+# Full edit
+nt edit --input draft.md -o final.md
+
+# Structure-only pass
+nt edit --input draft.md --layer structure -o restructured.md
+
+# Preserve voice, only fix grammar
+nt edit --input draft.md --preserve-voice -o polished.md
+
+# Pipe from stdin
+cat draft.md | nt edit -o final.md
+
+# Edit with diff output
+nt edit --input draft.md --diff -o final.md
+\`\`\`
+
+| Flag                       | Default | Description                                             |
+| -------------------------- | ------- | ------------------------------------------------------- |
+| \`--layer <l>\`              | \`all\`   | \`structure\` / \`paragraph\` / \`sentence\` / \`word\` / \`all\` |
+| \`--tone <t>\`               |         | Target tone                                             |
+| \`--target-audience <desc>\` |         | Target audience                                         |
+| \`--preserve-voice\`         |         | Keep original voice, fix grammar/logic only             |
+| \`--diff\`                   |         | Include diff showing changes                            |
+
+### \`nt fact-check [topic..]\` — Fact Verification
+
+Agent: fact-checker
+
+\`\`\`bash
+# Check an article
+nt fact-check --input article.md -o report.md
+
+# Check a single claim
+nt fact-check --claim "GPT-4 has 1.8 trillion parameters" --json
+
+# Strict mode with extra cross-verification
+nt fact-check --input report.md --strict -o verified.md
+\`\`\`
+
+| Flag             | Description                          |
+| ---------------- | ------------------------------------ |
+| \`--claim <text>\` | Verify a single claim                |
+| \`--strict\`       | Strict mode — more cross-referencing |
+
+### \`nt analyze [topic..]\` — Framework Analysis
+
+Agent: chief + researcher. Supports 12 analysis frameworks.
+
+\`\`\`bash
+# SWOT analysis
+nt analyze --input research.md --framework swot -o analysis.md
+
+# First principles
+nt analyze "Why are all tools moving to CLI" --framework first-principles -o analysis.md
+
+# Multiple frameworks combined
+nt analyze --input data.md --framework "swot,pestel" -o combo.md
+
+# JSON output
+nt analyze "React vs Vue market position" --framework porter --json
+\`\`\`
+
+Available frameworks: \`swot\`, \`pestel\`, \`porter\`, \`first-principles\`, \`5why\`, \`jobs-to-be-done\`, \`blue-ocean\`, \`value-chain\`, \`bcg-matrix\`, \`ansoff\`, \`okr\`, \`systems-thinking\`
+
+| Flag                 | Description                   |
+| -------------------- | ----------------------------- |
+| \`--framework <name>\` | Framework(s), comma-separated |
+
+### \`nt extract [topic..]\` — Content Extraction
+
+Agent: extractor. Extract structured content from documents, images, or web pages.
+
+\`\`\`bash
+# Extract from file
+nt extract --input paper.pdf -o extracted.md
+
+# Extract from URL
+nt extract --url "https://example.com/article" -o page.md
+
+# Prioritize tables
+nt extract --input report.pdf --extract-tables --json
+\`\`\`
+
+| Flag               | Description                        |
+| ------------------ | ---------------------------------- |
+| \`--url <url>\`      | Web page URL to extract from       |
+| \`--extract-tables\` | Prioritize table extraction        |
+| \`--extract-images\` | Extract and describe image content |
+
+### \`nt archive <action>\` — Knowledge Base
+
+Agent: archivist. Subcommands: \`store\`, \`search\`, \`list\`, \`delete\`.
+
+\`\`\`bash
+# Store content with tags
+nt archive store --input research.md --tags "AI,Agent,2026"
+
+# Semantic search
+nt archive search --query "difference between MCP and CLI" --top 5 -o results.md
+
+# List all entries (filtered by tag)
+nt archive list --tags "AI" --json
+
+# Delete entry
+nt archive delete --id "entry-123"
+\`\`\`
+
+| Flag             | Description                           |
+| ---------------- | ------------------------------------- |
+| \`--tags <csv>\`   | Tags, comma-separated (store/list)    |
+| \`--query <text>\` | Search query (search, required)       |
+| \`--top <n>\`      | Number of search results (default: 5) |
+| \`--id <id>\`      | Entry ID (delete, required)           |
+
+### \`nt pipeline [topic..]\` — Full Workflow
+
+Agent: chief orchestrating all agents. Default steps: research → analyze → write → fact-check → edit.
+
+\`\`\`bash
+# Full pipeline from topic
+nt pipeline "AI Agent trends 2026" --style newsletter --output-dir ./output/
+
+# Custom steps
+nt pipeline "MCP future" --steps "research,write,edit" -o result.md
+
+# From existing material (skip research)
+nt pipeline --input notes.md --steps "analyze,write,edit" -o final.md
+
+# JSON output
+nt pipeline "topic" --json
+\`\`\`
+
+| Flag                 | Default                                  | Description                                   |
+| -------------------- | ---------------------------------------- | --------------------------------------------- |
+| \`--steps <csv>\`      | \`research,analyze,write,fact-check,edit\` | Workflow steps                                |
+| \`--style <s>\`        |                                          | Final output writing style                    |
+| \`--output-dir <dir>\` |                                          | Output directory (one file per step)          |
+| \`--parallel\`         |                                          | Allow parallel execution of independent steps |
+
+Default timeout: 600s (vs 300s for other commands).
+
+---
+
+## Pipeline Composition Patterns
+
+Chain commands with \`&&\` for multi-step workflows:
+
+\`\`\`bash
+# Research → Write → Edit
+nt research "AI Agents" -o /tmp/r.md \\
+  && nt write --input /tmp/r.md --style newsletter -o /tmp/d.md \\
+  && nt edit --input /tmp/d.md -o final.md
+
+# Extract → Fact-check → Archive
+nt extract --input paper.pdf -o /tmp/e.md \\
+  && nt fact-check --input /tmp/e.md -o /tmp/fc.md \\
+  && nt archive store --input /tmp/fc.md --tags "paper,verified"
+
+# Research with JSON for downstream parsing
+nt research "topic" --json | jq '.result' > research.txt
+\`\`\`
+
+## Agent Integration Examples
+
+For AI agents (Claude Code, Cursor, etc.) calling \`nt\` programmatically:
+
+\`\`\`bash
+# Get structured output
+result=$(nt research "Kubernetes best practices" --json)
+echo "$result" | jq -r '.result'    # extract text
+echo "$result" | jq '.success'      # check success
+echo "$result" | jq '.metadata'     # get metadata
+
+# Check exit code
+nt research "topic" --json -o out.json
+if [ $? -eq 0 ]; then
+  echo "Success"
+elif [ $? -eq 2 ]; then
+  echo "Model call failed, retry"
+elif [ $? -eq 3 ]; then
+  echo "Timeout, increase with --timeout"
+fi
+
+# Write to file and verify
+nt write "topic" -o draft.md && test -f draft.md && echo "File created"
+\`\`\`
+
+## Command → Agent Mapping
+
+| Command         | Agent(s)                    | Description                            |
+| --------------- | --------------------------- | -------------------------------------- |
+| \`nt research\`   | researcher (+ fact-checker) | Deep research with source verification |
+| \`nt write\`      | writer                      | Multi-style content generation         |
+| \`nt edit\`       | editor                      | Four-layer content refinement          |
+| \`nt fact-check\` | fact-checker                | Claim and source verification          |
+| \`nt analyze\`    | chief + researcher          | 12 analysis frameworks                 |
+| \`nt extract\`    | extractor                   | Document/image/web extraction          |
+| \`nt archive\`    | archivist                   | Knowledge base CRUD                    |
+| \`nt pipeline\`   | chief → all                 | Full orchestration pipeline            |
+`