@taskset/cli 5.1.0 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @taskset/cli
 
+## 6.0.0
+
+### Major Changes
+
+- Make Taskset agent-first and polyglot-friendly: discover repositories by `.taskset/`, treat `taskset.config.ts` as optional, support package-runner and global installs, and split docs for humans and agents.
+- 89c31c3: Replace sequential and ULID entity IDs with immutable 5-6 character lowercase hex IDs.
+  
+  Filenames are now `{sequence}-{slug}-{id}.md`. `taskset sync` and `task migrate-ids` migrate legacy IDs, normalize filenames, repair duplicate sequence prefixes by `createdAt`, and rewrite repository references. Default task and document list sorting uses `createdAt` so creation order remains stable. Agents and commands must cite the short `id`, not the mutable sequence prefix.
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [89c31c3]
+  - @taskset/core@6.0.0
+  - @taskset/contracts@6.0.0
+
 ## 5.1.0
 
 ### Minor Changes

package/README.md

@@ -1,42 +1,41 @@
 # @taskset/cli
 
-The public command-line adapter for Taskset. Full documentation is available at
-[taskset.false.foundation](https://taskset.false.foundation/), including the
-[complete CLI reference](./docs/cli-reference.md).
+The public command-line adapter for Taskset, the Git-native workspace for plans, research, decisions, runbooks, and executable tasks. Full documentation is on [taskset.false.foundation](https://taskset.false.foundation/), including the [CLI reference](./docs/cli-reference.md), [document types](./docs/document-types.md), and [agent guide](./docs/agents/index.md).
 
-The published package also ships the repository `docs/` tree and `skills/` tree
-beside the CLI so installed projects can load offline references from
-`node_modules/@taskset/cli/docs` and `node_modules/@taskset/cli/skills`.
+The published package ships the repository `docs/` and `skills/` trees beside the CLI so agents can load offline references from `node_modules/@taskset/cli/docs` and `node_modules/@taskset/cli/skills`.
+
+## Install
 
 ```bash
+npx @taskset/cli@latest init
+pnpm dlx @taskset/cli init
 pnpm add --save-dev @taskset/cli
-pnpm taskset init
-pnpm taskset task create --title "Document the release"
+npm install --global @taskset/cli
 ```
 
-The package owns argument tokenization, Zod-backed command validation, output,
-and exit-code mapping. Repository behavior is delegated to `@taskset/core`.
+```bash
+taskset document create research --title "Evaluate release options"
+taskset task create --title "Ship the release notes" --related your_research_id_here
+taskset document list --json
+taskset task list --json
+```
 
-Supported command groups:
+The package owns argument tokenization, Zod-backed command validation, output, and exit-code mapping. Repository behavior is delegated to `@taskset/core`.
+
+## Commands
 
 - `taskset init`, `config`, `doctor`, `generate`, and `sync`
 - `taskset task create|list|show|update|status|delete|migrate-ids`
 - `taskset document create|import|batch|list|show|update|status|delete` (`doc` is an alias)
 - `taskset snapshot create|list|restore`
 
-Use `task list --file <path> --impact` for direct and transitive code-impact
-queries. Repeated path values use OR, distinct filter categories use AND,
-repeated labels require every label, and planning or timestamp ranges are
-inclusive. Filters include
-`--estimate-min`/`--estimate-max`, `--effort-min`/`--effort-max`,
-`--duplicate`, `--sort order`, and due/created/updated before/after bounds.
-`tasks-for-file` was removed.
+`init` creates `.taskset/` for tasks, stories, flows, decisions, research, and runbooks without requiring a config file. Pass `--config` for optional `taskset.config.ts`.
+
+Exit code `0` means success, `1` means a repository or domain failure, and `2` means invalid CLI usage. Commands reserve stdout for requested output and send diagnostics to stderr.
 
-Exit code `0` means success, `1` means a repository or domain failure, and `2`
-means invalid CLI usage. Commands reserve stdout for requested output and send
-diagnostics or generation warnings to stderr.
+## Optional config helper
 
-`defineConfig` is re-exported for `taskset.config.ts`:
+`defineConfig` is re-exported for optional `taskset.config.ts`:
 
 ```typescript
 import { defineConfig } from '@taskset/cli'

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuGA,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACzC;AAwuBD,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAy4B/F"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuGA,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACzC;AA6uBD,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAu5B/F"}

package/dist/cli.js

@@ -5,7 +5,7 @@ import { DocumentIdSchema, DocumentStatusSchema, DocumentTimestampSchema, TaskId
 import { buildDocumentGraph, buildTaskIndex, createDocument, createSnapshot, createTask, DOCUMENT_SORT_DIRECTIONS, DOCUMENT_SORT_KEYS, DocumentQuerySchema, deleteDocument, deleteTask, diagnoseRepository, discoverRepository, executeDocumentBatch, generateViews, importDocument, initializeRepository, listDocuments, listSnapshots, migrateTaskIds, normalizeDocumentKind, normalizeRepositoryPath, queryDocuments, queryTasks, RepositoryPathError, readDocument, readTask, restoreSnapshot, serializeDocumentFile, serializeTaskFile, syncRepository, TASK_SORT_DIRECTIONS, TASK_SORT_KEYS, TaskQuerySchema, updateDocument, updateTask, } from '@taskset/core';
 import * as z from 'zod';
 const USAGE = `Usage:
-  taskset init [--cwd <path>]
+  taskset init [--config] [--cwd <path>]
   taskset config [--json] [--cwd <path>]
   taskset doctor [--json] [--cwd <path>]
   taskset generate [--json] [--cwd <path>]
@@ -67,6 +67,10 @@ const CommonValuesSchema = z.strictObject({
     cwd: CwdSchema,
     json: JsonSchema,
 });
+const InitValuesSchema = z.strictObject({
+    cwd: CwdSchema,
+    config: z.boolean().optional(),
+});
 const ConcurrencySchema = z.coerce.number().int().min(1).max(32).optional();
 const DocumentKindInputSchema = TrimmedStringSchema.transform((value, context) => {
     try {
@@ -724,6 +728,23 @@ export async function runCli(args, context = {}) {
             return 0;
         }
         if (command === 'init' || command === 'config' || command === 'doctor') {
+            if (command === 'init') {
+                const parsed = parseArgs({
+                    args: commandArgs,
+                    allowPositionals: false,
+                    options: {
+                        cwd: { type: 'string' },
+                        config: { type: 'boolean' },
+                    },
+                });
+                const values = parseSchema(InitValuesSchema, parsed.values, 'init options');
+                const commandCwd = resolveCommandCwd(cwd, values.cwd);
+                const repository = await initializeRepository(commandCwd, {
+                    writeConfig: values.config === true,
+                });
+                stdout(`Initialized Taskset in ${repository.rootDirectory}\n`);
+                return 0;
+            }
             const parsed = parseArgs({
                 args: commandArgs,
                 allowPositionals: false,
@@ -731,24 +752,23 @@ export async function runCli(args, context = {}) {
             });
             const values = parseSchema(CommonValuesSchema, parsed.values, `${command} options`);
             const commandCwd = resolveCommandCwd(cwd, values.cwd);
-            if (command === 'init') {
-                const repository = await initializeRepository(commandCwd);
-                stdout(`Initialized Taskset in ${repository.rootDirectory}\n`);
-                return 0;
-            }
             const repository = await discoverRepository(commandCwd);
             if (command === 'config') {
                 if (values.json) {
                     stdout(`${JSON.stringify({
                         rootDirectory: repository.rootDirectory,
                         configPath: repository.configPath,
+                        hasConfig: repository.hasConfig,
                         dataDirectory: repository.dataDirectory,
                         config: repository.config,
                     }, null, 2)}\n`);
                 }
-                else {
+                else if (repository.hasConfig) {
                     stdout(`${repository.configPath}\n`);
                 }
+                else {
+                    stdout(`defaults (${repository.rootDirectory})\n`);
+                }
                 return 0;
             }
             const result = await diagnoseRepository(repository);
@@ -793,7 +813,7 @@ export async function runCli(args, context = {}) {
             });
             stdout(values.json
                 ? `${JSON.stringify(result, null, 2)}\n`
-                : `Synced ${result.migrations.length} migrations and generated views\n`);
+                : `Synced ${result.migrations.length + result.documentMigrations.length} migrations and generated views\n`);
             return 0;
         }
         if (command === 'snapshot') {

package/docs/_meta.ts

@@ -5,4 +5,5 @@ export default {
 	'cli-reference': 'CLI Reference',
 	'task-files': 'Task Files',
 	'document-types': 'Document Types',
+	agents: 'For Agents',
 }

package/docs/agents/_meta.ts

@@ -0,0 +1,5 @@
+export default {
+	index: 'For Agents',
+	workflows: 'Agent Workflows',
+	commands: 'Agent Commands',
+}

package/docs/agents/commands.md

@@ -0,0 +1,70 @@
+---
+title: Use Taskset command contracts
+description: Machine-oriented contracts for discovery, JSON output, clear flags, search, and identifiers.
+contentType: Reference
+navLabel: Agent Commands
+---
+
+# Use Taskset command contracts
+
+This page quotes the contracts agents should rely on. For the full human reference, see [CLI reference](../cli-reference.md).
+
+## Discovery and defaults
+
+| Fact | Contract |
+| --- | --- |
+| Repository marker | Nearest ancestor `.taskset/` directory |
+| Optional config | `taskset.config.ts` beside that root |
+| Missing config | Built-in statuses, priorities, and defaults |
+| `taskset config --json` | Includes `rootDirectory`, `configPath`, `hasConfig`, `dataDirectory`, `config` |
+| `taskset init` | Creates `.taskset/`; `--config` writes optional config |
+
+## Output and exit codes
+
+- Stdout carries requested output
+- Stderr carries diagnostics and generation warnings
+- Exit `0` means success
+- Exit `1` means repository or domain failure
+- Exit `2` means usage or validation failure
+
+## Identifiers
+
+- Entity `id` values are immutable 5–6 character lowercase hex strings
+- Filenames are `{sequence}-{slug}-{id}.md`
+- Commands and relationships must use the short `id`
+- Never cite the mutable sequence prefix as identity
+
+## Array updates and clear flags
+
+Array options replace the whole stored array. Repeat the singular option once per desired value. Clear with the exact plural flag:
+
+- `--clear-dependencies`
+- `--clear-labels`
+- `--clear-assignees`
+- `--clear-reviewers`
+- `--clear-related`
+- `--clear-files`
+- `--clear-directories`
+- `--clear-projects`
+- `--clear-parent`
+- `--clear-owner`
+
+Do not guess a clear flag from the singular setter name.
+
+## Search and impact
+
+- `--search` is token-aware: every normalized term must match title or body
+- Terms may appear in any order
+- `--impact` expands file, directory, or dependency matches to dependent work
+
+## Document kinds
+
+Use only these kinds:
+
+- `story`
+- `flow`
+- `decision` (`adr`, `dr` aliases)
+- `research`
+- `runbook`
+
+Document statuses are `draft`, `ready`, `active`, `accepted`, `superseded`, and `archived`.

package/docs/agents/index.md

@@ -0,0 +1,99 @@
+---
+title: Operate Taskset as an agent
+description: Plan, research, decide, and track repository work with the Taskset CLI, skill, and JSON contracts.
+contentType: How-to
+navLabel: For Agents
+---
+
+# Operate Taskset as an agent
+
+Use this page when you are an agent operating Taskset in a repository. Humans should start with [Getting started](../getting-started.md). Maintainer architecture lives under [Maintainer docs](../maintainers/index.md).
+
+Taskset is not only a task tracker. You use it to capture plans, research, decisions, flows, runbooks, and the tasks that execute them in one Git-native graph.
+
+## Load the skill first
+
+Prefer the packaged skill before inventing workflow:
+
+```bash
+npx skills add FalseFoundation/taskset --skill taskset
+```
+
+Project and global skill installs both work. After a project npm install, offline copies also live at `node_modules/@taskset/cli/skills/taskset/SKILL.md`.
+
+## Invoke the CLI
+
+Do not assume `pnpm taskset`. Use whichever runner the environment provides:
+
+```bash
+npx @taskset/cli document list --json
+npx @taskset/cli task list --json
+pnpm dlx @taskset/cli doctor --json
+yarn dlx @taskset/cli document show your_document_id_here --json
+bunx @taskset/cli sync --json
+taskset task list --json
+```
+
+## Discover the repository
+
+1. Walk upward for `.taskset/`
+2. Load optional `taskset.config.ts` at that root when present
+3. Otherwise use built-in defaults
+
+No config file is required. `taskset init` creates `.taskset/` only. Pass `--config` when the repository wants an optional TypeScript overlay.
+
+## Choose the right artifact
+
+| If the work produces… | Create… |
+| --- | --- |
+| A user outcome or acceptance criteria | `story` |
+| A journey with variants and checks | `flow` |
+| Evidence, options, or a recommendation | `research` |
+| A lasting architectural or product choice | `decision` / `adr` |
+| A repeatable recovery or ops procedure | `runbook` |
+| Scoped execution with status and owners | `task` |
+
+Link documents and tasks with `--related`. Keep one-off scratch in the task body.
+
+## Core operating rules
+
+- Treat `.taskset/tasks/` and kind-specific document directories as the source of truth
+- Mutate through CLI commands when a command exists
+- Cite short hex ids such as `a1b2c3`, never filename sequence prefixes
+- Prefer `--json` for handoffs
+- Create follow-up tasks or checklist subtasks for newly discovered work
+- Create research, decision, runbook, story, or flow documents when work produces reusable evidence or lasting choices
+- Keep statuses current mid-work
+
+## Command map
+
+| Goal | Command |
+| --- | --- |
+| Inspect root and defaults | `taskset config --json` |
+| Validate repository | `taskset doctor --json` |
+| List or search tasks | `taskset task list --search "terms" --json` |
+| List or search documents | `taskset document list research --search "terms" --json` |
+| Show one entity | `taskset task show your_task_id_here --json` |
+| Create executable work | `taskset task create --title "Describe the work"` |
+| Create durable memory | `taskset document create research --title "Evaluate options" --related your_task_id_here` |
+| Change status | `taskset task status your_task_id_here doing` |
+| Impact query | `taskset task list --file path/or/dir --impact --json` |
+| Repair and rebuild | `taskset sync --json` |
+
+Full contracts: [CLI reference](../cli-reference.md) and [Agent command contracts](commands.md).
+
+## Workflow checklist
+
+1. Confirm the repository root with `taskset config --json`
+2. Search existing tasks and documents before creating duplicates
+3. Capture durable evidence or decisions as documents mid-work
+4. Create or update tasks for executable delivery
+5. Resolve ownership before mutating assigned work
+6. Keep statuses current, then re-validate after edits
+
+## Related pages
+
+- [Agent workflows](workflows.md)
+- [Agent command contracts](commands.md)
+- [Document types](../document-types.md)
+- [Task files](../task-files.md)

package/docs/agents/llms.txt

@@ -0,0 +1,28 @@
+# Taskset
+
+> Git-native Markdown workspace for planning, research, decisions, operations, and delivery.
+
+Taskset stores stories, flows, research, decisions, runbooks, and tasks under `.taskset/`. The CLI is published as `@taskset/cli` and runs through package runners or a global install. Config files are optional.
+
+## For agents
+
+- [Operate Taskset as an agent](https://taskset.false.foundation/docs/agents)
+- [Follow agent workflows](https://taskset.false.foundation/docs/agents/workflows)
+- [Use Taskset command contracts](https://taskset.false.foundation/docs/agents/commands)
+- [Choose a document type](https://taskset.false.foundation/docs/document-types)
+- [Understand task files](https://taskset.false.foundation/docs/task-files)
+- [CLI reference](https://taskset.false.foundation/docs/cli-reference)
+
+## For humans
+
+- [Keep the whole delivery story beside the code](https://taskset.false.foundation/docs)
+- [Start a Taskset repository](https://taskset.false.foundation/docs/getting-started)
+- [Configure Taskset defaults](https://taskset.false.foundation/docs/configuration)
+
+## Optional offline skill
+
+After install, load `node_modules/@taskset/cli/skills/taskset/SKILL.md`, or install with:
+
+```text
+npx skills add FalseFoundation/taskset --skill taskset
+```

package/docs/agents/workflows.md

@@ -0,0 +1,50 @@
+---
+title: Follow agent workflows in Taskset
+description: Ownership checks, mid-work updates, documents, and monorepo habits for agent operators.
+contentType: How-to
+navLabel: Agent Workflows
+---
+
+# Follow agent workflows in Taskset
+
+These workflows assume the CLI is available and `.taskset/` already exists. Initialize with `taskset init` when it does not. Use documents for durable memory and tasks for execution; link them so later agents inherit the full story.
+
+## Before you execute a task
+
+1. Run `taskset task show your_task_id_here --json`
+2. Resolve `git config --get user.name`
+3. Compare owner and assignees with that identity
+4. Pause for confirmation when another person owns or is exclusively assigned the task
+5. Check unresolved dependencies and blockers before status changes
+
+Matching ownership does not override blockers. A generic instruction such as “work on the next task” does not override another person’s assignment.
+
+## While you execute
+
+- Set the active task to `doing` when work starts
+- Create child tasks (`--parent`) or checklist items (`- [ ]`) for newly discovered work
+- Check off finished checklist items as `- [x]`
+- Mark finished child tasks `done`
+- Create research, decision, runbook, story, or flow documents when evidence or lasting choices appear
+- Link documents and tasks with `--related`
+- Update a primary skill when the session designates one and a lasting lesson emerges
+
+Do not leave discovered work only in chat.
+
+## Close-out
+
+1. Confirm acceptance criteria are met
+2. Confirm every tracked subtask is finished or intentionally resolved
+3. Set the parent task to `done`
+4. Run the repository’s relevant tests or `taskset doctor --json` when the change touched contracts or many files
+
+## Monorepo habits
+
+- Prefer declared package names and existing Taskset projects over directory-name guesses
+- Record `--depends-on` only for real execution prerequisites
+- Attach the narrowest accurate `--file` or `--directory` scopes
+- Validate the changed package and affected dependents
+
+## Batch and sync
+
+Use `taskset document batch manifest.json --json` for multi-document jobs. Use `taskset sync --json` after upgrades or when filenames, ids, or generated views need repair.

package/docs/cli-reference.md

@@ -1,16 +1,15 @@
 ---
-title: CLI Reference
+title: Look up Taskset CLI commands
 description: Complete reference for the taskset command-line interface.
+contentType: Reference
+navLabel: CLI Reference
 ---
 
-# CLI Reference
+# Look up Taskset CLI commands
 
-The `taskset` command is a thin adapter over `@taskset/core`. It parses
-arguments, validates command options, calls core operations, and renders human
-or JSON output.
+The `taskset` command is a thin adapter over `@taskset/core` for the full Taskset surface: stories, flows, research, decisions, runbooks, and tasks. It parses arguments, validates options, calls core operations, and renders human or JSON output.
 
-Use `pnpm taskset <command>` when Taskset is installed as a project
-dependency. The examples below use `taskset` directly for brevity.
+Invoke it with `npx @taskset/cli`, `pnpm dlx @taskset/cli`, `yarn dlx @taskset/cli`, `bunx @taskset/cli`, a project binary, or a global install. Examples below use `taskset` directly.
 
 ## Common Behavior
 
@@ -46,12 +45,10 @@ Exit codes:
 ### `init`
 
 ```bash
-taskset init [--cwd <path>]
+taskset init [--config] [--cwd <path>]
 ```
 
-Initializes a Taskset repository in the target directory. The command creates
-`taskset.config.ts`, `.taskset/tasks/`, and `.taskset/.gitignore` when they do
-not already exist.
+Initializes a Taskset repository. The command resolves a root from an existing `.taskset/`, Git or workspace markers, or the working directory, then creates `.taskset/` task and document directories plus `.taskset/.gitignore` when they do not already exist. Pass `--config` to also write optional `taskset.config.ts`.
 
 Human output:
 
@@ -65,15 +62,15 @@ Initialized Taskset in <root-directory>
 taskset config [--json] [--cwd <path>]
 ```
 
-Discovers the nearest `taskset.config.ts` by walking upward from the working
-directory.
+Discovers the nearest `.taskset/` directory by walking upward from the working directory. Optional `taskset.config.ts` at that root overlays defaults when present.
 
-Human output is the config file path. JSON output contains:
+Human output is the config file path when a config exists, or `defaults (<root-directory>)` when it does not. JSON output contains:
 
 ```json
 {
   "rootDirectory": "...",
   "configPath": "...",
+  "hasConfig": false,
   "dataDirectory": "...",
   "config": {}
 }
@@ -311,7 +308,7 @@ Human output is the serialized task Markdown. JSON output contains:
 
 ```json
 {
-  "relativePath": ".taskset/tasks/0000001-short-title.md",
+  "relativePath": ".taskset/tasks/0000001-short-title-a1b2c3.md",
   "metadata": {},
   "body": "...",
   "derived": {}
@@ -384,11 +381,12 @@ alongside the deleted task record.
 taskset task migrate-ids [--json] [--cwd <path>]
 ```
 
-Atomically converts legacy `TS-` task IDs to seven-digit, title-derived IDs and
-rewrites canonical relationships plus references in repository text files.
-Dependencies, Git internals, build output, caches, generated views, indexes,
-and snapshots are excluded. Human output is a tab-separated
-old-to-new mapping; JSON emits the same mapping as objects.
+Atomically converts legacy `TS-` and sequential task IDs to immutable short hex
+IDs, normalizes filenames to `{sequence}-{slug}-{id}.md`, repairs duplicate
+sequence prefixes by `createdAt`, and rewrites canonical relationships plus
+references in repository text files. Dependencies, Git internals, build output,
+caches, generated views, indexes, and snapshots are excluded. Human output is a
+tab-separated old-to-new mapping; JSON emits the same mapping as objects.
 
 ### `sync`
 
@@ -396,9 +394,11 @@ old-to-new mapping; JSON emits the same mapping as objects.
 taskset sync [--concurrency <count>] [--json] [--cwd <path>]
 ```
 
-Ensures every canonical document directory exists under `.taskset`, applies
-legacy task-ID and repository-reference migrations, and rebuilds generated
-views. Progress counts and percentages are sent to stderr.
+Ensures every canonical document directory exists under `.taskset`, migrates
+legacy task and document IDs to short hex IDs, normalizes filenames, repairs
+duplicate sequence prefixes by `createdAt`, rewrites repository text
+references, and rebuilds generated views. Progress counts and percentages are
+sent to stderr.
 
 ## Document Commands
 

package/docs/configuration.md

@@ -1,13 +1,29 @@
 ---
-title: Configuration
-description: How taskset.config.ts identifies and configures a Taskset repository.
+title: Configure Taskset defaults
+description: Optionally add taskset.config.ts to overlay defaults and vocabulary on a `.taskset/` repository.
+contentType: How-to
+navLabel: Configuration
 ---
 
-# Configuration
+# Configure Taskset defaults
 
-Taskset usage begins with `taskset.config.ts` at the repository root. Commands
-started in nested packages or directories walk upward until they find this
-file.
+Taskset repositories are identified by a `.taskset/` directory. `taskset.config.ts` is optional. When the file is absent, built-in statuses, priorities, and creation defaults apply.
+
+## When to add a config file
+
+Add `taskset.config.ts` when you need at least one of these:
+
+- A repository `project.name`
+- Different task creation defaults
+- A reduced or reordered status or priority vocabulary
+
+Create one during init:
+
+```bash
+taskset init --config
+```
+
+Or author the file beside `.taskset/`:
 
 ```typescript
 import { defineConfig } from '@taskset/cli'
@@ -30,32 +46,18 @@ export default defineConfig({
 
 ## Contract
 
-- `project.name` is optional repository metadata.
-- `tasks.defaults.status`, `priority`, and `labels` are optional defaults used
-  by task creation.
-- `tasks.statuses` selects and orders the repository's active status vocabulary
-  from Taskset's canonical values. Task creation, updates, lifecycle changes,
-  listing, generated views, and diagnostics reject or report task statuses
-  outside that list. The default status must be included.
-- `tasks.priorities` selects and orders the repository's active priority
-  vocabulary from Taskset's canonical values. Task creation rejects a priority
-  outside that list, and the default priority must be included.
-- `urgent` is the highest supported priority. Taskset does not maintain a
-  separate urgency field because two overlapping importance scales make task
-  ordering harder to understand and keep consistent.
-- Unknown fields, invalid enum values, empty names, and duplicate default
-  labels or vocabulary values are rejected.
-- The config file is executable trusted project code and may use erasable
-  TypeScript syntax supported by the repository's Node version.
-
-The config identifies behavior; it is not task storage. Canonical task state
-remains under `.taskset/tasks/`, regardless of configuration.
+- `project.name` is optional repository metadata
+- `tasks.defaults.status`, `priority`, and `labels` are optional creation defaults
+- `tasks.statuses` selects and orders the active status vocabulary from Taskset’s canonical values
+- `tasks.priorities` selects and orders the active priority vocabulary from Taskset’s canonical values
+- `urgent` is the highest supported priority
+- Unknown fields, invalid enum values, empty names, and duplicate default labels or vocabulary values are rejected
+- The config file is trusted project TypeScript and may use erasable syntax supported by your Node version
+
+The config identifies behavior. It is not task storage. Canonical task state remains under `.taskset/tasks/`.
 
 ## Discovery
 
-`taskset init` creates a minimal config when one does not exist and initializes
-`.taskset/tasks/`. Other commands require a discoverable config and report an
-error when run outside a Taskset repository.
+Commands started in nested directories walk upward until they find `.taskset/`. If `taskset.config.ts` exists at that root, Taskset loads and validates it. Otherwise it uses built-in defaults.
 
-Use `taskset config --json` to inspect the discovered root and resolved
-defaults.
+Use `taskset config --json` to inspect the discovered root, whether a config file is present, and the resolved defaults.