@khanglvm/outline-cli 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.2 - 2026-03-06
+
+- Changes since `v0.1.1`.
+- docs(readme): remove redundant quick-start copy prompt (28ab2cd)
+- feat(help): add quick-start-agent onboarding section (1d21814)
+- docs(readme): rewrite quick start as AI agent instructions (2b3065b)
+- docs(readme): remove duplicated intro wording (88eddcf)
+- docs: remove tracked docs directory and refine README intro (7235f95)
+- docs(readme): prioritize global install usage (052c31b)
+
 ## 0.1.1 - 2026-03-05
 
 - Initial tagged release notes.

package/README.md

@@ -1,8 +1,6 @@
 # outline-cli
 
-`outline-cli` (alias `outline-agent`) is a Node.js CLI for the Outline API, designed for both human operators and AI agents.
-
-It prioritizes deterministic, machine-friendly output:
+An AI Agent-Optimized CLI for Outline ([`https://getoutline.com`](getoutline.com)).
 
 - Stable JSON envelopes
 - Token-efficient `ids` and `summary` views
@@ -12,46 +10,16 @@ It prioritizes deterministic, machine-friendly output:
 
 ## Quick Start
 
-Prerequisites:
-
-- Node.js `>=18.17`
-- An Outline workspace URL
-- An Outline API key (recommended auth mode)
-
-Run from npm without installing:
-
-```bash
-npx @khanglvm/outline-cli --help
-```
-
-Or install locally in this repo:
-
-```bash
-npm install
-node ./bin/outline-cli.js --help
-```
-
-Set up a profile (API key mode):
-
-```bash
-npx @khanglvm/outline-cli profile add prod \
-  --base-url https://app.getoutline.com \
-  --api-key "$OUTLINE_API_KEY" \
-  --set-default
-```
-
-Verify auth:
+Install globally:
 
 ```bash
-npx @khanglvm/outline-cli profile test prod --pretty
+npm i -g @khanglvm/outline-cli
 ```
 
-Run your first search:
+Then run built-in AI onboarding guidance:
 
 ```bash
-npx @khanglvm/outline-cli invoke documents.search \
-  --args '{"query":"oncall runbook","mode":"semantic","limit":5,"view":"summary"}' \
-  --pretty
+outline-cli tools help quick-start-agent --view full
 ```
 
 ## Day-to-Day Usage
@@ -59,36 +27,36 @@ npx @khanglvm/outline-cli invoke documents.search \
 Discover tools and contracts:
 
 ```bash
-npx @khanglvm/outline-cli tools list
-npx @khanglvm/outline-cli tools contract documents.search --pretty
-npx @khanglvm/outline-cli tools contract all --result-mode inline
+outline-cli tools list
+outline-cli tools contract documents.search --pretty
+outline-cli tools contract all --result-mode inline
 ```
 
 Read document metadata by id:
 
 ```bash
-npx @khanglvm/outline-cli invoke documents.info \
+outline-cli invoke documents.info \
   --args '{"id":"<document-id>","view":"summary"}'
 ```
 
 Create a document:
 
 ```bash
-npx @khanglvm/outline-cli invoke documents.create \
+outline-cli invoke documents.create \
   --args '{"title":"Release Notes","text":"# Release Notes","publish":false,"view":"summary"}'
 ```
 
 Update a document (mutation requires `performAction: true`):
 
 ```bash
-npx @khanglvm/outline-cli invoke documents.update \
+outline-cli invoke documents.update \
   --args '{"id":"<document-id>","text":"\n\nUpdated by automation.","editMode":"append","performAction":true,"view":"summary"}'
 ```
 
 Batch multiple calls:
 
 ```bash
-npx @khanglvm/outline-cli batch --ops '[
+outline-cli batch --ops '[
   {"tool":"collections.list","args":{"limit":5,"view":"summary"}},
   {"tool":"documents.search","args":{"query":"incident","limit":5,"view":"ids"}}
 ]'
@@ -101,14 +69,14 @@ Delete is guarded by read-token confirmation.
 1. Arm-delete read:
 
 ```bash
-npx @khanglvm/outline-cli invoke documents.info \
+outline-cli invoke documents.info \
   --args '{"id":"<document-id>","armDelete":true,"view":"summary"}'
 ```
 
 2. Copy the returned `deleteReadReceipt.token`, then delete:
 
 ```bash
-npx @khanglvm/outline-cli invoke documents.delete \
+outline-cli invoke documents.delete \
   --args '{"id":"<document-id>","readToken":"<token>","performAction":true}'
 ```
 
@@ -128,9 +96,9 @@ Result mode:
 Temp-file management:
 
 ```bash
-npx @khanglvm/outline-cli tmp list
-npx @khanglvm/outline-cli tmp cat /absolute/path/from/result.json
-npx @khanglvm/outline-cli tmp gc --older-than-hours 24
+outline-cli tmp list
+outline-cli tmp cat /absolute/path/from/result.json
+outline-cli tmp gc --older-than-hours 24
 ```
 
 ## Profile Management
@@ -138,7 +106,7 @@ npx @khanglvm/outline-cli tmp gc --older-than-hours 24
 Add password-mode profile:
 
 ```bash
-npx @khanglvm/outline-cli profile add internal \
+outline-cli profile add internal \
   --base-url https://outline.company.com \
   --auth-type password \
   --username agent@company.com \
@@ -148,17 +116,17 @@ npx @khanglvm/outline-cli profile add internal \
 Select default profile:
 
 ```bash
-npx @khanglvm/outline-cli profile use prod
+outline-cli profile use prod
 ```
 
 Improve AI profile routing metadata:
 
 ```bash
-npx @khanglvm/outline-cli profile annotate prod \
+outline-cli profile annotate prod \
   --description "Production knowledge base" \
   --append-keywords "prod,runbook,incident"
 
-npx @khanglvm/outline-cli profile enrich prod \
+outline-cli profile enrich prod \
   --query "incident escalation process" \
   --titles "Incident Playbook,Escalation Matrix"
 ```
@@ -177,8 +145,9 @@ Use this short operating pattern when an AI agent drives the CLI:
 For structured AI playbooks and scenario guides:
 
 ```bash
-npx @khanglvm/outline-cli tools help ai-skills --view summary
-npx @khanglvm/outline-cli tools help ai-skills --scenario UC-12
+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
 ```
 
 ## Testing (Live Environment)
@@ -239,6 +208,5 @@ Release prerequisites:
 
 ## Reference Docs
 
-- Tool contracts: [`docs/TOOL_CONTRACTS.md`](docs/TOOL_CONTRACTS.md)
 - Agent rules for this repo: [`AGENTS.md`](AGENTS.md)
 - Release script: [`scripts/release.mjs`](scripts/release.mjs)

package/package.json

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

package/src/agent-skills.js

@@ -2,6 +2,67 @@ 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_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.",
+  steps: [
+    {
+      step: 1,
+      title: "Install outline-cli globally",
+      command: "npm i -g @khanglvm/outline-cli",
+      successCheck: "outline-cli --help",
+    },
+    {
+      step: 2,
+      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",
+      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",
+      command:
+        'outline-cli profile add <profile-id> --base-url <base-url> --api-key "<api-key>" --set-default',
+    },
+    {
+      step: 5,
+      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",
+      commandTemplates: [
+        'outline-cli invoke documents.search --args \'{"query":"onboarding checklist","mode":"semantic","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.",
+    "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.",
+  ],
+};
 
 const AI_GLOBAL_GUIDANCE = {
   principles: [
@@ -630,6 +691,32 @@ function normalizeView(view = "summary") {
   return normalized;
 }
 
+function normalizeQuickStartView(view = "summary") {
+  const normalized = String(view || "summary").toLowerCase();
+  if (normalized !== "summary" && normalized !== "full") {
+    throw new CliError("Invalid view for quick-start-agent help. Expected summary or full.", {
+      code: "QUICK_START_HELP_INVALID_VIEW",
+      view,
+    });
+  }
+  return normalized;
+}
+
+function summarizeQuickStartPlaybook() {
+  return {
+    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,
+    })),
+    interactionRules: QUICK_START_AGENT_PLAYBOOK.interactionRules,
+    nextCommand: "outline-cli tools help quick-start-agent --view full",
+  };
+}
+
 function normalizeScenario(input) {
   if (!input) {
     return null;
@@ -747,8 +834,25 @@ export function getAgentSkillHelp(options = {}) {
   };
 }
 
+export function getQuickStartAgentHelp(options = {}) {
+  const view = normalizeQuickStartView(options.view || "summary");
+  return {
+    section: QUICK_START_HELP_SECTION_ID,
+    version: QUICK_START_HELP_VERSION,
+    view,
+    ...(view === "full" ? QUICK_START_AGENT_PLAYBOOK : summarizeQuickStartPlaybook()),
+  };
+}
+
 export function listHelpSections() {
   return [
+    {
+      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.",
+      commandExample: "outline-cli tools help quick-start-agent --view full",
+    },
     {
       id: AI_HELP_SECTION_ID,
       title: "AI instruction skills",

package/src/cli.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import path from "node:path";
-import { getAgentSkillHelp, listHelpSections } from "./agent-skills.js";
+import { getAgentSkillHelp, getQuickStartAgentHelp, listHelpSections } from "./agent-skills.js";
 import {
   buildProfile,
   defaultConfigPath,
@@ -786,6 +786,29 @@ export async function run(argv = process.argv) {
         return;
       }
 
+      if (
+        sectionName === "quick-start-agent" ||
+        sectionName === "quickstart-agent" ||
+        sectionName === "quickstart" ||
+        sectionName === "setup"
+      ) {
+        await emitOutput(
+          store,
+          {
+            ok: true,
+            ...getQuickStartAgentHelp({
+              view: merged.view,
+            }),
+          },
+          merged,
+          {
+            label: "tools-help-quick-start-agent",
+            mode: merged.resultMode,
+          }
+        );
+        return;
+      }
+
       throw new CliError(
         `Unknown tools help section: ${section}. Supported: ${listHelpSections().map((row) => row.id).join(", ")}`
       );

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: "26d0616d3f957992d3bf8ecf5a243bed9afb4bd239710449c5e2b8df56117996",
-  generatedAt: "2026-03-05T13:45:11.761Z",
+  signature: "db2b8cd3d150b5be3b17246af7a254fc42ec500c3567a8be79ca2e4178f4657a",
+  generatedAt: "2026-03-06T00:27:55.266Z",
   files: [
   {
     "path": "src/action-gate.js",
@@ -12,11 +12,11 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
   },
   {
     "path": "src/agent-skills.js",
-    "sha256": "d9ea2f000689311ecb6bfae92c469dd16a2d4f64ce84098f121cad2a24dd4529"
+    "sha256": "3ec649a1e4fb475de47882223d2ca0e5bb049720cad1b456ea3ecd6ff1b74ecc"
   },
   {
     "path": "src/cli.js",
-    "sha256": "b19f98ced5aba789c860891bbc21f95d4a5443f185c6c48f00bced81eadc1acb"
+    "sha256": "bf37837390eaedadc6f8a8a8e279e61c12d56792f83cb4c53173439009cf5422"
   },
   {
     "path": "src/config-store.js",

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

@@ -1,15 +1,44 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 
-import { getAgentSkillHelp, listHelpSections } from "../src/agent-skills.js";
+import { getAgentSkillHelp, getQuickStartAgentHelp, listHelpSections } from "../src/agent-skills.js";
 import { CliError } from "../src/errors.js";
 
 test("listHelpSections exposes ai-skills section", () => {
   const sections = listHelpSections();
   assert.ok(Array.isArray(sections));
+  assert.ok(sections.some((section) => section.id === "quick-start-agent"));
   assert.ok(sections.some((section) => section.id === "ai-skills"));
 });
 
+test("getQuickStartAgentHelp returns summary by default", () => {
+  const payload = getQuickStartAgentHelp();
+
+  assert.equal(payload.section, "quick-start-agent");
+  assert.equal(payload.view, "summary");
+  assert.ok(Array.isArray(payload.steps));
+  assert.ok(payload.steps.length >= 4);
+  assert.equal(payload.nextCommand, "outline-cli tools help quick-start-agent --view full");
+});
+
+test("getQuickStartAgentHelp returns full payload and validates view", () => {
+  const payload = getQuickStartAgentHelp({ view: "full" });
+  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(Array.isArray(payload.interactionRules));
+
+  assert.throws(
+    () => getQuickStartAgentHelp({ view: "compact" }),
+    (err) => {
+      assert.ok(err instanceof CliError);
+      assert.equal(err.details?.code, "QUICK_START_HELP_INVALID_VIEW");
+      return true;
+    }
+  );
+});
+
 test("getAgentSkillHelp returns summary guidance by default", () => {
   const payload = getAgentSkillHelp();