@taskset/cli 5.1.0 → 6.0.0

package/docs/document-types.md

@@ -1,14 +1,13 @@
 ---
-title: Document Types
+title: Choose a Taskset document type
 description: Canonical stories, flows, decisions, research, and runbooks.
+contentType: Conceptual
+navLabel: Document Types
 ---
 
-# Document Types
+# Choose a Taskset document type
 
-Taskset stores durable project context beside tasks without forcing every note
-into a task lifecycle. Each type has strict common frontmatter and a body
-template suited to its purpose. Documents use the same planning, people, path,
-and relationship metadata fields as tasks, with document-specific statuses.
+Documents are how Taskset keeps product and engineering memory: what to build, what you learned, what you decided, and how to recover. Use them when the material should outlive a single task. Each type has strict common frontmatter and a body template suited to its purpose. Documents share planning, people, path, and relationship fields with tasks, and use document-specific statuses.
 
 | Type | Directory | Template focus |
 | --- | --- | --- |
@@ -24,13 +23,15 @@ Create a document from its template:
 taskset document create story --title "Member signs in via SSO"
 taskset document create flow --title "Recover a delayed deposit"
 taskset document create adr --title "Use transactional outbox"
-taskset document create research --title "Evaluate queue providers" --related <task-id>
+taskset document create research --title "Evaluate queue providers" --related your_task_id_here
 taskset document create runbook --title "Recover consumer lag"
 ```
 
-IDs and filenames use a per-type seven-digit sequence and title slug, for
-example `.taskset/flows/0000001-member-signs-in-via-sso.md`. Disposable metadata
-indexes for that kind live beside the files in `.taskset/flows/.generated/`.
+Document IDs are immutable 5-6 character lowercase hex values. Filenames keep a
+per-type display sequence and title slug, for example
+`.taskset/flows/0000001-member-signs-in-via-sso-a1b2c3.md`. Agents and commands
+reference the short `id`. Disposable metadata indexes for that kind live beside
+the files in `.taskset/flows/.generated/`.
 
 ## Query And Mutation
 
@@ -82,8 +83,8 @@ safe for automation.
 [
   { "action": "create", "input": { "type": "story", "title": "Member upgrades" } },
   { "action": "import", "sourcePath": "docs/flows/checkout.md", "options": { "type": "flow" } },
-  { "action": "update", "id": "0000001-member-upgrades", "type": "story", "input": { "status": "ready" } },
-  { "action": "export", "id": "0000001-member-upgrades", "type": "story", "targetPath": "exports/member-upgrades.md" }
+  { "action": "update", "id": "a1b2c3", "type": "story", "input": { "status": "ready" } },
+  { "action": "export", "id": "a1b2c3", "type": "story", "targetPath": "exports/member-upgrades.md" }
 ]
 ```
 
@@ -93,8 +94,10 @@ taskset sync --concurrency 8
 ```
 
 `taskset sync` creates missing document-kind directories inside `.taskset`,
-migrates legacy task filenames and references throughout repository text files,
-refreshes data `.gitignore` rules for scoped `.generated/` directories, removes
-legacy global `.taskset/generated/`, and rebuilds generated views. Build
-outputs, dependencies, caches, snapshots, and Git internals are excluded from
-reference rewriting.
+migrates legacy task and document IDs to short hex IDs, normalizes
+`{sequence}-{slug}-{id}.md` filenames, repairs duplicate sequence prefixes by
+`createdAt`, rewrites repository text references, refreshes data `.gitignore`
+rules for scoped `.generated/` directories, removes legacy global
+`.taskset/generated/`, and rebuilds generated views. Build outputs,
+dependencies, caches, snapshots, and Git internals are excluded from reference
+rewriting.

package/docs/getting-started.md

@@ -1,99 +1,106 @@
 ---
-title: Getting Started
-description: Initialize Taskset in a project and create the first repository task.
+title: Start a Taskset repository
+description: Install the CLI, initialize `.taskset/`, and capture your first plan, decision, and task in any language repository.
+contentType: Tutorial
+navLabel: Getting Started
 ---
 
-# Getting Started
+# Start a Taskset repository
 
-Taskset keeps project work in human-readable Markdown beside the code. The
-current pre-alpha release is intended for local repository use.
+This guide initializes Taskset in a repository and walks one delivery loop: capture intent, record research or a decision, then track the work. You do not need a JavaScript app, and you do not need `taskset.config.ts`.
 
 ## Requirements
 
-- Node.js 24 or newer
-- pnpm 11 or newer
+- Node.js 24 or newer to run the published CLI
+- Any Git repository or project root you can write to
 
-## Install
+## Install the CLI
 
-Install the published package as a development dependency in the project that
-will own the tasks:
+Pick one install style:
+
+```bash
+npx @taskset/cli@latest --help
+```
 
 ```bash
 pnpm add --save-dev @taskset/cli
 ```
 
-The package exposes the `taskset` executable.
+```bash
+npm install --global @taskset/cli
+```
+
+The package exposes the `taskset` executable. Package runners work in repositories that never declare a Node dependency.
 
-## Initialize
+## Initialize the repository
 
-Run Taskset from the repository root:
+Run init from the repository root, or from a nested directory when Git or workspace markers identify the root:
 
 ```bash
-pnpm taskset init
+taskset init
 ```
 
 This creates:
 
 ```text
-taskset.config.ts
 .taskset/
 ├── .gitignore
-└── tasks/
+├── tasks/
+├── stories/
+├── flows/
+├── decisions/
+├── research/
+└── runbooks/
 ```
 
-The config controls validated defaults. Task Markdown under `.taskset/tasks/`
-remains the canonical project state. The nested ignore file excludes
-`.taskset/cache/`, per-entity `.generated/` directories, and `.taskset/snapshots/`.
-Snapshots are non-authoritative safety checkpoints; tasks remain canonical.
-
-## Create And Inspect Work
+Add an optional config file only when you need custom task defaults:
 
 ```bash
-pnpm taskset task create --title "Add repository validation"
-pnpm taskset task list
-pnpm taskset task show <task-id>
-pnpm taskset task update <task-id> --status doing
+taskset init --config
 ```
 
-Task files can also be read and reviewed directly without Taskset installed.
+The nested ignore file excludes `.taskset/cache/`, per-entity `.generated/` directories, and `.taskset/snapshots/`. Snapshots are non-authoritative safety checkpoints. Markdown under `.taskset/` remains canonical.
+
+## Capture intent, then track delivery
 
-## Query And Validate Work
+Start with the durable context, then create the task that implements it:
 
 ```bash
-pnpm taskset task list --status doing --label core --json
-pnpm taskset task list --file packages/core --impact --json
-pnpm taskset doctor
+taskset document create story --title "Member signs in via SSO"
+taskset document create research --title "Compare SSO providers" --related your_story_id_here
+taskset document create adr --title "Use OIDC for member SSO" --related your_research_id_here
+taskset task create --title "Add SSO callback handler" --related your_decision_id_here --file packages/api/src/auth.ts
+taskset task list
+taskset document list --json
 ```
 
-File and directory filters use normalized repository-relative containment
-matching. With `--impact`, list output groups direct matches and tasks that
-transitively depend on them. Other filters select the direct set before graph
-expansion. `doctor` reports all readable format and graph failures in one
-non-mutating pass.
+You can read every file directly in the editor without the CLI. Cite entities by short hex `id`, never by filename sequence prefixes.
 
-## Generated Views And Migration
+## Query and validate the graph
 
 ```bash
-pnpm taskset generate
-pnpm taskset snapshot create
-pnpm taskset snapshot list
+taskset task list --status doing --label core --json
+taskset document list research --search "SSO" --json
+taskset task list --file packages/api --impact --json
+taskset doctor
 ```
 
-Snapshot restore previews by default unless `--apply` is present.
+File and directory filters use repository-relative containment. With `--impact`, list output groups direct matches and work that transitively depends on them. `doctor` reports readable format and graph failures in one non-mutating pass.
 
-## Complete Or Remove Work
+## Finish or remove work
 
 ```bash
-pnpm taskset task status <task-id> done
-pnpm taskset task delete <task-id>
+taskset task status your_task_id_here done
+taskset document status your_research_id_here accepted --type research
+taskset task delete your_task_id_here
 ```
 
-Completed and canceled tasks are terminal. Deletion fails while another task
-depends on the target. Use `--remove-dependencies` only when Taskset should
-remove those inbound references and the task together.
+Completed and canceled tasks are terminal. Deletion fails while another task depends on the target. Use `--remove-dependencies` only when Taskset should remove those inbound references and the task together.
 
 ## Next
 
-- [Configure task defaults](configuration.md)
-- [Use the complete CLI reference](cli-reference.md)
+- [Choose a document type](document-types.md)
 - [Understand task files](task-files.md)
+- [Configure defaults](configuration.md)
+- [Use the complete CLI reference](cli-reference.md)
+- [Follow the agent guide](agents/index.md)

package/docs/index.md

@@ -1,37 +1,43 @@
 ---
-title: Taskset
-description: Offline, inline, AI-friendly project awareness stored beside the code.
+title: Keep the whole delivery story beside the code
+description: Taskset stores plans, research, decisions, runbooks, and tasks as Markdown in your repository for agents and humans.
+contentType: Landing
+navLabel: Overview
 ---
 
-# Taskset
+# Keep the whole delivery story beside the code
 
-Taskset is an offline, inline, AI-friendly, human-readable task manager designed
-to accelerate software delivery and give development teams immediate awareness
-of the work surrounding their code.
+Taskset is a local-first delivery workspace. You keep stories, research, decisions, flows, runbooks, and executable tasks as Markdown under `.taskset/`, so agents and humans share one reviewable source of truth.
 
-Tasks and project knowledge live inside the repository as Markdown. Git supplies
-history, branches, review, and collaboration. Taskset supplies a consistent
-domain model and interfaces over those files.
+Install the CLI as `@taskset/cli` from npm. Run it with `npx`, `pnpm dlx`, `yarn dlx`, `bunx`, a project dependency, or a global install.
 
-Install the command-line package from npm as `@taskset/cli`.
+## What belongs in Taskset
 
-## Core Promise
+- **Plan**: stories and flows that define outcomes and journeys
+- **Learn**: research that captures evidence and recommendations
+- **Decide**: decisions and ADRs that lock lasting choices
+- **Operate**: runbooks that make recovery safe to repeat
+- **Deliver**: tasks that carry ownership, status, dependencies, and code impact
 
-- Work remains readable without Taskset installed.
-- Developers can operate locally without a mandatory service.
-- Humans and AI agents inspect the same project context.
-- CLI, TUI, MCP, editor, Kanban, and reporting views share one source of truth.
-- Monorepo projects and code relationships are first-class.
+Documents preserve memory. Tasks move work. Relationships keep the graph honest.
 
-## Current Status
+## What you get
 
-Taskset is pre-alpha. The CLI supports repository initialization, configuration
-inspection, validated task CRUD and lifecycle changes, repository diagnostics,
-generated views, snapshots, metadata queries, and file-impact analysis.
+- Project knowledge stays in the repository it describes
+- Markdown remains readable without Taskset installed
+- Agents and humans inspect the same plans, decisions, and work
+- CLI, skills, and future interfaces share one domain model
+- Monorepo paths and code relationships are first-class
 
-## Read Next
+## What the CLI covers
 
-- [Getting started](getting-started.md)
-- [Configuration](configuration.md)
-- [CLI reference](cli-reference.md)
-- [Task files](task-files.md)
+The CLI initializes repositories, manages optional configuration, creates and queries tasks and documents, runs diagnostics, builds generated views, snapshots state, and syncs the tree after upgrades or repairs.
+
+## Choose your path
+
+- [Start a Taskset repository](getting-started.md)
+- [Choose a document type](document-types.md)
+- [Understand task files](task-files.md)
+- [Configure defaults when you need them](configuration.md)
+- [Look up every CLI command](cli-reference.md)
+- [Read agent workflows and contracts](agents/index.md)

package/docs/maintainers/architecture/decisions/0001-documentation-platform.md

@@ -1,70 +1,44 @@
 ---
 title: "ADR 0001: Documentation Platform"
-description: Render canonical user documentation through the Taskset website.
+description: Render canonical documentation through the Taskset website for humans, agents, and maintainers.
 ---
 
 # ADR 0001: Documentation Platform
 
 - Status: Accepted
 - Date: 2026-06-12
+- Updated: 2026-10-03
 
 ## Context
 
-Taskset needs one documentation source that is readable on Git hosts and can
-also power a documentation website. User guidance and repository maintenance
-material have different audiences and should remain visibly separated.
+Taskset needs one documentation source that is readable on Git hosts and can also power a documentation website. Human usage guidance, agent operating contracts, and repository maintenance material have different audiences and should remain visibly separated.
 
 ## Decision
 
-- Keep canonical user documentation in the root `docs/` directory.
-- Keep contributor, product, architecture, ADR, testing, and technology
-  material under `docs/maintainers/`.
-- Use plain Markdown by default and MDX only for interactive pages.
-- Build `apps/www` with Next.js App Router, Nextra, and the stock Nextra docs
-  and blog themes.
-- Expose root `docs/` as the app's Nextra `content` directory through a
-  repository-relative symlink.
-- Render top-level usage docs and `docs/maintainers/` through separate route
-  layouts and page maps so their navigation stays audience-specific.
-- Keep chronological release and project posts under `apps/www/posts/`.
-- Isolate usage docs, maintainer docs, and blog layouts and MDX component sets
-  by route.
-- Keep the Nextra configuration and layout close to the upstream defaults.
-
-Nextra supports App Router content-directory routing and typed `_meta.ts`
-navigation:
-
-- <https://nextra.site/docs/file-conventions/content-directory>
-- <https://nextra.site/docs/docs-theme/start>
+- Keep canonical documentation in the root `docs/` directory
+- Keep human usage pages at the top level of `docs/`
+- Keep agent operating guidance under `docs/agents/`, with root `AGENTS.md` and packaged `skills/` as offline entrypoints
+- Keep contributor, product, architecture, ADR, testing, and technology material under `docs/maintainers/`
+- Publish an agent discovery index at `apps/www/public/llms.txt` (served as `/llms.txt`); copy it into the packaged CLI docs for offline use
+- Use plain Markdown by default and MDX only for interactive pages
+- Build `apps/www` with Next.js App Router, Nextra, and the stock Nextra docs and blog themes
+- Expose root `docs/` as the app’s Nextra `content` directory through a repository-relative symlink
+- Render top-level usage docs (including `docs/agents/`) and `docs/maintainers/` through separate route layouts and page maps
+- Keep chronological release and project posts under `apps/www/posts/`
+- Follow the [Vercel writing guidelines](https://github.com/vercel-labs/writing-guidelines) for public prose voice and structure
 
 ## Why
 
-This matches the existing Next.js direction, provides navigation and search
-without a custom content loader, and keeps user documentation readable in its
-canonical location. Moving maintainer material into a dedicated
-`docs/maintainers/` section prevents the root README and user pages from
-becoming contributor handbooks.
+This keeps one Markdown source of truth while matching how agent-first tools expose denser contracts beside human onboarding. Maintainer material stays out of the primary product navigation. Agent pages and `llms.txt` give coding agents a short index without inventing a second product truth.
 
 ## Implementation Contract
 
-`apps/www/content` points to `../../docs`. The usage docs catch-all route loads
-top-level content and excludes `docs/maintainers/` from its page map. The
-`/maintainers` route loads the same content directory with a maintainer-rooted
-page map. The app may generate `.next/`, search data, and static output, but
-none of those become documentation source.
-
-`apps/www/posts/` is the source for blog Markdown. An app-local registry maps
-each post to `/posts/[slug]` so static export can enumerate routes without
-copying posts into `docs/`. The global MDX component file contains only base
-Nextra components; docs and blog routes apply their own theme components.
+`apps/www/content` points to `../../docs`. The usage docs catch-all route loads top-level content, including `docs/agents/`, and excludes `docs/maintainers/` from its page map. The `/maintainers` route loads the same content directory with a maintainer-rooted page map. Root `AGENTS.md` is repository-local agent guidance and may be linked from docs, but docs remain canonical for published pages. Do not place non-Markdown discovery files such as `llms.txt` under `docs/`; Nextra imports the content tree as modules and only Markdown/MDX pages belong there.
 
 ## Consequences
 
-- Documentation changes are reviewable without building the site.
-- Blog posts are reviewable as app-local Markdown without a CMS.
-- The site build must include root `docs/` files in its input.
-- New posts must be added to the app-local static post registry.
-- MDX components remain owned by `apps/www`.
-- Maintainer documentation is reviewed from `docs/maintainers/` and remains in
-  its own `/maintainers` navigation section.
-- Broken links and invalid frontmatter should fail CI.
+- Documentation changes are reviewable without building the site
+- Blog posts are reviewable as app-local Markdown without a CMS
+- New agent pages belong under `docs/agents/` and appear in usage navigation
+- Maintainer documentation remains in its own `/maintainers` navigation section
+- Broken links and invalid frontmatter should fail CI

package/docs/maintainers/development/contributing.md

@@ -5,8 +5,7 @@ description: Repository setup, Taskset dogfooding, pull requests, and completion
 
 # Contributing
 
-Taskset is pre-alpha. Strengthen the core file format and workflow before
-expanding the number of interfaces.
+Keep the core file format and workflow coherent when you change interfaces, packages, or docs.
 
 ## Start Here
 
@@ -27,7 +26,7 @@ Use the Node and pnpm versions declared by `.nvmrc` and `packageManager`.
 
 ## Develop Taskset With Taskset
 
-The repository dogfoods Taskset. Use the root `taskset.config.ts`, the CLI, and
+The repository dogfoods Taskset. Use the root `.taskset/` data, optional `taskset.config.ts`, the CLI, and
 canonical `.taskset/tasks/` files to plan and inspect work. When the CLI
 supports the required operation, update the task through the CLI instead of
 editing generated or derived state.

package/docs/maintainers/development/documentation.md

@@ -1,69 +1,52 @@
 ---
 title: Documentation
-description: How user Markdown becomes the Taskset documentation website.
+description: How Markdown becomes the Taskset documentation website for humans, agents, and maintainers.
 ---
 
 # Documentation
 
-The root `docs/` directory is canonical for user-facing guidance and maintainer
-guidance. Top-level pages are for users. Repository maintenance material belongs
-under `docs/maintainers/`.
+The root `docs/` directory is canonical. Split audiences deliberately:
 
-## Recommended Website Stack
+- Humans: top-level usage pages
+- Agents: `docs/agents/`, root `AGENTS.md`, and packaged `skills/`
+- Maintainers: `docs/maintainers/`
 
-Use Next.js App Router, Nextra, `nextra-theme-docs`, and
-`nextra-theme-blog` in `apps/www`.
+Follow the [Vercel writing guidelines](https://github.com/vercel-labs/writing-guidelines) for public prose.
+
+## Recommended website stack
+
+Use Next.js App Router, Nextra, `nextra-theme-docs`, and `nextra-theme-blog` in `apps/www`.
 
 Why:
 
 - `apps/www` owns the public documentation renderer
 - the repository already has a Next.js TypeScript preset
-- Nextra supplies Markdown routing, documentation navigation, blog layout, and
-  search
+- Nextra supplies Markdown routing, documentation navigation, blog layout, and search
 - Markdown remains the source rather than a CMS database
 
-## Content Rules
-
-- Use `.md` unless the page needs an interactive component.
-- Add `title` and `description` frontmatter.
-- Keep conceptual pages separate from current command reference.
-- Mark future behavior as planned.
-- Link to source files with repository-relative paths.
-- Keep generated API reference separate from hand-authored concepts.
-- Keep architecture, ADRs, development workflows, and technology preferences
-  under `docs/maintainers/`, not in top-level usage navigation.
-- Keep chronological release and project posts under `apps/www/posts/`.
-- Require `title`, `description`, and `date` frontmatter for blog posts.
-- Register each post in `apps/www/src/blog/posts.ts` so the static build can
-  enumerate `/posts/[slug]`.
+## Content rules
+
+- Use `.md` unless the page needs an interactive component
+- Add `title`, `description`, and `contentType` frontmatter for usage and agent pages
+- Keep conceptual pages separate from current command reference
+- Mark future behavior as planned
+- Link to source files with repository-relative paths
+- Keep generated API reference separate from hand-authored concepts
+- Keep architecture, ADRs, development workflows, and technology preferences under `docs/maintainers/`
+- Keep agent operating contracts under `docs/agents/`
+- Keep `/llms.txt` in `apps/www/public/llms.txt`, not under `docs/`, so Nextra does not import it as a page module
+- Keep chronological release and project posts under `apps/www/posts/`
+- Require `title`, `description`, and `date` frontmatter for blog posts
+- Register each post in `apps/www/src/blog/posts.ts` so the static build can enumerate `/posts/[slug]`
 
 ## Integration
 
-`apps/www/content` is a repository-relative symlink to `../../docs`. Nextra's
-standard content-directory loader renders that source without copying it or
-maintaining a second source tree. The top-level usage docs route filters
-`docs/maintainers/` out of its primary navigation, and the dedicated
-`/maintainers` route renders the same canonical maintainer Markdown with its own
-page map.
-
-Usage docs, maintainer docs, and blog pages use separate route layouts and
-receive their own MDX component sets. Do not merge docs and blog themes in the
-global `mdx-components.tsx`; their wrapper components own different page
-contracts. Blog Markdown is loaded from `apps/www/posts/` through the app-local
-post registry.
-
-Run the Next.js development and production builds in webpack mode. Turbopack
-does not reliably discover newly added Markdown through the external content
-symlink.
-
-Keep stable public site metadata such as `docsRepositoryBase` in the owning app
-configuration. Do not add a root `.env` for a non-secret constant. Use an
-app-local environment variable and checked-in `.env.example` only when a value
-genuinely differs by deployment.
-
-The website may generate `.next/`, search data, and build output. These are
-derived and ignored. Root `docs/` Markdown remains authoritative for
-documentation, and `apps/www/posts/` Markdown remains authoritative for blog
-posts.
+`apps/www/content` is a repository-relative symlink to `../../docs`. Nextra’s standard content-directory loader renders that source without copying it. The top-level usage docs route filters `docs/maintainers/` out of its primary navigation, and the dedicated `/maintainers` route renders maintainer Markdown with its own page map.
+
+Usage docs, maintainer docs, and blog pages use separate route layouts and receive their own MDX component sets. Do not merge docs and blog themes in the global `mdx-components.tsx`.
+
+Run the Next.js development and production builds in webpack mode. Turbopack does not reliably discover newly added Markdown through the external content symlink.
+
+The website may generate `.next/`, search data, and build output. These are derived and ignored. Root `docs/` Markdown remains authoritative for documentation, and `apps/www/posts/` Markdown remains authoritative for blog posts.
 
 See [ADR 0001](../architecture/decisions/0001-documentation-platform.md).

package/docs/maintainers/index.md

@@ -5,9 +5,7 @@ description: Repository maintenance documentation for Taskset contributors.
 
 # Taskset Maintainer Documentation
 
-This section contains repository maintenance material. It is intentionally
-separate from the primary user guides while remaining available in the same
-Nextra documentation site.
+This section contains repository maintenance material for the Taskset delivery workspace. It stays separate from the primary human and agent guides while remaining available in the same Nextra documentation site.
 
 ## Contents
 

package/docs/maintainers/product/vision.md

@@ -7,9 +7,7 @@ description: Maintainer-facing product direction for Taskset.
 
 ## Origin
 
-Taskset began from a simple need: keep task context offline and inline with the
-code so developers and AI assistants can understand work immediately without
-switching to a disconnected project-management database.
+Taskset began from a need to keep delivery context offline and inline with the code. Tasks alone were not enough. Teams and agents also needed stories, research, decisions, flows, and runbooks that travel with the repository instead of living in a disconnected project-management database.
 
 ## Vision
 
@@ -17,18 +15,15 @@ Taskset aims to become the Git-native operating system for software delivery.
 
 ## Mission
 
-Store planning, execution, and project knowledge as human-readable repository
-files, then provide focused interfaces over that shared task graph.
+Store planning, learning, decisions, operations, and execution as human-readable repository files, then provide focused interfaces over that shared work graph.
 
 ## Product Goals
 
-- Accelerate delivery by reducing context switching.
-- Give developers immediate awareness of related tasks, dependencies, specs,
-  decisions, and releases.
-- Give AI systems direct, structured, reviewable project context.
-- Make monorepos, packages, applications, and code paths first-class.
-- Let managers and stakeholders view repository-backed information without
-  creating another source of truth.
+- Accelerate delivery by reducing context switching
+- Give developers immediate awareness of related tasks, dependencies, specs, decisions, and releases
+- Give AI systems direct, structured, reviewable project context across plans and execution
+- Make monorepos, packages, applications, and code paths first-class
+- Let managers and stakeholders view repository-backed information without creating another source of truth
 
 ## Principles
 
@@ -38,39 +33,36 @@ Core workflows must work from a local repository without a network service.
 
 ### Inline with code
 
-Project context belongs beside the code it affects and travels with the
-repository.
+Project context belongs beside the code it affects and travels with the repository.
 
 ### Human and AI readable
 
-Markdown carries durable prose. Structured frontmatter carries data that tools
-can validate and query.
+Markdown carries durable prose. Structured frontmatter carries data that tools can validate and query.
 
 ### Git native
 
-Commits, branches, pull requests, diffs, and reviews are normal collaboration
-mechanisms.
+Commits, branches, pull requests, diffs, and reviews are normal collaboration mechanisms.
 
 ### One source of truth
 
-Every interface reads and changes the same canonical `.taskset/` files through
-the same domain rules.
+Every interface reads and changes the same canonical `.taskset/` files through the same domain rules.
 
-### Developer first
+### Agent first, human readable
 
-Taskset proves developer workflows before broad enterprise planning features.
+Taskset optimizes distribution, discovery, and docs for agent operators while keeping Markdown reviewable by humans.
 
-## Near-Term Scope
+### Memory and execution together
 
-The MVP should implement:
+Documents preserve product and engineering memory. Tasks carry ownership, status, and delivery. Relationships bind them into one graph.
 
-- repository initialization
-- task creation, listing, display, editing, and removal
-- lifecycle transitions
-- deterministic Markdown parsing and serialization
-- validation and repository diagnostics
-- basic search and filtering
-- dependency integrity
+## Current product surface
 
-TUI, MCP, extension, Kanban, Office, and integrations follow after the file and
-core contracts are reliable.
+The current surface includes:
+
+- repository initialization and optional configuration
+- tasks with lifecycle, dependencies, search, and impact queries
+- stories, flows, decisions, research, and runbooks with the same query and mutation family
+- validation, diagnostics, generated views, snapshots, and sync
+- packaged agent skills and dual-audience documentation
+
+TUI, MCP, extension, Kanban, Office, and integrations build on the same file and core contracts.