@khanglvm/outline-cli 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.3 - 2026-03-06
+
+- Changes since `v0.1.2`.
+- feat(ai-onboarding): add approval-gated npx skills install flow (9992856)
+
 ## 0.1.2 - 2026-03-06
 
 - Changes since `v0.1.1`.

package/README.md

@@ -1,12 +1,6 @@
 # outline-cli
 
-An AI Agent-Optimized CLI for Outline ([`https://getoutline.com`](getoutline.com)).
-
-- Stable JSON envelopes
-- Token-efficient `ids` and `summary` views
-- Batch operations to reduce API round trips
-- Safe mutation gates (`performAction: true`)
-- Automatic large-result offload to temp files
+A CLI for Outline ([`https://getoutline.com`](https://getoutline.com)) - optimized for AI agents.
 
 ## Quick Start
 
@@ -16,10 +10,12 @@ Install globally:
 npm i -g @khanglvm/outline-cli
 ```
 
-Then run built-in AI onboarding guidance:
+## Get Started with AI Agents
 
-```bash
-outline-cli tools help quick-start-agent --view full
+After installing, paste this instruction into your AI coding assistant:
+
+```text
+Run `outline-cli tools help quick-start-agent --view full` and follow its instructions to help me get started with Outline CLI
 ```
 
 ## Day-to-Day Usage
@@ -32,7 +28,7 @@ outline-cli tools contract documents.search --pretty
 outline-cli tools contract all --result-mode inline
 ```
 
-Read document metadata by id:
+Read document metadata by ID:
 
 ```bash
 outline-cli invoke documents.info \
@@ -64,7 +60,7 @@ outline-cli batch --ops '[
 
 ## Safe Delete Flow
 
-Delete is guarded by read-token confirmation.
+Deletion is guarded by read-token confirmation.
 
 1. Arm-delete read:
 
@@ -103,7 +99,7 @@ outline-cli tmp gc --older-than-hours 24
 
 ## Profile Management
 
-Add password-mode profile:
+Add a password-mode profile:
 
 ```bash
 outline-cli profile add internal \
@@ -135,16 +131,21 @@ outline-cli profile enrich prod \
 
 Use this short operating pattern when an AI agent drives the CLI:
 
-1. Start with `tools contract all --result-mode inline`.
-2. Prefer `view:"ids"` or `view:"summary"` first; hydrate to `full` only when needed.
-3. Bundle independent reads into one `batch` call.
-4. For any mutation endpoint, explicitly set `performAction:true`.
-5. For delete, always run `documents.info` with `armDelete:true` first and pass the returned read token.
-6. If output is file-offloaded, read only the required fields via `tmp cat` + `jq`.
+1. Start with `outline-cli --version` and `tools help --view summary` to confirm onboarding help is available.
+2. Suggest installing the `outline-cli` skill via `npx skills` for all currently supported local AI tools; only run install after explicit user approval.
+3. If approved, run headless install without tool-specific filter: `npx skills add https://github.com/khanglvm/skills --skill outline-cli -y`.
+4. Prefer `view:"ids"` or `view:"summary"` first; hydrate to `full` only when needed.
+5. Bundle independent reads into one `batch` call.
+6. For any mutation endpoint, explicitly set `performAction:true`.
+7. For delete, always run `documents.info` with `armDelete:true` first and pass the returned read token.
+8. List existing profiles before creating one with `outline-cli profile list --pretty`.
+9. For new profiles, prefer API key mode and guide users through base URL + API key generation (`<base-url>/settings/api`) before `profile add`.
+10. If output is file-offloaded, read only the required fields via `tmp cat` + `jq`.
 
 For structured AI playbooks and scenario guides:
 
 ```bash
+outline-cli tools help --view summary
 outline-cli tools help quick-start-agent --view full
 outline-cli tools help ai-skills --view summary
 outline-cli tools help ai-skills --scenario UC-12
@@ -152,7 +153,7 @@ outline-cli tools help ai-skills --scenario UC-12
 
 ## Testing (Live Environment)
 
-Set test credentials in local env file:
+Set test credentials in a local env file:
 
 ```bash
 cp .env.test.example .env.test.local
@@ -166,7 +167,7 @@ npm run check
 npm test
 ```
 
-Test rule in this repository:
+Test rules in this repository:
 
 - Mutation tests create and clean up their own test documents.
 - Read-only tests may use site-wide data.
@@ -204,7 +205,7 @@ Release prerequisites:
 
 - Never commit real API keys.
 - Keep local secrets in untracked files such as `.env.test.local`.
-- Profile secrets are stored in OS keychain by default.
+- Profile secrets are stored in the OS keychain by default.
 
 ## Reference Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/outline-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Agent-optimized CLI for Outline API",
   "type": "module",
   "bin": {

package/src/agent-skills.js

@@ -3,64 +3,166 @@ import { CliError } from "./errors.js";
 const AI_SKILL_DATA_VERSION = "2026-03-05.1";
 const AI_HELP_SECTION_ID = "ai-skills";
 const QUICK_START_HELP_SECTION_ID = "quick-start-agent";
-const QUICK_START_HELP_VERSION = "2026-03-05.1";
+const QUICK_START_HELP_VERSION = "2026-03-06.3";
 
 const QUICK_START_AGENT_PLAYBOOK = {
   title: "outline-cli onboarding for non-expert users",
   audience: "AI agents assisting non-expert users in terminal setup and first usage.",
   objective:
-    "Install outline-cli globally, discover required setup commands, guide profile creation with follow-up questions, then demonstrate example use cases in natural language.",
+    "Verify existing outline-cli installation first, discover AI onboarding commands, explicitly offer optional outline-cli skill installation via npx skills (approval-gated), list existing profiles before creating one, then guide API-key setup with domain checks and provide natural-language starter prompts.",
   steps: [
     {
       step: 1,
-      title: "Install outline-cli globally",
-      command: "npm i -g @khanglvm/outline-cli",
-      successCheck: "outline-cli --help",
+      title: "Check current installation and help command availability",
+      commands: [
+        "outline-cli --version",
+        "outline-cli --help",
+        "outline-cli tools --help",
+        "outline-cli tools help --view summary",
+      ],
+      fallbackCommands: [
+        "npm i -g @khanglvm/outline-cli@latest",
+        "outline-cli --version",
+        "outline-cli tools help --view summary",
+      ],
+      successCheck: "tools help output includes the quick-start-agent section",
     },
     {
       step: 2,
+      title: "Load full onboarding guide for deterministic setup steps",
+      command: "outline-cli tools help quick-start-agent --view full",
+    },
+    {
+      step: 3,
+      title: "Suggest optional outline-cli skill installation via npx skills",
+      question:
+        "Would you like me to install the outline-cli skill now via npx skills for all currently supported local AI tools? This helps future AI sessions use the right workflow by default.",
+      commandTemplates: [
+        "npx skills add https://github.com/khanglvm/skills --skill outline-cli -y",
+      ],
+      decisionRules: [
+        "If user explicitly approves, run the command in headless mode exactly once so installation applies to currently supported local tools.",
+        "If user declines, skip installation and continue onboarding without blocking profile setup.",
+      ],
+      expectedSignals: [
+        "Successful install prints completion output from npx skills.",
+        "Failure should be reported with the exact command and next recovery step.",
+      ],
+    },
+    {
+      step: 4,
       title: "Inspect command surfaces before asking the user for inputs",
       commands: [
-        "outline-cli --help",
         "outline-cli profile --help",
-        "outline-cli tools --help",
         "outline-cli invoke --help",
       ],
     },
     {
-      step: 3,
-      title: "Ask follow-up questions for missing setup values",
+      step: 5,
+      title: "List existing profiles first and branch setup flow",
+      command: "outline-cli profile list --pretty",
+      decisionRules: [
+        "If one or more profiles exist, show them and ask whether to use an existing profile or create a new one.",
+        "If no profiles exist, continue with new profile setup questions.",
+      ],
+    },
+    {
+      step: 6,
+      title: "Ask for Outline base URL with beginner-friendly explanation",
+      question:
+        "What is your Outline base URL? This is the web address you open in your browser to use Outline.",
+      examples: [
+        "Official cloud: https://app.getoutline.com",
+        "Custom/self-hosted: https://docs.yourcompany.com",
+      ],
+      guidance: [
+        "Use https:// and do not include a trailing path.",
+        "If unsure, copy the URL from your browser while viewing your Outline workspace home.",
+      ],
+    },
+    {
+      step: 7,
+      title: "Validate the provided base URL before asking for API key",
+      commandTemplates: [
+        'curl -sS -o /dev/null -w "HTTP %{http_code}\\n" "<base-url>"',
+        'curl -sS -o /dev/null -w "API %{http_code}\\n" "<base-url>/api/auth.info"',
+      ],
+      expectedSignals: [
+        "Base URL check should return a reachable HTTP status (often 200/301/302).",
+        "API auth endpoint without token often returns 401/403, which still confirms domain + API route are reachable.",
+      ],
+    },
+    {
+      step: 8,
+      title: "Guide user to create API key in Outline UI",
+      apiKeySettingsUrlTemplate: "<base-url>/settings/api",
+      fallbackNavigation: "In Outline UI: Settings → API Keys",
+      apiKeyConfigTemplate: [
+        "Name: outline-cli-<profile-id-or-your-name>",
+        "Expiration date: choose your policy (for example 90 days or no expiry if policy allows)",
+        "Scopes: leave empty for same permissions as your user, or restrict to needed endpoints",
+      ],
+      scopeExamples: [
+        "Read-focused starter scope: *.info documents.search collections.list",
+        "Document automation scope: documents.* collections.info",
+      ],
+      requiredUserAction:
+        "Create the key, then copy the generated token value (typically starts with ol_api_) and share it with the agent for profile setup.",
+    },
+    {
+      step: 9,
+      title: "Ask follow-up questions for remaining setup values (one at a time)",
       questions: [
-        "What is your Outline base URL?",
         "What is your Outline API key?",
         "What profile id do you want? (default to prod if user has no preference)",
       ],
     },
     {
-      step: 4,
-      title: "Guide profile setup and set it as default",
+      step: 10,
+      title: "Guide profile setup (API key mode) and set it as default",
       command:
-        'outline-cli profile add <profile-id> --base-url <base-url> --api-key "<api-key>" --set-default',
+        'outline-cli profile add <profile-id> --base-url <base-url> --auth-type apiKey --api-key "<api-key>" --set-default',
     },
     {
-      step: 5,
+      step: 11,
       title: "Verify profile authentication",
       command: "outline-cli profile test <profile-id> --pretty",
     },
     {
-      step: 6,
-      title: "Show example use cases in plain language and run one command per example",
+      step: 12,
+      title: "Show natural-language prompts for what the AI agent can do with outline-cli",
+      minimumPromptCount: 10,
+      naturalLanguagePrompts: [
+        "Find our onboarding checklist in Outline.",
+        "List recent documents in the Engineering collection.",
+        "Show me a summary of document <document-id>.",
+        "Create a draft release notes document with today's date.",
+        "Append a short status update to document <document-id>.",
+        "Find documents mentioning incident response in the last month.",
+        "Show who can access document <document-id>.",
+        "Compare two documents and list key differences.",
+        "Generate a TODO list from document <document-id>.",
+        "Find stale docs that have not been updated recently.",
+      ],
       commandTemplates: [
         'outline-cli invoke documents.search --args \'{"query":"onboarding checklist","mode":"semantic","limit":5,"view":"summary"}\' --pretty',
+        'outline-cli invoke documents.list --args \'{"limit":5,"view":"summary"}\' --pretty',
         'outline-cli invoke documents.info --args \'{"id":"<document-id>","view":"summary"}\' --pretty',
       ],
     },
   ],
   interactionRules: [
     "Use short and clear explanations for beginners.",
+    "Always run installation/help discovery commands before setup questions.",
+    "Always suggest optional outline-cli skill installation via npx skills and ask for explicit approval before running install.",
+    "If approved, run npx skills installation in headless mode (`-y`, no tool-specific agent filter) and continue onboarding.",
+    "Always run profile list before profile add.",
+    "Prefer API key authentication for beginner onboarding unless the user explicitly requests another auth mode.",
+    "Explain base URL and API key steps in plain language, then validate the domain before requesting the API key.",
     "Ask one question at a time when required information is missing.",
     "If a command fails, explain the cause and provide the exact next command.",
     "Confirm each step completion before moving to the next step.",
+    "After setup, provide at least 10 natural-language prompts and run one command example.",
   ],
 };
 
@@ -707,11 +809,46 @@ function summarizeQuickStartPlaybook() {
     title: QUICK_START_AGENT_PLAYBOOK.title,
     audience: QUICK_START_AGENT_PLAYBOOK.audience,
     objective: QUICK_START_AGENT_PLAYBOOK.objective,
-    steps: QUICK_START_AGENT_PLAYBOOK.steps.map((row) => ({
-      step: row.step,
-      title: row.title,
-      command: row.command || null,
-    })),
+    steps: QUICK_START_AGENT_PLAYBOOK.steps.map((row) => {
+      const summaryRow = {
+        step: row.step,
+        title: row.title,
+      };
+      if (row.command) {
+        summaryRow.command = row.command;
+      }
+      if (Array.isArray(row.commands)) {
+        summaryRow.commands = row.commands;
+      }
+      if (Array.isArray(row.questions)) {
+        summaryRow.questions = row.questions;
+      }
+      if (row.question) {
+        summaryRow.question = row.question;
+      }
+      if (row.minimumPromptCount) {
+        summaryRow.minimumPromptCount = row.minimumPromptCount;
+      }
+      if (Array.isArray(row.commandTemplates)) {
+        summaryRow.commandTemplates = row.commandTemplates;
+      }
+      if (Array.isArray(row.decisionRules)) {
+        summaryRow.decisionRules = row.decisionRules;
+      }
+      if (Array.isArray(row.expectedSignals)) {
+        summaryRow.expectedSignals = row.expectedSignals;
+      }
+      if (row.apiKeySettingsUrlTemplate) {
+        summaryRow.apiKeySettingsUrlTemplate = row.apiKeySettingsUrlTemplate;
+      }
+      if (Array.isArray(row.apiKeyConfigTemplate)) {
+        summaryRow.apiKeyConfigTemplate = row.apiKeyConfigTemplate;
+      }
+      if (Array.isArray(row.scopeExamples)) {
+        summaryRow.scopeExamples = row.scopeExamples;
+      }
+      return summaryRow;
+    }),
     interactionRules: QUICK_START_AGENT_PLAYBOOK.interactionRules,
     nextCommand: "outline-cli tools help quick-start-agent --view full",
   };
@@ -850,7 +987,7 @@ export function listHelpSections() {
       id: QUICK_START_HELP_SECTION_ID,
       title: "AI setup onboarding",
       description:
-        "Copy-ready AI onboarding instructions to install outline-cli, guide profile setup, and demonstrate first use cases.",
+        "Copy-ready AI onboarding instructions to verify installation, guide API-key profile setup (including base URL + settings path), and provide natural-language starter prompts.",
       commandExample: "outline-cli tools help quick-start-agent --view full",
     },
     {

package/src/cli.js

@@ -789,8 +789,11 @@ export async function run(argv = process.argv) {
       if (
         sectionName === "quick-start-agent" ||
         sectionName === "quickstart-agent" ||
+        sectionName === "quick-start" ||
         sectionName === "quickstart" ||
-        sectionName === "setup"
+        sectionName === "setup" ||
+        sectionName === "agent" ||
+        sectionName === "onboarding"
       ) {
         await emitOutput(
           store,

package/src/entry-integrity-manifest.generated.js

@@ -3,8 +3,8 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
   version: 1,
   algorithm: "sha256",
   signatureAlgorithm: "sha256-salted-manifest-v1",
-  signature: "db2b8cd3d150b5be3b17246af7a254fc42ec500c3567a8be79ca2e4178f4657a",
-  generatedAt: "2026-03-06T00:27:55.266Z",
+  signature: "03f876687f3972f11cce73da3da5f5f5266536bdce151a03326a813082240016",
+  generatedAt: "2026-03-06T04:21:12.443Z",
   files: [
   {
     "path": "src/action-gate.js",
@@ -12,11 +12,11 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
   },
   {
     "path": "src/agent-skills.js",
-    "sha256": "3ec649a1e4fb475de47882223d2ca0e5bb049720cad1b456ea3ecd6ff1b74ecc"
+    "sha256": "12d54830ec84d9e8815cd28915070453175520416c83983de2496c1734acd7a2"
   },
   {
     "path": "src/cli.js",
-    "sha256": "bf37837390eaedadc6f8a8a8e279e61c12d56792f83cb4c53173439009cf5422"
+    "sha256": "7959970b8e2d0d81de0c2e35201274f0d16744aaa2a73f001decfdad45c85522"
   },
   {
     "path": "src/config-store.js",

package/test/agent-skills.unit.test.js

@@ -18,6 +18,34 @@ test("getQuickStartAgentHelp returns summary by default", () => {
   assert.equal(payload.view, "summary");
   assert.ok(Array.isArray(payload.steps));
   assert.ok(payload.steps.length >= 4);
+  assert.ok(
+    payload.steps.some(
+      (row) => Array.isArray(row.commands) && row.commands.includes("outline-cli --version")
+    )
+  );
+  assert.ok(
+    payload.steps.some(
+      (row) =>
+        typeof row.question === "string" &&
+        row.question.toLowerCase().includes("install the outline-cli skill")
+    )
+  );
+  assert.ok(
+    payload.steps.some(
+      (row) =>
+        Array.isArray(row.commandTemplates) &&
+        row.commandTemplates.some(
+          (cmd) => cmd.includes("npx skills add") && cmd.includes("--skill outline-cli -y") && !cmd.includes("--agent")
+        )
+    )
+  );
+  assert.ok(
+    payload.steps.some(
+      (row) =>
+        typeof row.question === "string" &&
+        row.question.toLowerCase().includes("base url")
+    )
+  );
   assert.equal(payload.nextCommand, "outline-cli tools help quick-start-agent --view full");
 });
 
@@ -26,7 +54,42 @@ test("getQuickStartAgentHelp returns full payload and validates view", () => {
   assert.equal(payload.section, "quick-start-agent");
   assert.equal(payload.view, "full");
   assert.ok(Array.isArray(payload.steps));
-  assert.ok(payload.steps.some((row) => row.command === "npm i -g @khanglvm/outline-cli"));
+  assert.ok(payload.steps.some((row) => row.command === "outline-cli profile list --pretty"));
+  assert.ok(
+    payload.steps.some(
+      (row) =>
+        row.command &&
+        row.command.includes("--auth-type apiKey") &&
+        row.command.includes("--api-key")
+    )
+  );
+  assert.ok(
+    payload.steps.some(
+      (row) =>
+        Array.isArray(row.commandTemplates) &&
+        row.commandTemplates.includes(
+          "npx skills add https://github.com/khanglvm/skills --skill outline-cli -y"
+        ) &&
+        Array.isArray(row.decisionRules) &&
+        row.decisionRules.some((rule) => rule.toLowerCase().includes("explicitly approves"))
+    )
+  );
+  assert.ok(
+    payload.steps.some(
+      (row) =>
+        row.apiKeySettingsUrlTemplate === "<base-url>/settings/api" &&
+        Array.isArray(row.apiKeyConfigTemplate) &&
+        row.apiKeyConfigTemplate.length >= 3
+    )
+  );
+  assert.ok(
+    payload.steps.some(
+      (row) =>
+        row.minimumPromptCount >= 10 &&
+        Array.isArray(row.naturalLanguagePrompts) &&
+        row.naturalLanguagePrompts.length >= 10
+    )
+  );
   assert.ok(Array.isArray(payload.interactionRules));
 
   assert.throws(