Update README, add CLAUDE.md, and set up lefthook

.github/workflows/lint.yml

@@ -0,0 +1,34 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run type-check
+
+      - name: Lint and format check
+        run: npx biome check

.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test

.gitignore

@@ -1,2 +1,3 @@
 node_modules/
 dist/
+.claude/settings.local.json

CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```sh
+npm install           # install dependencies
+npm run build         # compile TypeScript to dist/
+npm run dev           # watch mode (rebuild on changes)
+npm run type-check    # typecheck without emitting
+npm run test          # run all tests
+npx vitest run src/__tests__/output.test.ts  # run a single test file
+npm run format        # biome lint + format (auto-fix)
+```
+
+After building, `npm link` makes the `ol` binary available globally.
+
+## Architecture
+
+ESM-only TypeScript CLI using Commander.js. Entry point: `src/index.ts` creates the program and registers four command modules.
+
+### Command pattern
+
+Each file in `src/commands/` exports a `registerXxxCommand(program)` function that defines subcommands with Commander's chaining API. Commands use async action handlers.
+
+### Lib modules
+
+- **api.ts**: Single `apiRequest<T>(path, body)` function. All Outline API calls are POST with Bearer auth. Wraps requests in spinner with per-endpoint messages (SPINNER_MESSAGES map).
+- **auth.ts**: Config stored at `~/.config/outline-cli/config.json`. Token/URL resolution: env var → config file → default.
+- **output.ts**: `outputItem()` and `outputList()` handle three output modes (human/json/ndjson). Commands define a `humanFormatter` function and an `essentialKeys` array for JSON field filtering.
+- **spinner.ts**: `withSpinner(opts, fn)` wrapper using yocto-spinner. Auto-disables on non-TTY, JSON output, CI, `--no-spinner` flag.
+- **markdown.ts**: Terminal markdown rendering via marked + marked-terminal.
+
+### Key patterns
+
+- Document IDs are resolved from full URLs or slugs via regex extraction in `resolveId()`.
+- Text input for create/update supports `--text` inline or `--file` path, with auto title extraction from markdown headings.
+- Delete operations require `--confirm` flag.
+
+## Testing
+
+Vitest with module mocking. Tests live in `src/__tests__/`. Common patterns:
+- Mock `apiRequest` with `vi.mock()`
+- Stub `fetch` globally for API tests
+- Capture `console.log` calls in an array for output assertions
+- Use `program.exitOverride()` + `program.parseAsync()` to test command parsing
+- Auth tests use tmpdir with `process.pid` for filesystem isolation
+
+## Style
+
+- Biome: tabs for indentation, auto-sorted imports
+- TypeScript strict mode, target ES2022, NodeNext modules
+- Avoid `any` types and forced typecasts
+- Prefer `for` loops over `.forEach()`

README.md

@@ -5,7 +5,11 @@ CLI for the [Outline](https://www.getoutline.com) wiki/knowledge base API.
 ## Install
 
 ```sh
-npm install -g outline-cli
+git clone https://github.com/gnapse/outline-cli.git
+cd outline-cli
+npm install
+npm run build
+npm link
 ```
 
 ## Auth
@@ -26,19 +30,21 @@ Self-hosted instances: provide your instance URL during `ol auth login` or set `
 
 ```sh
 # Search
-ol search "query" --limit 10 --collection <id>
+ol search "query" --limit 10 --collection <id> --status published
 
-# Documents
+# Documents (alias: ol doc)
 ol document list --collection <id> --sort updatedAt --direction DESC
-ol document get <urlId>
+ol document get <urlId>              # renders markdown for terminal
+ol document get <urlId> --raw        # outputs raw markdown
+ol document open <urlId>             # opens in browser
 ol document create --title "Title" --collection <id> --file doc.md --publish
 ol document update <urlId> --file updated.md
 ol document delete <urlId> --confirm
 ol document move <urlId> --collection <target-id>
 ol document archive <urlId>
 ol document unarchive <urlId>
 
-# Collections
+# Collections (alias: ol col)
 ol collection list
 ol collection get <id>
 ol collection create --name "Engineering" --color "#4CAF50"

biome.json

@@ -1,12 +1,12 @@
 {
-  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
-  "organizeImports": { "enabled": true },
-  "linter": {
-    "enabled": true,
-    "rules": { "recommended": true }
-  },
-  "formatter": {
-    "enabled": true,
-    "indentStyle": "tab"
-  }
+	"$schema": "https://biomejs.dev/schemas/2.3.12/schema.json",
+	"assist": { "actions": { "source": { "organizeImports": "on" } } },
+	"linter": {
+		"enabled": true,
+		"rules": { "recommended": true }
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	}
 }

lefthook.yml

@@ -0,0 +1,13 @@
+pre-commit:
+  commands:
+    type-check:
+      run: npm run type-check
+    biome:
+      glob: '*.{ts,js,json}'
+      run: npx biome check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}
+      stage_fixed: true
+
+pre-push:
+  commands:
+    test:
+      run: npm test