--target <DATE-OR-TIMESTAMP> [--file <PATH>] [--project <PROJECT-GUID>] [--json] alterac-ai milestone list [--project <PROJECT-GUID>] [--json] alterac-ai milestone get <MILESTONE-NUMBER> [--project <PROJECT-GUID>] [--json] alterac-ai milestone update <MILESTONE-NUMBER> [MARKDOWN] [--title <TITLE>] [--file <PATH>] [--target <DATE-OR-TIMESTAMP>] [--project <PROJECT-GUID>] [--json] create --file get update --target YYYY-MM-DD Z 2026-12-18T17:00:00-05:00 update get --json list get --project alterac-ai milestone create --title "Public beta" --file milestone-objective.md --target 2026-12-18 alterac-ai milestone list alterac-ai milestone get 12 --json alterac-ai milestone update 12 --target 2026-12-21 alterac-ai task comment <taskNumber> [commentMarkdown] [--file <path>] [--author <agent|person>] [--project <projectId>] taskNumber --file --author agent person --project alterac-ai work-run get <taskWorkRunId> [--json] alterac-ai work-run complete <taskWorkRunId> (--summary <markdown> | --summary-file <path>) (--hand-off <markdown> | --hand-off-file <path>) [--review-url <url>] get --json FreshStart complete taskNumber taskWorkRunId complete --json projectId .alterac-ai/config.yaml --project <projectId>81:Tdc7,Use these names as they appear in the application and CLI. The terms explain product behavior; they do not grant access to resources you cannot open. Term Meaning Organization A shared account space that owns projects and memberships. Project A workspace inside one organization. Tasks, Task Builder Sessions, and task numbers belong to one project. Task One unit of project work with its own content, state, labels, dependencies, size, comments, and execution history. Task number The human-facing sequential number for a task within its project. Use it with the project context. Work run One exact execution of a queued task by a coding agent. It captures immutable task context, a summary, hand-off, and review history. Work-run ID The stable identifier for one exact work run. It is not a task number and must not be reused for a newer execution. Size The optional task sizing value shown in the Tasks Mass/Weight column. It is not a state, priority, or completion percentage. Mass The Coding agent task size: the expected difficulty of reviewing the completed work. Weight The Person task size: the expected difficulty of the work needed to complete the task. Tasks move through the normal task workflow. A task may show a direct blocker or an approval wait that must be resolved before it can proceed. State Meaning Backlog Planned work that is not queued. Queued Work selected for a coding agent and waiting to start. Agent working A coding agent has an active work run. Reviewing Work is ready for human review. Done The task's reviewed work is complete and can satisfy dependencies. Closed Work intentionally made inactive without recording successful completion or delivery. Term Meaning Task Builder The workflow for drafting structured Plans and tasks with a local AI conversation before you publish them. Task Builder Session One project-owned drafting workspace. It owns its draft work and can be selected locally for CLI mutations. Session number The human-facing number for a Task Builder Session within its project. Proposed Plan A session-owned draft Plan with optional Markdown, labels, and zero or more member tasks. Proposed Plan ID The stable identifier for one proposed Plan. Its session-local display position is not its mutation identity. Draft ID The stable identifier for one draft task. Its display position can change when drafts are reordered or removed. Standalone draft task A draft task without proposed Plan membership. It still publishes as part of the complete session. Building The session state before publication. Draft content can be changed through the planning conversation and CLI. Published The session state after its complete reviewed draft set was published. It is an immutable history. Publish The explicit application action that atomically creates the session's complete reviewed Plans and tasks. Term Meaning Coding agent A configured command that can receive a queued task and perform its work in a local terminal. Its availability depends on its project configuration and policy. Listener The local process that checks its initialized project for queued work and launches the selected coding agent after any required local approval. Waiting for input A listener status that means a local command-approval prompt needs a response. The task remains queued until that decision. Use Fix task and review workflows for state, work-run, and review problems; Fix Task Builder workflows for draft and publication problems; and Fix the local listener for coding-agent launch problems.82:T957,Choose your operating system and processor above, then follow the commands for your shell. The page validates both release manifests before showing archive links or installation commands. After the tab's commands finish, open a new terminal and run: The output should match the stable version shown above. Then initialize alterac.ai in a repository . An ordinary command may report that a newer stable CLI is available. The warning names both the installed and available versions and links to Install the CLI . The CLI checks before running the command when its last successful check is at least 15 minutes old. A due check waits at most two seconds for release metadata. If the check fails, the command still runs normally, and the CLI waits at least one minute before retrying. A warning based on a previously verified newer release remains visible during a failed check. To upgrade, rerun the recommended install command . The CLI does not update itself. A separate warning about outdated repository guidance means you should also run ; replacing the executable and refreshing repository guidance are separate steps. The initial macOS and Windows binaries are unsigned. Verify the SHA-256 value before extracting the archive, and follow only the narrow operating-system confirmation steps below. Do not disable Gatekeeper, SmartScreen, or another system-wide security control. On macOS, the first launch may say Apple cannot verify the developer. After verifying the checksum, try the command once, open System Settings , select Privacy & Security , and use Open Anyway for if your organization's policy allows it. Confirm Open when macOS asks. This approves that executable; it does not require disabling Gatekeeper globally. On Windows, SmartScreen may show Windows protected your PC . After verifying the checksum, select More info , review that the app is , and select Run anyway if your organization's policy allows it. Do not disable SmartScreen. A managed device may intentionally prevent either exception; contact your organization instead of bypassing that policy. If downloads are unavailable, check your connection and select Retry manifest loading . Do not construct a download URL yourself. If a new terminal cannot find , see Fix repository setup . If a version warning persists after replacement, open a new terminal and confirm that reports the stable version shown above.37:["$","$L44",null,{"searchIndex":[{"url":"/docs","title":"Start with alterac.ai","searchDescription":"Choose a practical starting point for setting up and using alterac.ai.","sectionLabel":"Start here","headings":["Choose your starting point"],"headingIds":["choose-your-starting-point"],"prose":"alterac.ai helps you turn planned work into reviewed changes with your local coding agent. Follow one focused path to work you can review. If you are new to alterac.ai, complete your first task . It starts with a prerequisite checklist, then guides you through creating, queueing, reviewing, and finishing one small change. If you already want to prepare related work with a local AI conversation, plan work with Task Builder . For a high-level explanation of how alterac.ai fits around local coding agents and human review, read Understand the task workflow and Configure a coding agent .","code":""},{"url":"/docs/start/complete-your-first-task","title":"Complete your first task","searchDescription":"Set up alterac.ai locally in an existing Git project, run one small task, review the result, and mark it done.","sectionLabel":"Start here","headings":["Check the prerequisites","Set up alterac.ai locally","Configure an enabled coding agent","Leave the listener running","Create one small real task","Queue the task","Review the result and mark it done","Next steps"],"headingIds":["check-the-prerequisites","set-up-alteracai-locally","configure-an-enabled-coding-agent","leave-the-listener-running","create-one-small-real-task","queue-the-task","review-the-result-and-mark-it-done","next-steps"],"prose":"$45","code":"alterac-ai init alterac.ai is ready for use. Start listening for tasks by running alterac-ai listen. .alterac-ai alterac-ai init alterac-ai listen alterac-ai init ## Goal ## Acceptance criteria 3 3"},{"url":"/docs/cli/overview","title":"Use the alterac.ai CLI","searchDescription":"Understand when people and coding agents use the CLI, and how it resolves repository state.","sectionLabel":"Use the CLI","headings":["Check scheduling command availability","Choose the usual operator","Learn the workflow","Find exact syntax"],"headingIds":["check-scheduling-command-availability","choose-the-usual-operator","learn-the-workflow","find-exact-syntax"],"prose":"$46","code":"alterac-ai --version --help milestone set-sprint set-milestone docs-update"},{"url":"/docs/cli/install","title":"Install the CLI","searchDescription":"Install or upgrade the alterac.ai CLI with one command on macOS, Linux, WSL, or Windows.","sectionLabel":"Use the CLI","headings":["Confirm it works","Install a specific version","Upgrade the CLI","What the installer changes","Configure the installer","Skip PATH changes","Choose the installation directory","macOS, Linux, and WSL","Windows PowerShell","Add PATH manually when opting out","Supported systems","Unsigned-binary warnings","Uninstall","If something goes wrong"],"headingIds":["confirm-it-works","install-a-specific-version","upgrade-the-cli","what-the-installer-changes","configure-the-installer","skip-path-changes","choose-the-installation-directory","macos-linux-and-wsl","windows-powershell","add-path-manually-when-opting-out","supported-systems","unsigned-binary-warnings","uninstall","if-something-goes-wrong"],"prose":"$47","code":"$48"},{"url":"/docs/cli/repository-setup","title":"Initialize and refresh repository guidance","searchDescription":"Connect a Git repository to an accessible alterac.ai project and refresh its local guidance.","sectionLabel":"Use the CLI","headings":["Initialize the repository","Refresh local guidance","Recover from setup problems"],"headingIds":["initialize-the-repository","refresh-local-guidance","recover-from-setup-problems"],"prose":"$49","code":"alterac-ai init .alterac-ai/config.yaml task-work-run-id=[GUID] .alterac-ai/process.md alterac-ai docs-update docs-update --force  init docs-update init init"},{"url":"/docs/cli/login-and-logout","title":"Log in and out from the CLI","searchDescription":"Store interactive CLI authentication, recover from rejected credentials, and clear local sign-in state.","sectionLabel":"Use the CLI","headings":["Sign in","Recover from authentication errors","Sign out"],"headingIds":["sign-in","recover-from-authentication-errors","sign-out"],"prose":"$4a","code":"alterac-ai login init alterac-ai login alterac-ai logout"},{"url":"/docs/cli/listen","title":"Listen for queued work","searchDescription":"Run the local listener that receives queued tasks and starts the configured coding-agent command.","sectionLabel":"Use the CLI","headings":["Start the listener","Choose a trust mode","Adjust polling carefully"],"headingIds":["start-the-listener","choose-a-trust-mode","adjust-polling-carefully"],"prose":"$4b","code":"alterac-ai listen {alterac-ai-message} Ctrl+C alterac-ai config trust {alterac-ai-message} --poll-interval-seconds"},{"url":"/docs/cli/task-work-runs","title":"Use task and work-run commands","searchDescription":"Discover project labels, record durable task comments, and retrieve or complete exact work runs.","sectionLabel":"Use the CLI","headings":["Create one immediate task","Inspect tasks before making direct changes","Read a project task before changing it","Discover available labels","Record a durable task decision","Retrieve and complete a work run"],"headingIds":["create-one-immediate-task","inspect-tasks-before-making-direct-changes","read-a-project-task-before-changing-it","discover-available-labels","record-a-durable-task-decision","retrieve-and-complete-a-work-run"],"prose":"$4c","code":"alterac-ai task create \"Add concise task details.\" --title \"Improve task creation\" --mass --weight --exclude-from-metrics --label --dependency --plan --sprint --milestone --assignee --type --type person task list task update alterac-ai task list alterac-ai task list --plan 12 alterac-ai task list --sprint 7 alterac-ai task list --milestone 12 alterac-ai task list --json --plan <planNumber> --sprint <sprintNumber> --milestone <milestoneNumber> --project <projectId> --json alterac-ai task get <taskNumber> taskNumber --project <projectId> --json alterac-ai labels --json --project <projectId> alterac-ai task comment <taskNumber> \"Decision text\" alterac-ai work-run get <taskWorkRunId> alterac-ai work-run complete work-run get work-run complete type compatibleStates executionOrigin excludeFromMetrics plan task create --type person"},{"url":"/docs/cli/output-and-identifiers","title":"Read CLI output and identifiers","searchDescription":"Choose Markdown or JSON output and keep project, task, Sprint, Milestone, work-run, session, and draft identifiers distinct.","sectionLabel":"Use the CLI","headings":["Keep identifiers distinct","Use file input for Markdown"],"headingIds":["keep-identifiers-distinct","use-file-input-for-markdown"],"prose":"$4d","code":"--json projectId --project taskNumber task get task update task delete task comment sprintNumber --sprint set-sprint --sprint milestoneNumber milestone get milestone update --milestone set-milestone --milestone taskWorkRunId work-run get work-run complete sessionNumber --session draftPlanId draftId milestone list list get"},{"url":"/docs/cli/tasks","title":"Task and work-run commands","searchDescription":"Create and update published tasks, assign a Sprint or Milestone, and inspect current planning membership.","sectionLabel":"Use the CLI","headings":["Create one immediate task","List published tasks","Show authoritative task details","Delete one published task","Update one published task","Assign a Sprint and classify later changes","Assign a Milestone and classify later changes","Retrieve work-run context","Add a task comment","Submit review output","Retrospective Correction compatibility"],"headingIds":["create-one-immediate-task","list-published-tasks","show-authoritative-task-details","delete-one-published-task","update-one-published-task","assign-a-sprint-and-classify-later-changes","assign-a-milestone-and-classify-later-changes","retrieve-work-run-context","add-a-task-comment","submit-review-output","retrospective-correction-compatibility"],"prose":"$4e","code":"$4f"},{"url":"/docs/tasks/overview","title":"Understand the task workflow","searchDescription":"Follow Coding agent or Person work from creation through work, review, completion, or deliberate closure.","sectionLabel":"Work with tasks","headings":["Follow Coding agent task states","Start work on a Person task","Close or reopen superseded work","Know the identifiers","Choose the next action"],"headingIds":["follow-coding-agent-task-states","start-work-on-a-person-task","close-or-reopen-superseded-work","know-the-identifiers","choose-the-next-action"],"prose":"$50","code":"--weight --clear-weight --mass --clear-mass #12"},{"url":"/docs/tasks/plans","title":"View and manage Plans","searchDescription":"Create and edit Plans, manage one task membership at a time, and review count-based progress and archive visibility.","sectionLabel":"Work with tasks","headings":["Create a Plan","Find a Plan","Review Plan details","Edit Plan details","Add, move, or remove one task","Archive or restore a Plan"],"headingIds":["create-a-plan","find-a-plan","review-plan-details","edit-plan-details","add-move-or-remove-one-task","archive-or-restore-a-plan"],"prose":"$51","code":""},{"url":"/docs/tasks/create-and-edit","title":"Create and edit a task","searchDescription":"Add task details and set independent Plan, Sprint, and Milestone membership, Mass or Weight, assignment, labels, and dependencies.","sectionLabel":"Work with tasks","headings":["Create a task","Set useful metadata","Choose a Milestone and classify changes","Choose a Sprint and classify changes","Inspect Sprint and Milestone change history","Estimate work","Edit or delete safely"],"headingIds":["create-a-task","set-useful-metadata","choose-a-milestone-and-classify-changes","choose-a-sprint-and-classify-changes","inspect-sprint-and-milestone-change-history","estimate-work","edit-or-delete-safely"],"prose":"$52","code":"alterac-ai task create alterac-ai task create \"Task details\" --title \"Short title\" --type person --type person alterac-ai task update <taskNumber> --title \"Replacement title\" --file --mass --weight --label --dependency --plan --sprint --milestone --assignee --clear-mass --clear-weight --clear-labels --clear-dependencies --clear-plan --clear-sprint --clear-milestone --clear-assignee size --mass --clear-mass --weight --clear-weight alterac-ai task delete <taskNumber> --yes"},{"url":"/docs/tasks/organize","title":"Organize tasks","searchDescription":"Search task numbers, titles, and descriptions, combine filters, and save or share a project task view.","sectionLabel":"Work with tasks","headings":["Find the work you need","Share or return to a task view","Find current and previous Sprint work","Understand Plan and dependency filters","Use metadata consistently"],"headingIds":["find-the-work-you-need","share-or-return-to-a-task-view","find-current-and-previous-sprint-work","understand-plan-and-dependency-filters","use-metadata-consistently"],"prose":"$53","code":"#246 timeout #246 # q closed=1 state=Closed"},{"url":"/docs/tasks/queue","title":"Queue a task","searchDescription":"Choose a coding agent, queue a task, and understand listener approval and active-work status.","sectionLabel":"Work with tasks","headings":["Queue the work","What happens next"],"headingIds":["queue-the-work","what-happens-next"],"prose":"$54","code":""},{"url":"/docs/tasks/comments","title":"Comment on a task","searchDescription":"Add general task context, manage comments you own, and distinguish task comments from review feedback.","sectionLabel":"Work with tasks","headings":["Add and manage a general comment","Use the right kind of comment"],"headingIds":["add-and-manage-a-general-comment","use-the-right-kind-of-comment"],"prose":"$55","code":""},{"url":"/docs/tasks/review","title":"Review and recover task work","searchDescription":"Submit Person work for review, use project default review branch guidance, or continue and recover coding-agent work.","sectionLabel":"Work with tasks","headings":["Submit and review Person work","Review completed work","View delivered code changes","Recover incomplete work","Choose the replacement coding agent","Continue"],"headingIds":["submit-and-review-person-work","review-completed-work","view-delivered-code-changes","recover-incomplete-work","choose-the-replacement-coding-agent","continue"],"prose":"$56","code":"main main main main main main main main"},{"url":"/docs/tasks/review-history","title":"Read review history","searchDescription":"Compare current and prior work runs, their review output, comments, attribution, and completion history.","sectionLabel":"Work with tasks","headings":["Inspect a work run","Understand continuation"],"headingIds":["inspect-a-work-run","understand-continuation"],"prose":"$57","code":""},{"url":"/docs/task-builder/overview","title":"Plan work with Task Builder","searchDescription":"Prepare proposed Plans and typed task drafts, edit draft content in the browser, and review the complete set before publication.","sectionLabel":"Plan work with Task Builder","headings":["Choose the right starting point","Keep the conversation and publication separate","Understand a Task Builder Session","Know what proposed Plans and drafts contain","Choose your next step"],"headingIds":["choose-the-right-starting-point","keep-the-conversation-and-publication-separate","understand-a-task-builder-session","know-what-proposed-plans-and-drafts-contain","choose-your-next-step"],"prose":"$58","code":"task list task get task create task update task delete taskNumber planNumber sessionNumber draftPlanId draftId"},{"url":"/docs/task-builder/start","title":"Start a planning session","searchDescription":"Create or select a Building Task Builder Session from a local AI planning conversation.","sectionLabel":"Plan work with Task Builder","headings":["Start with a planning conversation","Continue an existing plan","Check the structured result","Next step"],"headingIds":["start-with-a-planning-conversation","continue-an-existing-plan","check-the-structured-result","next-step"],"prose":"$59","code":""},{"url":"/docs/task-builder/refine","title":"Refine proposed Plans and draft tasks","searchDescription":"Edit Building draft type, content, Plan, labels and dependencies in the browser; refine proposed Plans, order and scheduling through the CLI.","sectionLabel":"Plan work with Task Builder","headings":["Improve the session first","Organize proposed Plans","Shape draft tasks","Edit draft content in the browser","Update draft content through the CLI","Assign a future Sprint","Recover saved Milestone intent","Set dependencies and order","Keep track of identities","Check the plan again"],"headingIds":["improve-the-session-first","organize-proposed-plans","shape-draft-tasks","edit-draft-content-in-the-browser","update-draft-content-through-the-cli","assign-a-future-sprint","recover-saved-milestone-intent","set-dependencies-and-order","keep-track-of-identities","check-the-plan-again"],"prose":"$5a","code":"--mass --weight task-builder task set-metric-exclusion /edit alterac-ai task-builder show <SESSION-NUMBER> updatedAt --expected-updated-at --expected-updated-at <TIMESTAMP> --mass --weight show set-plan set-labels set-dependencies --expected-updated-at show --help --expected-updated-at alterac-ai task-builder task set-sprint <DRAFT-ID> --sprint <SPRINT-NUMBER> --session <SESSION-NUMBER> alterac-ai task-builder task set-sprint <DRAFT-ID> --session <SESSION-NUMBER> alterac-ai task-builder show <SESSION-NUMBER> --json --session alterac-ai task-builder task set-milestone <DRAFT-ID> --milestone <MILESTONE-NUMBER> --session <SESSION-NUMBER> alterac-ai task-builder task set-milestone <DRAFT-ID> --milestone <MILESTONE-NUMBER> --milestone-change scope-change --session <SESSION-NUMBER> alterac-ai task-builder task set-milestone <DRAFT-ID> --session <SESSION-NUMBER> --session set-milestone --milestone-change"},{"url":"/docs/task-builder/review-and-publish","title":"Review and publish a session","searchDescription":"Review and edit Building draft content, review optional estimates and resolve scheduling blockers, and explicitly publish the complete Task Builder Session.","sectionLabel":"Plan work with Task Builder","headings":["Review the Building session","Resolve readiness messages","Resolve saved Milestone intent","Publish the complete set","Continue with normal task management"],"headingIds":["review-the-building-session","resolve-readiness-messages","resolve-saved-milestone-intent","publish-the-complete-set","continue-with-normal-task-management"],"prose":"$5b","code":"Started alterac-ai task-builder task set-sprint <DRAFT-ID> --sprint <SPRINT-NUMBER> --session <SESSION-NUMBER> --sprint task-builder task set-milestone Started --milestone-change scope-change task-builder task set-milestone <DRAFT-ID> --session <SESSION-NUMBER>"},{"url":"/docs/task-builder/archive-and-history","title":"Archive and review sessions","searchDescription":"Find Building and Published Task Builder Sessions, control archive visibility, and review publication history.","sectionLabel":"Plan work with Task Builder","headings":["Find the right session","Archive or restore a session","Understand published history","Find an archived session"],"headingIds":["find-the-right-session","archive-or-restore-a-session","understand-published-history","find-an-archived-session"],"prose":"$5c","code":""},{"url":"/docs/coding-agents/overview","title":"Configure a coding agent","searchDescription":"Bring your own coding agent through a compatible local command, configure its definition, and start listening for queued work.","sectionLabel":"Configure coding agents","headings":["Create your first definition","Make it available","Queue and approve a first run","Use optional code-exploration tools","Next steps"],"headingIds":["create-your-first-definition","make-it-available","queue-and-approve-a-first-run","use-optional-code-exploration-tools","next-steps"],"prose":"$5d","code":"{alterac-ai-message} Codex {alterac-ai-message} alterac-ai listen approve-changed"},{"url":"/docs/coding-agents/scopes","title":"Choose where a coding agent belongs","searchDescription":"Understand personal, organization, and project coding-agent ownership and the entries available when work is queued.","sectionLabel":"Configure coding agents","headings":["Ownership and availability","Enabled, hidden, and deleted are different","Copy a definition safely"],"headingIds":["ownership-and-availability","enabled-hidden-and-deleted-are-different","copy-a-definition-safely"],"prose":"$5e","code":""},{"url":"/docs/coding-agents/defaults-and-inheritance","title":"Set defaults and inheritance","searchDescription":"Set coding-agent defaults, understand organization policy, and predict the command selected for a project.","sectionLabel":"Configure coding agents","headings":["Set a default","Understand the selection order","Set organization policy","Check the effective choice"],"headingIds":["set-a-default","understand-the-selection-order","set-organization-policy","check-the-effective-choice"],"prose":"$5f","code":""},{"url":"/docs/coding-agents/worktrees","title":"Prepare repositories for task worktrees","searchDescription":"Understand how alterac.ai uses linked Git worktrees and what to check before concurrent task work.","sectionLabel":"Configure coding agents","headings":["Know what a new worktree contains","Use the repository's normal setup","Make hooks location-aware","Isolate parallel resources","Keep alterac.ai commands in the retained checkout","Clean up after review"],"headingIds":["know-what-a-new-worktree-contains","use-the-repositorys-normal-setup","make-hooks-location-aware","isolate-parallel-resources","keep-alteracai-commands-in-the-retained-checkout","clean-up-after-review"],"prose":"$60","code":".env pnpm install repository_root=\"$(git rev-parse --show-toplevel)\" \"$repository_root/scripts/check-before-commit.sh\" workspace_id=\"$(git branch --show-current | tr '/.' '-')\" ./scripts/start-local.sh --name \"$workspace_id\" --allocate-port .alterac-ai alterac-ai work-run complete 00000000-0000-0000-0000-000000000000 \\ --summary-file /path/to/repository/worktrees/301-example/summary.md \\ --hand-off-file /path/to/repository/worktrees/301-example/hand-off.md"},{"url":"/docs/coding-agents/codegraph","title":"Use CodeGraph with a coding agent","searchDescription":"Use optional CodeGraph alongside alterac.ai with agent access and a separate index for each task worktree.","sectionLabel":"Configure coding agents","headings":["Make it available in task worktrees","Add a short repository instruction"],"headingIds":["make-it-available-in-task-worktrees","add-a-short-repository-instruction"],"prose":"$61","code":"codegraph status --json projectPath codegraph_explore projectPath --path .codegraph/ ## CodeGraph Use CodeGraph only when already available; do not install it for a task. Initialize its index in the assigned task worktree and verify projectPath. If that worktree has no .codegraph directory, initialize it before exploration. For MCP, pass that absolute worktree root as projectPath to codegraph_explore. Keep repository exclusions and generated graph data ignored. Set CODEGRAPH_TELEMETRY=0 and DO_NOT_TRACK=1 for CLI and MCP processes. Run codegraph sync after edits before relying on results. If unavailable or unhelpful, use source search and direct reads. Follow the alterac.ai process and required repository validation throughout."},{"url":"/docs/coding-agents/command-templates","title":"Write a coding-agent command","searchDescription":"Write and validate a coding-agent command that receives alterac.ai routing and exact work-run context instructions.","sectionLabel":"Configure coding agents","headings":["Multi-line commands","Required placeholder and quoting","Fields and validation","Add queue-time option selectors","What is snapshotted"],"headingIds":["multi-line-commands","required-placeholder-and-quoting","fields-and-validation","add-queue-time-option-selectors","what-is-snapshotted"],"prose":"$62","code":"{alterac-ai-message} \\ coding-agent \\ --option value \\ \"{alterac-ai-message}\" coding-agent --option value \"...\" C:\\tools\\codex.exe \\\" ^ .alterac-ai/process.md task-work-run-id=[00000000-0000-0000-0000-000000000000] alterac-ai work-run get 00000000-0000-0000-0000-000000000000 {alterac-ai-message} {Alterac-ai-message} {Label:first option|second option} careful --mode coding-agent --mode {Mode:careful|quick} \"{alterac-ai-message}\" {Sandbox:|--sandbox workspace-write}"},{"url":"/docs/coding-agents/example-commands","title":"Example coding-agent commands","searchDescription":"Get started with copyable Claude Code, Codex, and Cursor CLI templates, tested CLI versions, and unverified variants.","sectionLabel":"Configure coding agents","headings":["Claude Code","Codex","Cursor CLI","Unverified Claude model and effort selectors"],"headingIds":["claude-code","codex","cursor-cli","unverified-claude-model-and-effort-selectors"],"prose":"$63","code":"claude --model {Model:opus|sonnet|haiku} --effort {Effort:high|medium|low|max} --permission-mode acceptEdits --verbose --output-format stream-json \"{alterac-ai-message}\" 2.1.280 fable codex --model {Model:gpt-6.1-sol|gpt-6-astra} --sandbox workspace-write --ask-for-approval on-request -c 'approvals_reviewer=\"auto_review\"' -c 'sandbox_workspace_write.network_access=true' -c 'model_reasoning_effort=\"{Effort:xhigh|high|medium|low|max}\"' -c 'model_reasoning_summary=\"concise\"' -c 'show_raw_agent_reasoning=false' -c 'model_verbosity=\"low\"' --search \"{alterac-ai-message}\" 0.159.2 agent --model auto \"{alterac-ai-message}\" 2026.10.01-e373342 agent --model claude-{Model:opus|sonnet}-5-5-{Effort:medium|high|low|xhigh|max} \"{alterac-ai-message}\" sonnet high claude-sonnet-5-5-high"},{"url":"/docs/coding-agents/trust","title":"Choose a command trust mode","searchDescription":"Choose how the local listener asks for approval before it runs a queued coding-agent command.","sectionLabel":"Configure coding agents","headings":["Trust modes","What counts as changed","Waiting for input"],"headingIds":["trust-modes","what-counts-as-changed","waiting-for-input"],"prose":"$64","code":"alterac-ai config trust approve-changed approve-changed always-allow approve-every-run always-allow always-allow approve-changed {alterac-ai-message}"},{"url":"/docs/coding-agents/listener","title":"Run the local task listener","searchDescription":"Start a local listener for queued work, approve commands safely, and understand terminal launches and queue snapshots.","sectionLabel":"Configure coding agents","headings":["Start listening","Understand launches and output","Why a task can remain queued","Recover safely"],"headingIds":["start-listening","understand-launches-and-output","why-a-task-can-remain-queued","recover-safely"],"prose":"$65","code":".alterac-ai alterac-ai listen Ctrl+C {alterac-ai-message} .alterac-ai/process.md {alterac-ai-message} alterac-ai config trust alterac-ai listen"},{"url":"/docs/projects/organizations-and-projects","title":"Create organizations and projects","searchDescription":"Start free with one person per organization and all features, then create the projects that hold your tasks and coding agents.","sectionLabel":"Manage your team and projects","headings":["Create an organization","Create a project","Understand ownership and access","Choose the organization time zone","Continue with local alterac.ai setup"],"headingIds":["create-an-organization","create-a-project","understand-ownership-and-access","choose-the-organization-time-zone","continue-with-local-alteracai-setup"],"prose":"$66","code":""},{"url":"/docs/projects/metrics","title":"Use project Metrics","searchDescription":"Choose a date range and understand what the project Metrics page shows when delivery data is or is not available.","sectionLabel":"Manage your team and projects","headings":["Choose a date range","Read completed-task throughput","Read accepted without follow-up","Read AI work time per completed task","Read human review time during working hours"],"headingIds":["choose-a-date-range","read-completed-task-throughput","read-accepted-without-follow-up","read-ai-work-time-per-completed-task","read-human-review-time-during-working-hours"],"prose":"$67","code":"N/A N/A N/A N/A N/A"},{"url":"/docs/projects/sprints","title":"Prepare and manage Sprints","searchDescription":"Prepare Sprints, inspect daily work and progress, complete or safely reopen existing Sprints, and correct retained history.","sectionLabel":"Manage your team and projects","headings":["Before you begin","Browse and prepare Sprints","Understand Sprint lifecycle availability","Read the Sprint Horizon","Read Sprint progress","Use the Sprint Team Pulse","Manage tasks on a Sprint page","Complete a Sprint and correct its history","Disabled Sprints","Reset a task view","Complete and start the following Sprint"],"headingIds":["before-you-begin","browse-and-prepare-sprints","understand-sprint-lifecycle-availability","read-the-sprint-horizon","read-sprint-progress","use-the-sprint-team-pulse","manage-tasks-on-a-sprint-page","complete-a-sprint-and-correct-its-history","disabled-sprints","reset-a-task-view","complete-and-start-the-following-sprint"],"prose":"$68","code":""},{"url":"/docs/projects/milestones","title":"Create and manage Milestones","searchDescription":"Manage Milestone tasks, complete and safely reopen outcomes, and correct retained history.","sectionLabel":"Manage your team and projects","headings":["Before you begin","Find an outcome","Read the Milestone Horizon","Read Milestone progress","Inspect task states and membership","Manage tasks on a Milestone page","Create or edit a Milestone","Start or complete a Milestone","Correct retained history","Safely reopen a Milestone","Delete a Planned record","Assign tasks with the CLI","Disabled Milestones","Reset a task view"],"headingIds":["before-you-begin","find-an-outcome","read-the-milestone-horizon","read-milestone-progress","inspect-task-states-and-membership","manage-tasks-on-a-milestone-page","create-or-edit-a-milestone","start-or-complete-a-milestone","correct-retained-history","safely-reopen-a-milestone","delete-a-planned-record","assign-tasks-with-the-cli","disabled-milestones","reset-a-task-view"],"prose":"$69","code":"task create --milestone <milestoneNumber> task update <taskNumber> --milestone <milestoneNumber> --clear-milestone task list --milestone <milestoneNumber> --milestone-change correction --milestone-change scope-change"},{"url":"/docs/projects/members-and-roles","title":"Manage members and roles","searchDescription":"Inspect license capacity, add members, and choose the access each person needs.","sectionLabel":"Manage your team and projects","headings":["Before you begin","Inspect license capacity","Add an organization member","Add a member to a project","Change a role or remove someone","Choose the right role"],"headingIds":["before-you-begin","inspect-license-capacity","add-an-organization-member","add-a-member-to-a-project","change-a-role-or-remove-someone","choose-the-right-role"],"prose":"$6a","code":""},{"url":"/docs/projects/labels","title":"Manage labels","searchDescription":"Create shared organization labels and project-specific labels that keep tasks, plans, and drafts organized.","sectionLabel":"Manage your team and projects","headings":["Before you begin","Start with default labels","Create a label","Choose an owner for the label","Use scoped labels","Keep shared definitions clear"],"headingIds":["before-you-begin","start-with-default-labels","create-a-label","choose-an-owner-for-the-label","use-scoped-labels","keep-shared-definitions-clear"],"prose":"$6b","code":"#175CD3 priority::high priority::high :: priority::high :: priority::high priority::low priority::low priority::high ::"},{"url":"/docs/projects/settings","title":"Change or delete an organization or project","searchDescription":"Change workspace details, configure independent Sprint and Milestone settings and review branch guidance, or delete a project or organization.","sectionLabel":"Manage your team and projects","headings":["Before you begin","Update details","Configure review branch guidance","Configure Sprints and Milestones","Browse and prepare Sprints","Read the Sprint Horizon","Read Sprint progress","Use the Sprint Team Pulse","Manage tasks on a Sprint page","Complete a Sprint and correct its history","Change automatic project access","Set the organization time zone","Configure working hours","Delete an organization or project","Set coding-agent policy separately"],"headingIds":["before-you-begin","update-details","configure-review-branch-guidance","configure-sprints-and-milestones","browse-and-prepare-sprints","read-the-sprint-horizon","read-sprint-progress","use-the-sprint-team-pulse","manage-tasks-on-a-sprint-page","complete-a-sprint-and-correct-its-history","change-automatic-project-access","set-the-organization-time-zone","configure-working-hours","delete-an-organization-or-project","set-coding-agent-policy-separately"],"prose":"$6c","code":"America/New_York"},{"url":"/docs/account/create-account","title":"Create an account","searchDescription":"Sign up, confirm your email, protect your account with an authenticator, and finish your profile.","sectionLabel":"Manage your account and security","headings":["Before you start","Create and confirm your account","Public page measurement","Set up an authenticator","Save recovery codes safely","What happens next"],"headingIds":["before-you-start","create-and-confirm-your-account","public-page-measurement","set-up-an-authenticator","save-recovery-codes-safely","what-happens-next"],"prose":"$6d","code":""},{"url":"/docs/account/log-in","title":"Log in","searchDescription":"Sign in with your password and authenticator, use a recovery code, and sign out safely.","sectionLabel":"Manage your account and security","headings":["Log in with an authenticator","Use a recovery code instead","Sign out","If you cannot log in"],"headingIds":["log-in-with-an-authenticator","use-a-recovery-code-instead","sign-out","if-you-cannot-log-in"],"prose":"$6e","code":""},{"url":"/docs/account/reset-password","title":"Reset a password","searchDescription":"Request a password-reset email, set a new password, and recover when a reset link does not work.","sectionLabel":"Manage your account and security","headings":["Request a reset link","If the email or link does not work"],"headingIds":["request-a-reset-link","if-the-email-or-link-does-not-work"],"prose":"$6f","code":""},{"url":"/docs/account/profile-and-layout","title":"Update your profile","searchDescription":"Complete your required display name and manage the profile details shown in your account settings.","sectionLabel":"Manage your account and security","headings":["Complete your profile","Manage account details"],"headingIds":["complete-your-profile","manage-account-details"],"prose":"Finish your profile after first-time authenticator setup so alterac.ai can show your required display name. Later, open account settings to review and update your current profile details. After saving recovery codes, enter your display name on Finish your profile . You can add a profile picture if you want. Select Save profile . The display name is required before you can enter the app. If you leave the flow before finishing it, log in again and complete the displayed profile step. Open Account settings from the app to update your profile and review security settings. In the left sidebar of an organization or project, the muted Version value above Collapse sidebar shows the exact running product version to share during support and deployment verification. If the version is unavailable, wait and try again later rather than reporting a guessed release. Keep your account email current so you can receive confirmation and password-reset emails. Use Change your email for that separate security-sensitive action.","code":""},{"url":"/docs/account/change-email","title":"Change your email","searchDescription":"Update the email used for your account and confirm the new address before it takes effect.","sectionLabel":"Manage your account and security","headings":["Change the address"],"headingIds":["change-the-address"],"prose":"Change your account email from Account settings when you need to use a different inbox for sign-in and account recovery. Open Account settings in the app. In the email section, enter the new email address and complete the requested confirmation. Open the confirmation email sent to the new address and use its link. The new address takes effect only after confirmation. Keep access to your current inbox until you finish, because alterac.ai sends a security notice when an email change is requested and again when it completes. If alterac.ai cannot send the confirmation email, your current address stays active. Keep the new address in the form and select Send confirmation again to request a fresh email. If you no longer control either inbox, do not repeatedly submit change requests. Restore access to your current account email first, or use the recovery path in Fix account access .","code":""},{"url":"/docs/account/change-password","title":"Change your password","searchDescription":"Change your signed-in account password after confirming your current password and second factor.","sectionLabel":"Manage your account and security","headings":["Change your password securely"],"headingIds":["change-your-password-securely"],"prose":"Change your password from Account settings when you can already sign in and want a new password. Open Account settings and select Change password . Confirm your current password and either the current code from your authenticator app or one recovery code. Enter and confirm the new password. Select Change password . Use at least 8 characters with uppercase, lowercase, a digit, and a symbol. The second confirmation protects this sensitive change if someone has access to an unlocked browser session. After a successful change, the browser session where you changed the password stays signed in. Other browser sessions and CLI credentials must sign in again with the new password and your second factor. Changing your password does not replace your recovery codes. If you used one as the second factor, it no longer works; check the remaining-code count and generate new recovery codes when needed.","code":""},{"url":"/docs/account/two-factor","title":"Manage an authenticator","searchDescription":"Set up or replace the authenticator app that protects your alterac.ai sign-in.","sectionLabel":"Manage your account and security","headings":["Set up your first authenticator","Replace an authenticator app","Recover when no authenticator or recovery code remains"],"headingIds":["set-up-your-first-authenticator","replace-an-authenticator-app","recover-when-no-authenticator-or-recovery-code-remains"],"prose":"$70","code":""},{"url":"/docs/account/recovery-codes","title":"Use recovery codes","searchDescription":"Store, use, and replace one-time recovery codes for safe backup account access.","sectionLabel":"Manage your account and security","headings":["Store codes when they are shown","Use a code to sign in","Generate new codes"],"headingIds":["store-codes-when-they-are-shown","use-a-code-to-sign-in","generate-new-codes"],"prose":"$71","code":""},{"url":"/docs/troubleshooting/account-access","title":"Fix account access","searchDescription":"Recover from confirmation, password, authenticator, recovery-code, and profile-completion, and legal-agreement access problems.","sectionLabel":"Solve a problem","headings":["You cannot confirm your email","You cannot sign in with your password","Your authenticator code is rejected","You signed in but must complete your profile","Agree to the Privacy Policy and Terms of Use","Next step"],"headingIds":["you-cannot-confirm-your-email","you-cannot-sign-in-with-your-password","your-authenticator-code-is-rejected","you-signed-in-but-must-complete-your-profile","agree-to-the-privacy-policy-and-terms-of-use","next-step"],"prose":"$72","code":""},{"url":"/docs/troubleshooting/cli-authentication","title":"Fix CLI login","searchDescription":"Recover when alterac.ai CLI login fails, credentials expire, or two-factor challenges, or current legal agreement is required.","sectionLabel":"Solve a problem","headings":["The CLI says you need to sign in","Stored credentials are rejected or have expired","A command still targets the wrong environment or account","Current legal agreement is required","Next step"],"headingIds":["the-cli-says-you-need-to-sign-in","stored-credentials-are-rejected-or-have-expired","a-command-still-targets-the-wrong-environment-or-account","current-legal-agreement-is-required","next-step"],"prose":"$73","code":"alterac-ai alterac-ai login alterac-ai login alterac-ai logout alterac-ai login alterac-ai login 403 Forbidden code: \"LegalAgreementRequired\" requiredDocuments agreementUrl: \"/account/legal-agreement\" GET /legal/privacy-policy GET /legal/terms-of-use POST /account/legal-agreement agreeToPrivacyPolicy agreeToTermsOfUse true privacyPolicyVersion termsOfUseVersion privacyPolicyIntegrityIdentifier termsOfUseIntegrityIdentifier integrityIdentifier hasAcceptedCurrentDocuments: true GET /account/legal-agreement 400 legalAgreement LegalAgreementRequired"},{"url":"/docs/troubleshooting/repository-setup","title":"Fix repository setup","searchDescription":"Recover an uninitialized, missing, invalid, stale, or wrongly selected alterac.ai repository configuration.","sectionLabel":"Solve a problem","headings":["The repository is not initialized","The selected project is wrong or no longer available","Managed files are missing or stale","A task worktree is missing dependencies or local configuration","The CLI itself is unavailable","Command not found after install","Install script errors","A newer CLI version is available","Next step"],"headingIds":["the-repository-is-not-initialized","the-selected-project-is-wrong-or-no-longer-available","managed-files-are-missing-or-stale","a-task-worktree-is-missing-dependencies-or-local-configuration","the-cli-itself-is-unavailable","command-not-found-after-install","install-script-errors","a-newer-cli-version-is-available","next-step"],"prose":"$74","code":".alterac-ai alterac-ai init .alterac-ai .alterac-ai alterac-ai init alterac-ai docs-update alterac-ai init .env alterac-ai --version alterac-ai init ~/.zshrc ~/.bash_profile ~/.bashrc ALTERAC_AI_NO_MODIFY_PATH=1 alterac-ai alterac-ai.exe sudo sudo alterac-ai --version"},{"url":"/docs/troubleshooting/listener","title":"Fix the local listener","searchDescription":"Diagnose unavailable coding agents, local approval waits, terminal launch fallback, duplicate listeners, and queued work.","sectionLabel":"Solve a problem","headings":["There is no available coding agent","The listener is not running","The listener is waiting for approval","A worker terminal did not open","The coding agent is waiting for permission or input","The task remains queued or an old listener is still shown","The organization license expired","Next step"],"headingIds":["there-is-no-available-coding-agent","the-listener-is-not-running","the-listener-is-waiting-for-approval","a-worker-terminal-did-not-open","the-coding-agent-is-waiting-for-permission-or-input","the-task-remains-queued-or-an-old-listener-is-still-shown","the-organization-license-expired","next-step"],"prose":"$75","code":"alterac-ai listen Active Active always-allow Ctrl+C Ctrl+C"},{"url":"/docs/troubleshooting/tasks-and-review","title":"Fix task and review workflows","searchDescription":"Recover when a task is unavailable, cannot be queued, has an unexpected state, or review and follow-up actions are unavailable.","sectionLabel":"Solve a problem","headings":["A task cannot be found or opened","Queue is unavailable or work does not start","A task stays Agent working after agent work stops","The work run is superseded or completion is rejected","Review actions are unavailable","Next step"],"headingIds":["a-task-cannot-be-found-or-opened","queue-is-unavailable-or-work-does-not-start","a-task-stays-agent-working-after-agent-work-stops","the-work-run-is-superseded-or-completion-is-rejected","review-actions-are-unavailable","next-step"],"prose":"$76","code":""},{"url":"/docs/troubleshooting/task-builder","title":"Fix Task Builder workflows","searchDescription":"Recover stale browser and CLI draft saves, optional estimates, scheduling intent, readiness, archive visibility, and Task Builder publication.","sectionLabel":"Solve a problem","headings":["The active session is missing or stale","The session is Published and cannot be edited","A browser save conflicts with a newer draft","A version-checked CLI update conflicts","Readiness shows errors or warnings","A dependency cycle or unavailable label blocks the session","Saved Sprint membership blocks publication","Saved Milestone intent blocks publication","A proposed Plan or draft ID is rejected","Publication did not complete or archived work is not visible","Next step"],"headingIds":["the-active-session-is-missing-or-stale","the-session-is-published-and-cannot-be-edited","a-browser-save-conflicts-with-a-newer-draft","a-version-checked-cli-update-conflicts","readiness-shows-errors-or-warnings","a-dependency-cycle-or-unavailable-label-blocks-the-session","saved-sprint-membership-blocks-publication","saved-milestone-intent-blocks-publication","a-proposed-plan-or-draft-id-is-rejected","publication-did-not-complete-or-archived-work-is-not-visible","next-step"],"prose":"$77","code":"alterac-ai task-builder show <SESSION-NUMBER> --expected-updated-at updatedAt set-plan set-labels set-dependencies show --expected-updated-at set-sprint set-milestone task-builder task set-milestone --milestone-change correction --milestone-change scope-change Started draftPlanId draftId"},{"url":"/docs/releases/v1.7.0","title":"Release notes for v1.7.0","searchDescription":"Edit Task Builder drafts in the browser, protect reviewed CLI changes, and get clearer organization and project setup guidance.","sectionLabel":"Release notes","headings":["Highlights","What changed","Important information"],"headingIds":["highlights","what-changed","important-information"],"prose":"$78","code":"--expected-updated-at --expected-updated-at"},{"url":"/docs/releases/v1.6.1","title":"Release notes for v1.6.1","searchDescription":"Fixes task creation with No Sprint selected, including in projects with no Sprints.","sectionLabel":"Release notes","headings":["Highlights","What changed"],"headingIds":["highlights","what-changed"],"prose":"Create your first task in a project without preparing a Sprint first. Fixed an error that blocked creating Coding-agent and Person tasks with No Sprint selected. Creation also works after selecting a Sprint and then clearing it. See Create and edit a task .","code":""},{"url":"/docs/releases/v1.6.0","title":"Release notes for v1.6.0","searchDescription":"New features, improvements, and fixes in alterac.ai v1.6.0.","sectionLabel":"Release notes","headings":["Highlights","What changed","Important information"],"headingIds":["highlights","what-changed","important-information"],"prose":"$79","code":""},{"url":"/docs/releases/v1.5.0","title":"Release notes for v1.5.0","searchDescription":"Plan queueing, Coding-agent review follow-ups, and other improvements in alterac.ai v1.5.0.","sectionLabel":"Release notes","headings":["Highlights","What changed"],"headingIds":["highlights","what-changed"],"prose":"$7a","code":""},{"url":"/docs/releases/v1.4.0","title":"Release notes for v1.4.0","searchDescription":"One-command CLI installs, timely update warnings, and first-pass task acceptance reporting in alterac.ai v1.4.0.","sectionLabel":"Release notes","headings":["Highlights","What changed","Important information"],"headingIds":["highlights","what-changed","important-information"],"prose":"$7b","code":""},{"url":"/docs/releases/v1.3.0","title":"Release notes for v1.3.0","searchDescription":"New features, improvements, and fixes in alterac.ai v1.3.0.","sectionLabel":"Release notes","headings":["Highlights","What changed","Person tasks: track human work next to agent work","Mass and Weight: size work the way it is done","Close tasks you no longer plan to finish","Plan mixed teams in Task Builder","A clearer start for every coding agent","More improvements and fixes","Important information"],"headingIds":["highlights","what-changed","person-tasks-track-human-work-next-to-agent-work","mass-and-weight-size-work-the-way-it-is-done","close-tasks-you-no-longer-plan-to-finish","plan-mixed-teams-in-task-builder","a-clearer-start-for-every-coding-agent","more-improvements-and-fixes","important-information"],"prose":"$7c","code":"--weight {alterac-ai-message} {task-work-run-id}"},{"url":"/docs/releases/v1.2.0","title":"Release notes for v1.2.0","searchDescription":"New features, improvements, and fixes in alterac.ai v1.2.0.","sectionLabel":"Release notes","headings":["Highlights","What changed","Important information"],"headingIds":["highlights","what-changed","important-information"],"prose":"$7d","code":""},{"url":"/docs/releases/v1.1.0","title":"Release notes for v1.1.0","searchDescription":"New features, improvements, and fixes in alterac.ai v1.1.0.","sectionLabel":"Release notes","headings":["Highlights","What changed","Important information"],"headingIds":["highlights","what-changed","important-information"],"prose":"$7e","code":""},{"url":"/docs/reference/cli-commands","title":"CLI command reference","searchDescription":"Find exact production alterac.ai command syntax, inputs, validation, output, and local state effects.","sectionLabel":"Reference","headings":["Command discovery","Repository setup and local state","Authentication","Listener and trust configuration","Label discovery","Create a task","Task discovery","Task details","Delete a published task","Update a task","Task Builder draft content","Task Builder draft labels, dependencies, and Plan membership","Task Builder future Sprint membership","Task Builder Milestone membership","Sprint membership and estimate changes","Milestone membership and estimate changes","Milestone records","Task comments","Work runs","Text, files, JSON, and project resolution","Retrospective Correction compatibility"],"headingIds":["command-discovery","repository-setup-and-local-state","authentication","listener-and-trust-configuration","label-discovery","create-a-task","task-discovery","task-details","delete-a-published-task","update-a-task","task-builder-draft-content","task-builder-draft-labels-dependencies-and-plan-membership","task-builder-future-sprint-membership","task-builder-milestone-membership","sprint-membership-and-estimate-changes","milestone-membership-and-estimate-changes","milestone-records","task-comments","work-runs","text-files-json-and-project-resolution","retrospective-correction-compatibility"],"prose":"$7f","code":"$80"},{"url":"/docs/reference/terminology","title":"alterac.ai terminology","searchDescription":"Look up the shared names for organizations, projects, tasks, work runs, Task Builder sessions, identifiers, states, task size, coding agents, and listeners.","sectionLabel":"Reference","headings":["Workspace and task terms","Task states","Task Builder terms","Coding-agent terms","Related recovery"],"headingIds":["workspace-and-task-terms","task-states","task-builder-terms","coding-agent-terms","related-recovery"],"prose":"$81","code":"alterac-ai listen"},{"url":"/docs/reference/manual-cli-install","title":"Download the CLI manually","searchDescription":"Download a verified stable alterac.ai CLI archive and set up a user-owned installation when you cannot run the install script.","sectionLabel":"Reference","headings":["3. Confirm it works","When the CLI reports a newer version","Important: unsigned-binary warnings","If something goes wrong"],"headingIds":["3-confirm-it-works","when-the-cli-reports-a-newer-version","important-unsigned-binary-warnings","if-something-goes-wrong"],"prose":"$82","code":"alterac-ai --version alterac-ai docs-update alterac-ai alterac-ai.exe alterac-ai alterac-ai --version"}],"children":"$L83"}] </article></body></html>

78:T69f,Refine Task Builder drafts directly in the browser before publishing. New accounts also get clearer guidance from creating or joining an organization to completing a first task. Edit Building drafts in the browser. Change task type, title, Markdown, optional Mass or Weight, same-session Plan membership and dependencies, and project labels. Unsaved changes are protected by discard prompts and version checks; CLI replacements can also check the reviewed version with . See Refine proposed Plans and draft tasks . Find your first organization and task. Empty organization and project views explain how to create an organization or get access to an existing team. Projects without tasks link to the first-task guide . Get clearer coding-agent guidance. The coding-agent overview explains the requirements for bringing your own agent through a compatible local command. The named agents are examples, with their documented verification limits. Contact sales from pricing. Sales email addresses now open your email application when selected. Find the founder podcast conversation. Home features an AI Operators Podcast appearance, and the self case study links to the relevant chapter. Browser editing applies to Building drafts. Published snapshots remain read-only. Draft creation, proposed Plan definitions, ordering, metric exclusion, and Sprint/Milestone assignments continue through the CLI. Older CLI versions still work, but replacements without a reviewed version can overwrite newer changes. Check command help for and install an available release if your executable lacks the option. After a conflict, read the latest draft, review and merge your changes, then retry with its timestamp.79:T873,Plan a period of work with Sprints or group tasks around an outcome with Milestones. New scheduling controls, task-list options, and consistent planning pages make it easier to organize work and see what needs attention. Our existing free tier is easier to find: Free for one person, with as many projects as you want. All features included. No credit card required. Prepare Sprints with a planned start and end. Follow another Sprint or choose your own start, then calculate the end from your project's Sprint duration or set it yourself. Start and complete Sprints when you are ready. Create Milestones to organize tasks around an objective and target date. Use them alongside Sprints or on their own, with several Milestones underway at once. Sprint Team Pulse shows work by person, including unassigned tasks. Select a person or task-state count to inspect the matching tasks, then clear the selection to return to the full view. Resize task-table columns with your mouse or keyboard to give the information you need more room. Your browser remembers the widths, and you can restore the defaults. Planning dates and scheduling dialogs now use the time zone in Organization Settings, beside working hours. Existing scheduled times stay at the same moment when you change the zone. Sprint and Milestone pages share layouts, clearer action buttons, and compact planning links. Smaller improvements include simpler history entries, clearer chart tooltips, and easier filter resets. Assign Sprint and Milestone targets independently from the CLI and Task Builder, and create or edit Milestone details from the CLI. See the CLI command reference . Projects can save default guidance for checking a task branch against main. You can still edit that guidance for each follow-up. Fixes keep the sidebar steady when moving between planning pages, preserve schedules when saving unrelated edits, allow deletion of unused Planned Milestones, and improve account-setup recovery. Updated guides explain organization setup, joining an existing team, and completing your first task . New commands require a compatible CLI version. Update your installed CLI before using them.7a:T427,Queue Coding-agent tasks directly from a Plan and request follow-up work to check and update a review branch. Task details and CLI guidance also make it easier to follow work through to completion. On a Coding-agent task in review, you can ask for follow-up work to check and update its linked review branch. This option is also available from More actions before you have written a review comment. Queue a Backlog Coding-agent task directly from its Plan, choosing a coding agent and handling any incomplete dependencies. Done Coding-agent task details link to the latest recorded code review when one is available. Task dependency previews stay open while you move between a task card and its preview. The CLI installation guide now explains how to choose an installation directory or manage PATH yourself. Example coding-agent commands show tested starting points for Codex and Claude Code. The Privacy Policy and Terms of Use are available on the site; signup requires agreement to both, and existing users are prompted to accept current versions when needed.7b:T57c,You can now install or upgrade the alterac.ai CLI with one command. Project Metrics also shows how often completed tasks were accepted without a follow-up round. Install or upgrade the CLI with a macOS, Linux, WSL, PowerShell, or Command Prompt command. The installer verifies the selected download, installs it in your user folder, and can install an exact published version. The install guide explains PATH setup, and manual downloads remain available. When a newer CLI release is available, the first eligible command can show the installed and available versions with a link to the update steps before it runs. The command still runs normally; the CLI does not update itself. Outdated repository guidance has its own separate warning. Project Metrics now includes Accepted without follow-up , with an accepted-task percentage, known-review-history count, unknown-history count, and trend. It covers both Coding-agent and Person tasks and is a delivery observation, not an AI performance score. The project-home Working summary and Tasks list have less explanatory text, leaving more room for the current work. The macOS and Windows CLI binaries remain unsigned. Linux installs require glibc; musl systems such as Alpine are unsupported. Windows Arm64 uses the Windows x64 CLI through emulation in a 64-bit PowerShell process. See the installation guide for the supported systems and security prompts.7c:Tb71,Person tasks now track human work beside coding-agent work in the same projects, Plans and review flow. v1.3.0 introduces Person tasks, so the work people do themselves sits right beside the work your coding agents deliver, in the same projects, Plans, and review flow. It also adds a Closed state for work you decide not to finish, and gives coding agents a clearer start on every task. Not every task belongs to a coding agent. Now you can create a Person task for work a teammate does themselves, like a manual check, a design decision, or writing a migration plan. Choose Coding agent or Person when you create a task. Select Start work to take a Person task and track it In progress . Submit your work for review with a summary, then accept it, send it back for more work, or complete it directly. See Person tasks alongside agent work in project home, Tasks, Plans, and metrics. The Working count covers both people in progress and agents at work. Follow one history for each task that shows every attempt, whether a person or a coding agent did the work. Person tasks use Weight to describe the expected difficulty of the work itself. Coding agent tasks keep Mass , the expected difficulty of reviewing what the agent produced. The Tasks list shows both in one Mass/Weight column, and the CLI accepts for Person tasks. Priorities change. Close a task to take it out of your way without deleting its history, and reopen it any time. Closed tasks leave the normal task view, so your list stays focused on active work. Turn on Show closed when you want to see them again. Closed tasks do not count against your completion metrics or Plan progress. When Task Builder breaks down a larger piece of work, choose whether each draft is a Coding agent or Person task. Each draft shows its task-type icon, so you can review who does what before you publish. Coding agents now receive a short alterac.ai launch message when they start a task. It points them straight to your repository's alterac.ai process and their exact work run, so they begin in the right place every time. Write multi-line coding-agent commands using backslash line continuations. Leave review comments of any length. Reopen a task with one click; it saves immediately. See human review time as N/A when working hours are not configured, and a friendlier empty state on a new project's metrics. Fixed duplicate Plan labels in Task Builder review. Fixed review history for tasks whose coding-agent work started before this release. Update each coding-agent command to use in place of . A command that still uses the old placeholder cannot queue new work, and work queued before this release needs to be requeued after you update the command. See Write a coding-agent command . Install the latest CLI with this release. Older CLI versions can clear a task's Mass or Weight when they update the task. Learn more in Understand the task workflow and Organize tasks .7d:T661,v1.2.0 makes it easier to find, filter, share, and review project work. It also adds a guided account-recovery path and gives new users a clearer journey from installing the CLI to completing their first task. Search project tasks by task number, title, or readable description text, then combine the search with task, Plan, label, and dependency filters. Share or revisit a task-list view through its address, including its search, filters, sorting, page, and page size. Filter by more than one Plan choice at a time and see active filters in a clearer task-discovery layout. Review Task Builder output with proposed Plans that are more clearly separated and can be collapsed. Ask a platform administrator to start authenticator recovery when you lose both your authenticator and recovery codes. The time-limited recovery flow keeps passwords, setup keys, and recovery tokens private. Find installation and first-task guidance earlier in Docs, with a clearer starting page, screenshots, command examples, and improved in-page highlighting. Read simpler product, use-case, case-study, and pricing pages centered on coordinating coding agents while people retain the final decision. Navigate the application and Docs more consistently, with clearer selected states, improved typography, complete table borders, and more direct task actions. Authenticator recovery requires a platform administrator to initiate it. If you can still sign in with a recovery code, use the normal authenticator replacement flow instead. Start with Start with alterac.ai , then follow Complete your first task for the full setup, dispatch, and review path.7e:T6e2,v1.1.0 is the initial stable release of alterac.ai. It provides one coordination loop for planning repository-based software work, dispatching tasks to configured local coding agents, preserving each work run's context, and keeping acceptance or follow-up decisions with people. Create organizations and projects, manage member roles and licensed capacity, configure coding agents, and organize work with tasks, labels, dependencies, Plans, and Mass. Turn a planning conversation into draft Plans and tasks with Task Builder, review the proposed set, and choose when it becomes published project work. Run configured coding-agent commands in your own local checkout through the alterac.ai CLI and listener, with repository-local approval controls for new or changed commands. Follow each task from Backlog through agent work and review. Every work run keeps its exact context, summary, hand-off, review comments, and history so you can accept the result, request follow-up work, start fresh, or recover an incomplete run. Use Project Metrics to observe completed-task throughput and per-task AI-work and working-hours review distributions with visible sample sizes and exclusions. Learn and evaluate the workflow through public product, use-case, case-study, pricing, and Docs pages. The app sidebar identifies the running version so you can find the matching release notes. Bring an existing Git repository, a configured local coding agent, and a person ready to review the result. alterac.ai coordinates the work and preserves the context; it still leaves the code-writing to your agent and the final judgment to a human. The robots have plenty to do already. Start with Complete your first task for the shortest path through setup, local dispatch, and review.7f:T74d3,This reference covers the production commands people use to set up a repository, manage authentication and trust, and run local work. Local coding agents also use CLI commands when their repository guidance directs them; their command contracts remain in that guidance. Use built-in help rather than guessing syntax. prints the exact embedded product release version and does not read repository state or contact the API. The CLI installation guide provides one-line installation, version selection, rerun upgrades, and uninstall steps, while the CLI overview explains how the commands fit together. Scheduling examples require an executable whose help lists the relevant , task membership/filter/classification, or Task Builder scheduling command. If your installed help lacks one, follow Check scheduling command availability before using the example. Refreshing generated guidance does not upgrade the executable. After an ordinary command is parsed successfully, including and , the CLI checks whether a newer stable version is available before running the command. Successful checks are reused for 15 minutes; a due check waits at most two seconds for release metadata. Failed checks retry no sooner than one minute later and do not change the command's exit result. A previously verified newer version continues to produce a warning if a later check fails. The warning names the installed and available versions and links to the CLI installation guide ; it never installs an update. It appears in yellow when the terminal supports color and uses standard error, so standard output remains valid structured data. If generated repository guidance is also outdated, its separate warning follows the CLI warning. and refresh that guidance themselves and skip only its warning. Help, , and invalid command lines do not check for or print this binary-version warning. Authenticated commands keep stored credentials when the API denies access. When an organization's license has expired, the CLI prints the API's stable recovery guidance instead of replacing it with a generic permission message. New product operations remain blocked until reactivation, while an exact work run that already started can still use and to reach review safely. is normally person-operated. It has no required arguments. It authenticates if needed, selects an accessible project, selects coding-agent trust and managed instruction files, refreshes repository-local guidance, and writes . If no accessible project is available, create or join one in alterac.ai and retry. refreshes the repository-local alterac.ai home using the existing managed instruction-file selection. requests a refresh even when the local version looks current. Both commands change repository-local state, not project tasks. See Initialize and refresh repository guidance for the workflow. is normally person-operated and interactive. It reads the local trust mode, asks for a replacement, and saves it to . It controls local coding-agent command-template approval, not project permission. is normally person-operated and interactive. It collects email, password, and required two-factor or recovery-code challenges, then stores CLI authentication for the device. clears that stored authentication and succeeds with a no-op message when none exists. Authenticated commands other than report missing or rejected credentials and direct you to ; they do not begin an unexpected interactive sign-in. Read Log in and out from the CLI for recovery. The person-operated listener reads the configured project, authenticates, registers local presence, polls queued work, captures immutable context, expands the selected command's token into the centrally owned exact-run instruction, and launches the command. A snapshot without the required token fails before launch with requeue guidance. The polling interval defaults to 5 seconds and must be from 1 through 300. stops the listener. When a terminal cannot be launched, it prints the resolved command for manual use. See Listen for queued work . This normally agent-operated command lists project-owned and inherited organization labels. Without , it reads the selected project from ; an explicit accessible project does not change that file. Default output is Markdown with names and stable IDs; JSON also includes scope and ownership details. This command immediately creates one normal Backlog task. It requires a nonblank title and Markdown supplied inline or with , but never both. It does not queue work or create a work run. Use Task Builder when you need to create multiple new tasks or review related work before publishing it. Pass to record that a new task should be excluded from task-derived metrics; omission records it as included. The created task output reports the persisted choice, and task-derived reports apply it retroactively without changing lifecycle or history. sizes a Coding agent task and sizes a Person task; both must be below 100. Use only with (or the default type) and only with ; the mismatched option, or both options together, fails before any request. Repeat to assign exact available labels and to set direct project task dependencies. accepts an active project-scoped Plan number. and accept available same-project Planned or Current records while their respective features are enabled; Current assignment requires its own or . See Sprint membership and estimate changes and Milestone membership and estimate changes . accepts an exact eligible member email, display name, or stable user ID. Permissions, labels, dependencies, Plan, Sprint, and Milestone membership, and assignee eligibility are validated before mutation. Task creation and its Sprint/Milestone assignments save together after target, lifecycle, authority, and classification preflight. The default output is the created task, including its persisted type and ordered compatible states, shown as Weight for a Person task and Mass for a Coding agent task; uses for both types. Omit or use for a Coding agent task; use for a Person task. The chosen type cannot be changed after creation. If separately stored labels or assignee metadata cannot be applied after creation, the error names the created task and the exact metadata operation to review and retry. This normally agent-operated command lists tasks in ascending task-number order. It reads the selected project from unless supplies another accessible project, without changing local selection. Use , , or with a positive project-scoped number to list current members; combined filters require every selected membership. An unavailable target returns an error, while an available target with no current tasks returns a successful empty list. Each scheduling filter requires its own feature to be enabled and does not list historical Complete membership. Markdown shows each task's number, title, persisted type, current state, ordered compatible states, Weight or Mass (by type), metric exclusion, labels, Plan, current Sprint and Milestone, dependency status, assignee, and update time. returns the same authoritative task records, with the sizing value as for both types, for scripting. Current Sprint and Milestone metadata include identity and lifecycle; Sprint detail also includes planned dates and opening or closing facts. A disabled feature hides its scheduling details independently. Markdown lifecycle labels are Planned, Current, and Complete; JSON preserves the API states Planned, Started, and Complete. Legacy records and omitted creation types retain Coding agent compatibility. The command is read-only. This normally agent-operated command reads complete authoritative task content and metadata without changing task state. is a positive, project-scoped number; it is not the task's GUID or an exact . The project comes from local config unless supplies another accessible project. Default Markdown includes the task and project IDs, title, Markdown, persisted type, current state, ordered compatible states, Weight or Mass (by type), metric exclusion, labels, dependencies, blocking tasks, Plan, current Sprint and Milestone identity and lifecycle facts when enabled, assignee, timestamps, completion facts, and active-work-run context. returns the equivalent structured response, with the sizing value as for both types. It does not retrieve comments or review history. Use it before a direct task update or deletion. This destructive command retrieves one authoritative published task before deleting it. Interactive use displays the exact task number and title, then asks for default-negative confirmation. Declining or providing no affirmation leaves the task unchanged and reports that it was not deleted. Use as the explicit affirmative option for an asynchronous coding agent or another non-interactive invocation. It skips only the prompt: the CLI still retrieves the task and the API still owns authentication, access, deletion eligibility, relationships, dependencies, work runs, comments, reviews, and provenance. Success appears only after API confirmation. A task that disappears after retrieval reports not-found instead of success, while server rejection and API failures return distinct errors. Deletion is immediate and has no soft-delete or restore path. This removes a published project task; it does not affect unpublished Task Builder drafts. This command immediately updates one published task. It requires a positive project-scoped task number and at least one explicit replacement or clear. Omitted fields preserve current values. , inline Markdown, and replace required content and cannot clear it. Use inline Markdown or , never both. Each metadata field follows the same preserve, replace, and clear convention. Omit it to preserve it. Pass , , repeated , repeated , , , , or to replace that complete field. Pass the corresponding , , , , , , , or option to clear it. Do not combine replacement and clear options for the same field. Sprint or Milestone replacement changes only that feature’s membership; Plan and other metadata remain independent. / apply only to a Coding agent task and / only to a Person task; the command validates the supplied option against the task's retrieved type before any write and fails with a task-specific message when it does not match, or when both a mass option and a weight option are supplied together. Pass or to replace the persisted task-level metric eligibility choice. Omit both to preserve it, and never pass both together. Task-derived reports apply the choice retroactively. The command uses the task version it just retrieved and rejects a stale concurrent change instead of overwriting it. Labels must be exact available labels and enforce scoped exclusivity. Dependencies use task numbers and enforce availability, self-dependency, duplicate, and cycle rules. Plans use one active same-project Plan number. Assignees use an exact eligible member email, display name, or stable user ID. The API remains authoritative for project access and metadata validation. Default output is the complete authoritative persisted task, including its type and ordered compatible states; returns the same task data as JSON. When coordinated metadata endpoints partially fail, the command exits nonzero, names completed and failed operations, and returns authoritative recovery state when it can retrieve it. Review that state and retry only the remaining field. Workflow state and task type are not generic task metadata. This command preserves both, along with comments, reviews, work runs, completion facts, and Task Builder provenance. It does not queue work, transition review state, edit a Plan, add comments, or complete a work run; use the workflow-specific task, review, and actions for those lifecycle changes. Person lifecycle transitions are available in the application; the CLI has no Person start, submission, or review-resolution commands. Read and review the draft before preparing an update. For stale-write protection, pass that draft's exact as the optional ; human output also prints a copyable option. Use the draft timestamp, rather than the session timestamp. The command requires a complete title and Markdown, supplied inline or through . It preserves the current task type, Plan membership, labels, and dependencies. Coding agent drafts accept ; Person drafts accept . Omitting the matching sizing option clears the saved value. The Building browser editor can change draft type and same-session relationships; this CLI content command has no type-conversion option. Without a version, the previous last-write-wins behavior is preserved and can overwrite newer saved content. With a version, if the draft changes after your read, the update is rejected without overwriting the newer content. Run , review the current draft, merge your intended changes, then retry with its newly reviewed . The command never replaces your token with its internal session read or automatically retries a stale replacement. Published sessions remain read-only. Archiving only changes visibility; an archived Building session remains editable. Older CLIs remain supported without this option. To use version-checked updates, check that lists ; install an available release if needed. Refreshing generated guidance does not upgrade the executable. See Edit draft content for browser and AI collaboration. Each command replaces its complete relationship field on one Building draft. accepts available project or inherited organization label IDs or exact names; accepts other draft IDs from the same session; accepts a proposed Plan ID from that same session. Omit the relationship options to clear labels or dependencies, or return the draft to Standalone. The optional also protects clearing. Before preparing any replacement, run and review the draft's current type, content, size, Plan membership, labels, and dependencies. For stale-write protection, pass that draft's exact earlier reviewed as optional , rather than the session timestamp. Internal lookups preserve the supplied token. Unversioned replacements retain the previous last-write-wins behavior and can overwrite newer selections; supplied stale versions reject the replacement without changing newer browser or CLI selections. After a conflict, run again, review and merge the intended changes, and retry explicitly with the newly reviewed draft version. Do not automatically refresh the token and resend an old replacement. Older CLIs remain supported for these commands. To use version-checked replacements, check each command’s help for and install an available release if needed. Updating repository guidance alone does not upgrade the executable. See Refine draft content and relationships for collaboration and recovery. This normally agent-operated command assigns or replaces a Building draft's future Sprint membership. Omit to clear it. is stable; must be a positive number within the configured project, available from its Sprints page. Omit to use the active Building session or select one explicitly without changing local selection. Plan membership and dependencies are independent, and both fixed draft task types are supported. Targets must be Planned with Sprints enabled. Disabled configuration returns Project Settings recovery; missing, inaccessible, or cross-project targets return access/identity guidance. Current or Complete targets (Started or Complete in JSON output) must be replaced with a future Planned Sprint or cleared before publication. A failed replacement preserves the saved assignment. Clearing does not require an enabled or available target. Default output and detailed session reads show Sprint number, title, current state, and stable ID. exposes the saved and nullable object with , , , and ; unavailable details retain the saved ID. The command reads current session state after mutation, and later server readiness and publication responses remain authoritative if eligibility changes. This command creates no Sprints, changes no lifecycle, and does not publish the session. See Refine proposed Plans and draft tasks and Review and publish a session . This normally agent-operated command assigns or replaces one Building draft's Milestone target. Omit and to clear both the target and saved intent. Use the stable draft ID and a positive Milestone number from this project's Milestones page. Omit to use the active Building session, or select another explicitly without changing local selection. Coding agent and Person drafts are supported; Sprint and Plan membership remain independent. An enabled same-project Planned target requires no intent and rejects . A Started target (Current in scheduling rules) requires explicit or . Scope change records newly added work. Correction requires Team Lead authority and counts the published task in the opening plan, even when publication happens later. Its actual creation and completion times stay unchanged. Choose Scope change when the work should enter scope at publication time. The server remains authoritative for permission, readiness, and publication checks. Complete, missing, inaccessible, or cross-project targets are invalid. Failed assignment or replacement preserves the previous target and intent. If the target becomes Complete or unavailable, select another eligible target or clear both fields. If a Planned target becomes Started, explicitly save Current intent before publishing. Assignment and replacement fail when Milestones are disabled with Project Settings guidance; clearing stale draft intent remains available to an authorized session editor, including when the target is unavailable. Clearing a draft never changes live Milestone membership. Human output and detailed session reads report target number, title, lifecycle (Planned, Current, or Complete; Current is in JSON), stable ID, and saved intent. retains , ( , , or null), and nullable context ( , , , , ). Unavailable target details preserve the saved ID and intent. Output refreshes session facts after a successful mutation; readiness and publication recheck them. This command does not publish, change a Milestone lifecycle, or delete a Milestone. See Recover saved Milestone intent and Resolve saved Milestone intent . Sprint numbers are positive and scoped to the selected project. Assignment accepts Planned or Current Sprints; Complete Sprints cannot receive current members. Closing a Sprint clears its current membership, retaining history. The CLI exposes current membership, not historical correction controls or Sprint entity creation, opening, closing, or deletion commands. Planned membership needs no classification. For a membership change involving a Current Sprint or an actual estimate change affecting Current planning history, supply or . One choice covers the whole Sprint change across the affected source and destination histories and any simultaneous Mass or Weight change. A Correction repairs the opening membership and Size plan and requires effective Team Lead authority; it may include a later-created task without changing its actual creation, state, or completion times. A Scope change records a later scope decision and is available to effective project members. Setting a missing estimate or clearing an estimate counts as a change. The classification option requires a membership or estimate mutation and does not perform a standalone change. Requested targets and classifications are validated before any write. Task creation with Sprint assignment, and task updates to content, dependencies, Sprint membership, and affected estimate history, save atomically. Invalid or stale Sprint changes leave that operation unchanged. Plan, labels, assignee, and metric eligibility may use separate writes; review recovered authoritative task output if a later write fails. An actual estimate edit affecting Current Milestone history additionally requires or , with the same Correction and Scope change permissions. Supply independent choices when both Sprint and Milestone history are affected; Correction in one and Scope change in the other is valid. All affected histories are validated and saved atomically. Setting a missing estimate or clearing one counts as a change. Milestones must be enabled to submit their classification; if disabled, re-enable them before the edit. When Sprints are disabled, assignment, replacement, clearing, filtering, and standalone classification are rejected with Project Settings guidance. Ordinary task edits remain available. An actual estimate edit affecting retained Current Sprint history still requires the same explicit classification and authority, with neutral planning-history guidance that does not disclose the disabled Sprint's details. If that edit also affects a disabled Milestone, its classification is blocked and the whole edit waits for Milestone re-enablement. Task Builder supports independent future Planned Sprint membership and Planned or Started Milestone membership . Use on task creation or update to assign one available same-project Milestone. On update, omission preserves membership and clears it; replacement and clear are mutually exclusive. Plan, Sprint, and Milestone membership remain independent. Use for current members, optionally combined with and ; every selected membership must match. An available target with no current members succeeds with an empty list. Planned membership needs no classification. A membership change involving a Started Milestone, or an actual Mass or Weight edit affecting its history, requires or . One choice covers the whole Milestone change across affected source/destination records and the simultaneous estimate edit. Scope change records a later scope decision and is available to project members. Correction repairs the opening plan and requires Team Lead authority. It may include a newly created task; its actual creation, state, and completion dates remain unchanged. Scope change instead adds work from the time of the change. A classification alone is not a task or history mutation. The command preflights feature settings, project/lifecycle eligibility, authority, and intent before task creation. The API revalidates at the atomic write boundary: task content, dependencies, memberships, and every affected Sprint/Milestone history save together. Invalid targets, unavailable history evidence, unauthorized Corrections, and stale versions leave that operation unchanged. Plan, labels, assignee, or metric updates may use separate writes; review returned authoritative task output if a later operation fails. Complete Milestones cannot receive live tasks. Completion clears current membership and retains final history; later live estimate edits do not rewrite that snapshot. Explicit historical repairs belong to the history-correction workflow, rather than assigning a task to a Complete record. Milestone opening, closing, and eligible deletion remain browser operations. When Milestones are disabled, assignment, replacement, clearing, filtering, and fail with Project Settings guidance while records/history remain intact. An estimate edit affecting retained Started Milestone history also requires re-enablement before its explicit classification; rejection leaves the task and all affected histories unchanged. Ask a Team Lead to re-enable Milestones before retrying. Enabled Sprint workflows remain available independently. These commands create, discover, read, and edit project Milestone metadata. requires a nonblank title, a nonblank Markdown objective supplied inline or with , and a target. It creates a Planned Milestone without opening it or assigning tasks. Use inline Markdown or a file, never both. and use a positive project-scoped Milestone number, not a Milestone GUID or task number. accepts as an organization-local calendar date, or an ISO 8601 timestamp with an explicit offset or , such as . A date covers that local day through the next local midnight as an exclusive boundary; the stored target retains its time-zone interpretation. A timestamp without an offset is rejected. first retrieves the current record and requires at least one explicit title, objective, or target replacement. Omitted fields preserve current values. Required fields cannot be cleared or replaced with blank text. The API checks the retrieved record version; if someone changes it before your save, reload with , review their changes, and retry only the intended replacement. Project members can read enabled records, create Milestones, and edit Planned metadata. Editing Started or Complete records requires Team Lead authority or inherited organization Owner/Admin project-management authority; updates preserve lifecycle and history. Default Markdown and output include Milestone and project identity, title, lifecycle, objective, target and time-zone context, and concise eligible task-count progress facts with excluded-member coverage. Complete progress uses the corrected historical final scope and retained task states, together with the current metric-exclusion choice. A retained membership Correction changes these counts without changing live task membership. Later task deletion retains the last recorded metric-exclusion choice, so available history still reports the corrected final scope. If the latest exclusion choice or historical evidence cannot be verified, progress is unavailable. Markdown lifecycle labels are Planned, Current, and Complete; JSON preserves the API states Planned, Started, and Complete. Detail output also includes creation, update, opening, and closing timestamps, with Started and Completed as the opening and closing timestamp labels in Markdown. These are factual records, not forecasts or health judgments. and are read-only, and an explicit never changes local project selection. When Milestones are disabled, reads and mutations return guidance to Project Settings , rather than presenting retained records as an empty project. Re-enabling restores access to retained records and history; members who cannot manage settings should ask a Team Lead. See Configure Sprints and Milestones . Milestone opening, closing, and eligible deletion belong to browser workflows; there are no CLI lifecycle or delete commands. The CLI has no Sprint entity command family. Task membership belongs to task commands, with independent Sprint and Milestone assignment, clearing, filtering, and explicit planning-history classification. Milestone collection, editing, and browser lifecycle actions are available. Browser task scheduling controls and charts remain separate from these pages. For example, create from a local Markdown objective and change only its target: This normally agent-operated command adds one nonblank Markdown comment without changing task state. is a positive project-scoped integer. Provide inline Markdown or , never both. defaults to ; use only to preserve a direct human comment. The project comes from local config unless is supplied. See Use task and work-run commands . These normally agent-operated commands use an exact, non-empty work-run GUID supplied by the listener. They authenticate but do not read project configuration or accept a project override. returns immutable execution context as Markdown by default or JSON with ; it does not fall back to task data. Both forms expose the snapshotted task type and its ordered compatible states, durable execution origin, and nullable Plan context captured when the run started, including Plan identity, content, archive state, timestamps, and labels. Markdown adds a prominent restart instruction for and a separate Plan Snapshot section; JSON returns the equivalent structured values. A task that was standalone at start remains without Plan context even if its live membership changes later. requires nonblank summary and AI hand-off content, with exactly one inline or file form for each. It may include an absolute HTTP or HTTPS review URL no longer than 2,048 characters. It retrieves the same immutable context, submits review output for that exact run, and reports the task state. Only run it after implementation, validation, and delivery are complete. A cannot substitute for a . The summary allows at most 8,192 characters and the AI hand-off at most 16,384. These limits count Unicode code points: supplementary characters count as one, while combining marks count separately. The API rejects oversized text with field-specific validation errors and saves none of the submission. Shorten the indicated text or file and retry with the same work-run GUID; the active run remains available. Content is never silently truncated. Use an inline value or a file for Markdown input, not both. Required task/Milestone/comment/work-run files must contain nonblank text; proposed Plan Markdown is optional and an omitted or empty value stores empty Markdown. Use files for multiline or shell-sensitive content and remove temporary files after use. Default output is Markdown or concise status text; use only on commands that list it. A nonzero exit means the command did not fully succeed. Some coordinated metadata operations may already have persisted; inspect the reported task and recovery state, then retry only the failed operation. Project-scoped commands, including task and Milestone commands, read from unless they offer and receive . The local config may also store trust, managed instruction-file selection, and an active Task Builder session. Use CLI commands, not hand edits, to change it. Retrospective Correction during direct CLI task creation requires a CLI build containing this change. An older installed CLI may reject that choice before contacting the API. Updating only the API/frontend does not update your local CLI. Until a compatible CLI is installed, create the task without that Current target and use the browser to add it as a Correction. Task Builder saved Milestone intent is validated by the deployed API at publication.80:T178f,alterac-ai alterac-ai --help alterac-ai --version alterac-ai --help alterac-ai --help alterac-ai --version milestone init docs-update --json init docs-update --version work-run get work-run complete alterac-ai init .alterac-ai/config.yaml alterac-ai docs-update [--force] --force alterac-ai config trust .alterac-ai/config.yaml alterac-ai login alterac-ai logout init login alterac-ai listen [--poll-interval-seconds ] {alterac-ai-message} Ctrl+C alterac-ai labels [--project ] [--json] --project .alterac-ai/config.yaml alterac-ai task create [taskMarkdown] --title [--file ] [--type ] [--mass ] [--weight ] [--exclude-from-metrics] [--label ]... [--dependency ]... [--plan ] [--sprint ] [--sprint-change ] [--milestone ] [--milestone-change ] [--assignee ] [--project ] [--json] --file --exclude-from-metrics --mass --weight --mass --type coding-agent --weight --type person --label --dependency --plan --sprint --milestone --sprint-change --milestone-change --assignee --json mass --type --type coding-agent --type person alterac-ai task list [--project ] [--plan ] [--sprint ] [--milestone ] [--json] .alterac-ai/config.yaml --project --plan --sprint --milestone --json mass alterac-ai task get [--project ] [--json] taskNumber taskWorkRunId --project --json mass alterac-ai task delete [--project ] [--yes] --yes alterac-ai task update [taskMarkdown] [--title ] [--file ] [--mass | --clear-mass] [--weight | --clear-weight] [--exclude-from-metrics | --include-in-metrics] [--label ]... [--clear-labels] [--dependency ]... [--clear-dependencies] [--plan | --clear-plan] [--sprint | --clear-sprint] [--sprint-change ] [--milestone | --clear-milestone] [--milestone-change ] [--assignee | --clear-assignee] [--project ] [--json] --title --file --file --mass --weight --label --dependency --plan --sprint --milestone --assignee --clear-mass --clear-weight --clear-labels --clear-dependencies --clear-plan --clear-sprint --clear-milestone --clear-assignee --mass --clear-mass --weight --clear-weight --exclude-from-metrics --include-in-metrics --json work-run alterac-ai task-builder show [--json] alterac-ai task-builder task update [MARKDOWN] --title [--expected-updated-at ] [--file ] [--mass | --weight ] [--session ] updatedAt --expected-updated-at show --file --mass --weight alterac-ai task-builder show updatedAt task-builder task update --help --expected-updated-at alterac-ai task-builder show [--json] alterac-ai task-builder task set-labels [--expected-updated-at ] [--label ]... [--session ] [--json] alterac-ai task-builder task set-dependencies [--expected-updated-at ] [--dependency ]... [--session ] [--json] alterac-ai task-builder task set-plan [--expected-updated-at ] [--plan ] [--session ] [--json] set-labels set-dependencies set-plan --expected-updated-at show updatedAt --expected-updated-at show --expected-updated-at alterac-ai task-builder task set-sprint [--sprint ] [--session ] [--json] alterac-ai task-builder show [--json] --sprint DRAFT-ID SPRINT-NUMBER --session --json sprintId sprint sprintId number title state alterac-ai task-builder task set-milestone [--milestone ] [--milestone-change ] [--session ] [--json] alterac-ai task-builder show [--json] --milestone --milestone-change --session --milestone-change --milestone-change correction --milestone-change scope-change Started --json milestoneId milestoneChangeKind Correction ScopeChange milestone milestoneId number title state version --sprint-change correction --sprint-change scope-change --milestone-change correction --milestone-change scope-change --milestone --clear-milestone task list --milestone --plan --sprint --milestone-change correction --milestone-change scope-change --milestone-change alterac-ai milestone create [MARKDOWN] --title --target <DATE-OR-TIMESTAMP> [--file <PATH>] [--project <PROJECT-GUID>] [--json] alterac-ai milestone list [--project <PROJECT-GUID>] [--json] alterac-ai milestone get <MILESTONE-NUMBER> [--project <PROJECT-GUID>] [--json] alterac-ai milestone update <MILESTONE-NUMBER> [MARKDOWN] [--title <TITLE>] [--file <PATH>] [--target <DATE-OR-TIMESTAMP>] [--project <PROJECT-GUID>] [--json] create --file get update --target YYYY-MM-DD Z 2026-12-18T17:00:00-05:00 update get --json list get --project alterac-ai milestone create --title "Public beta" --file milestone-objective.md --target 2026-12-18 alterac-ai milestone list alterac-ai milestone get 12 --json alterac-ai milestone update 12 --target 2026-12-21 alterac-ai task comment <taskNumber> [commentMarkdown] [--file <path>] [--author <agent|person>] [--project <projectId>] taskNumber --file --author agent person --project alterac-ai work-run get <taskWorkRunId> [--json] alterac-ai work-run complete <taskWorkRunId> (--summary <markdown> | --summary-file <path>) (--hand-off <markdown> | --hand-off-file <path>) [--review-url <url>] get --json FreshStart complete taskNumber taskWorkRunId complete --json projectId .alterac-ai/config.yaml --project <projectId>81:Tdc7,Use these names as they appear in the application and CLI. The terms explain product behavior; they do not grant access to resources you cannot open. Term Meaning Organization A shared account space that owns projects and memberships. Project A workspace inside one organization. Tasks, Task Builder Sessions, and task numbers belong to one project. Task One unit of project work with its own content, state, labels, dependencies, size, comments, and execution history. Task number The human-facing sequential number for a task within its project. Use it with the project context. Work run One exact execution of a queued task by a coding agent. It captures immutable task context, a summary, hand-off, and review history. Work-run ID The stable identifier for one exact work run. It is not a task number and must not be reused for a newer execution. Size The optional task sizing value shown in the Tasks Mass/Weight column. It is not a state, priority, or completion percentage. Mass The Coding agent task size: the expected difficulty of reviewing the completed work. Weight The Person task size: the expected difficulty of the work needed to complete the task. Tasks move through the normal task workflow. A task may show a direct blocker or an approval wait that must be resolved before it can proceed. State Meaning Backlog Planned work that is not queued. Queued Work selected for a coding agent and waiting to start. Agent working A coding agent has an active work run. Reviewing Work is ready for human review. Done The task's reviewed work is complete and can satisfy dependencies. Closed Work intentionally made inactive without recording successful completion or delivery. Term Meaning Task Builder The workflow for drafting structured Plans and tasks with a local AI conversation before you publish them. Task Builder Session One project-owned drafting workspace. It owns its draft work and can be selected locally for CLI mutations. Session number The human-facing number for a Task Builder Session within its project. Proposed Plan A session-owned draft Plan with optional Markdown, labels, and zero or more member tasks. Proposed Plan ID The stable identifier for one proposed Plan. Its session-local display position is not its mutation identity. Draft ID The stable identifier for one draft task. Its display position can change when drafts are reordered or removed. Standalone draft task A draft task without proposed Plan membership. It still publishes as part of the complete session. Building The session state before publication. Draft content can be changed through the planning conversation and CLI. Published The session state after its complete reviewed draft set was published. It is an immutable history. Publish The explicit application action that atomically creates the session's complete reviewed Plans and tasks. Term Meaning Coding agent A configured command that can receive a queued task and perform its work in a local terminal. Its availability depends on its project configuration and policy. Listener The local process that checks its initialized project for queued work and launches the selected coding agent after any required local approval. Waiting for input A listener status that means a local command-approval prompt needs a response. The task remains queued until that decision. Use Fix task and review workflows for state, work-run, and review problems; Fix Task Builder workflows for draft and publication problems; and Fix the local listener for coding-agent launch problems.82:T957,Choose your operating system and processor above, then follow the commands for your shell. The page validates both release manifests before showing archive links or installation commands. After the tab's commands finish, open a new terminal and run: The output should match the stable version shown above. Then initialize alterac.ai in a repository . An ordinary command may report that a newer stable CLI is available. The warning names both the installed and available versions and links to Install the CLI . The CLI checks before running the command when its last successful check is at least 15 minutes old. A due check waits at most two seconds for release metadata. If the check fails, the command still runs normally, and the CLI waits at least one minute before retrying. A warning based on a previously verified newer release remains visible during a failed check. To upgrade, rerun the recommended install command . The CLI does not update itself. A separate warning about outdated repository guidance means you should also run ; replacing the executable and refreshing repository guidance are separate steps. The initial macOS and Windows binaries are unsigned. Verify the SHA-256 value before extracting the archive, and follow only the narrow operating-system confirmation steps below. Do not disable Gatekeeper, SmartScreen, or another system-wide security control. On macOS, the first launch may say Apple cannot verify the developer. After verifying the checksum, try the command once, open System Settings , select Privacy & Security , and use Open Anyway for if your organization's policy allows it. Confirm Open when macOS asks. This approves that executable; it does not require disabling Gatekeeper globally. On Windows, SmartScreen may show Windows protected your PC . After verifying the checksum, select More info , review that the app is , and select Run anyway if your organization's policy allows it. Do not disable SmartScreen. A managed device may intentionally prevent either exception; contact your organization instead of bypassing that policy. If downloads are unavailable, check your connection and select Retry manifest loading . Do not construct a download URL yourself. If a new terminal cannot find , see Fix repository setup . If a version warning persists after replacement, open a new terminal and confirm that reports the stable version shown above.37:["$","$L44",null,{"searchIndex":[{"url":"/docs","title":"Start with alterac.ai","searchDescription":"Choose a practical starting point for setting up and using alterac.ai.","sectionLabel":"Start here","headings":["Choose your starting point"],"headingIds":["choose-your-starting-point"],"prose":"alterac.ai helps you turn planned work into reviewed changes with your local coding agent. Follow one focused path to work you can review. If you are new to alterac.ai, complete your first task . It starts with a prerequisite checklist, then guides you through creating, queueing, reviewing, and finishing one small change. If you already want to prepare related work with a local AI conversation, plan work with Task Builder . For a high-level explanation of how alterac.ai fits around local coding agents and human review, read Understand the task workflow and Configure a coding agent .","code":""},{"url":"/docs/start/complete-your-first-task","title":"Complete your first task","searchDescription":"Set up alterac.ai locally in an existing Git project, run one small task, review the result, and mark it done.","sectionLabel":"Start here","headings":["Check the prerequisites","Set up alterac.ai locally","Configure an enabled coding agent","Leave the listener running","Create one small real task","Queue the task","Review the result and mark it done","Next steps"],"headingIds":["check-the-prerequisites","set-up-alteracai-locally","configure-an-enabled-coding-agent","leave-the-listener-running","create-one-small-real-task","queue-the-task","review-the-result-and-mark-it-done","next-steps"],"prose":"$45","code":"alterac-ai init alterac.ai is ready for use. Start listening for tasks by running alterac-ai listen. .alterac-ai alterac-ai init alterac-ai listen alterac-ai init ## Goal ## Acceptance criteria 3 3"},{"url":"/docs/cli/overview","title":"Use the alterac.ai CLI","searchDescription":"Understand when people and coding agents use the CLI, and how it resolves repository state.","sectionLabel":"Use the CLI","headings":["Check scheduling command availability","Choose the usual operator","Learn the workflow","Find exact syntax"],"headingIds":["check-scheduling-command-availability","choose-the-usual-operator","learn-the-workflow","find-exact-syntax"],"prose":"$46","code":"alterac-ai --version --help milestone set-sprint set-milestone docs-update"},{"url":"/docs/cli/install","title":"Install the CLI","searchDescription":"Install or upgrade the alterac.ai CLI with one command on macOS, Linux, WSL, or Windows.","sectionLabel":"Use the CLI","headings":["Confirm it works","Install a specific version","Upgrade the CLI","What the installer changes","Configure the installer","Skip PATH changes","Choose the installation directory","macOS, Linux, and WSL","Windows PowerShell","Add PATH manually when opting out","Supported systems","Unsigned-binary warnings","Uninstall","If something goes wrong"],"headingIds":["confirm-it-works","install-a-specific-version","upgrade-the-cli","what-the-installer-changes","configure-the-installer","skip-path-changes","choose-the-installation-directory","macos-linux-and-wsl","windows-powershell","add-path-manually-when-opting-out","supported-systems","unsigned-binary-warnings","uninstall","if-something-goes-wrong"],"prose":"$47","code":"$48"},{"url":"/docs/cli/repository-setup","title":"Initialize and refresh repository guidance","searchDescription":"Connect a Git repository to an accessible alterac.ai project and refresh its local guidance.","sectionLabel":"Use the CLI","headings":["Initialize the repository","Refresh local guidance","Recover from setup problems"],"headingIds":["initialize-the-repository","refresh-local-guidance","recover-from-setup-problems"],"prose":"$49","code":"alterac-ai init .alterac-ai/config.yaml task-work-run-id=[GUID] .alterac-ai/process.md alterac-ai docs-update docs-update --force  init docs-update init init"},{"url":"/docs/cli/login-and-logout","title":"Log in and out from the CLI","searchDescription":"Store interactive CLI authentication, recover from rejected credentials, and clear local sign-in state.","sectionLabel":"Use the CLI","headings":["Sign in","Recover from authentication errors","Sign out"],"headingIds":["sign-in","recover-from-authentication-errors","sign-out"],"prose":"$4a","code":"alterac-ai login init alterac-ai login alterac-ai logout"},{"url":"/docs/cli/listen","title":"Listen for queued work","searchDescription":"Run the local listener that receives queued tasks and starts the configured coding-agent command.","sectionLabel":"Use the CLI","headings":["Start the listener","Choose a trust mode","Adjust polling carefully"],"headingIds":["start-the-listener","choose-a-trust-mode","adjust-polling-carefully"],"prose":"$4b","code":"alterac-ai listen {alterac-ai-message} Ctrl+C alterac-ai config trust {alterac-ai-message} --poll-interval-seconds"},{"url":"/docs/cli/task-work-runs","title":"Use task and work-run commands","searchDescription":"Discover project labels, record durable task comments, and retrieve or complete exact work runs.","sectionLabel":"Use the CLI","headings":["Create one immediate task","Inspect tasks before making direct changes","Read a project task before changing it","Discover available labels","Record a durable task decision","Retrieve and complete a work run"],"headingIds":["create-one-immediate-task","inspect-tasks-before-making-direct-changes","read-a-project-task-before-changing-it","discover-available-labels","record-a-durable-task-decision","retrieve-and-complete-a-work-run"],"prose":"$4c","code":"alterac-ai task create \"Add concise task details.\" --title \"Improve task creation\" --mass --weight --exclude-from-metrics --label --dependency --plan --sprint --milestone --assignee --type --type person task list task update alterac-ai task list alterac-ai task list --plan 12 alterac-ai task list --sprint 7 alterac-ai task list --milestone 12 alterac-ai task list --json --plan <planNumber> --sprint <sprintNumber> --milestone <milestoneNumber> --project <projectId> --json alterac-ai task get <taskNumber> taskNumber --project <projectId> --json alterac-ai labels --json --project <projectId> alterac-ai task comment <taskNumber> \"Decision text\" alterac-ai work-run get <taskWorkRunId> alterac-ai work-run complete work-run get work-run complete type compatibleStates executionOrigin excludeFromMetrics plan task create --type person"},{"url":"/docs/cli/output-and-identifiers","title":"Read CLI output and identifiers","searchDescription":"Choose Markdown or JSON output and keep project, task, Sprint, Milestone, work-run, session, and draft identifiers distinct.","sectionLabel":"Use the CLI","headings":["Keep identifiers distinct","Use file input for Markdown"],"headingIds":["keep-identifiers-distinct","use-file-input-for-markdown"],"prose":"$4d","code":"--json projectId --project taskNumber task get task update task delete task comment sprintNumber --sprint set-sprint --sprint milestoneNumber milestone get milestone update --milestone set-milestone --milestone taskWorkRunId work-run get work-run complete sessionNumber --session draftPlanId draftId milestone list list get"},{"url":"/docs/cli/tasks","title":"Task and work-run commands","searchDescription":"Create and update published tasks, assign a Sprint or Milestone, and inspect current planning membership.","sectionLabel":"Use the CLI","headings":["Create one immediate task","List published tasks","Show authoritative task details","Delete one published task","Update one published task","Assign a Sprint and classify later changes","Assign a Milestone and classify later changes","Retrieve work-run context","Add a task comment","Submit review output","Retrospective Correction compatibility"],"headingIds":["create-one-immediate-task","list-published-tasks","show-authoritative-task-details","delete-one-published-task","update-one-published-task","assign-a-sprint-and-classify-later-changes","assign-a-milestone-and-classify-later-changes","retrieve-work-run-context","add-a-task-comment","submit-review-output","retrospective-correction-compatibility"],"prose":"$4e","code":"$4f"},{"url":"/docs/tasks/overview","title":"Understand the task workflow","searchDescription":"Follow Coding agent or Person work from creation through work, review, completion, or deliberate closure.","sectionLabel":"Work with tasks","headings":["Follow Coding agent task states","Start work on a Person task","Close or reopen superseded work","Know the identifiers","Choose the next action"],"headingIds":["follow-coding-agent-task-states","start-work-on-a-person-task","close-or-reopen-superseded-work","know-the-identifiers","choose-the-next-action"],"prose":"$50","code":"--weight --clear-weight --mass --clear-mass #12"},{"url":"/docs/tasks/plans","title":"View and manage Plans","searchDescription":"Create and edit Plans, manage one task membership at a time, and review count-based progress and archive visibility.","sectionLabel":"Work with tasks","headings":["Create a Plan","Find a Plan","Review Plan details","Edit Plan details","Add, move, or remove one task","Archive or restore a Plan"],"headingIds":["create-a-plan","find-a-plan","review-plan-details","edit-plan-details","add-move-or-remove-one-task","archive-or-restore-a-plan"],"prose":"$51","code":""},{"url":"/docs/tasks/create-and-edit","title":"Create and edit a task","searchDescription":"Add task details and set independent Plan, Sprint, and Milestone membership, Mass or Weight, assignment, labels, and dependencies.","sectionLabel":"Work with tasks","headings":["Create a task","Set useful metadata","Choose a Milestone and classify changes","Choose a Sprint and classify changes","Inspect Sprint and Milestone change history","Estimate work","Edit or delete safely"],"headingIds":["create-a-task","set-useful-metadata","choose-a-milestone-and-classify-changes","choose-a-sprint-and-classify-changes","inspect-sprint-and-milestone-change-history","estimate-work","edit-or-delete-safely"],"prose":"$52","code":"alterac-ai task create alterac-ai task create \"Task details\" --title \"Short title\" --type person --type person alterac-ai task update <taskNumber> --title \"Replacement title\" --file --mass --weight --label --dependency --plan --sprint --milestone --assignee --clear-mass --clear-weight --clear-labels --clear-dependencies --clear-plan --clear-sprint --clear-milestone --clear-assignee size --mass --clear-mass --weight --clear-weight alterac-ai task delete <taskNumber> --yes"},{"url":"/docs/tasks/organize","title":"Organize tasks","searchDescription":"Search task numbers, titles, and descriptions, combine filters, and save or share a project task view.","sectionLabel":"Work with tasks","headings":["Find the work you need","Share or return to a task view","Find current and previous Sprint work","Understand Plan and dependency filters","Use metadata consistently"],"headingIds":["find-the-work-you-need","share-or-return-to-a-task-view","find-current-and-previous-sprint-work","understand-plan-and-dependency-filters","use-metadata-consistently"],"prose":"$53","code":"#246 timeout #246 # q closed=1 state=Closed"},{"url":"/docs/tasks/queue","title":"Queue a task","searchDescription":"Choose a coding agent, queue a task, and understand listener approval and active-work status.","sectionLabel":"Work with tasks","headings":["Queue the work","What happens next"],"headingIds":["queue-the-work","what-happens-next"],"prose":"$54","code":""},{"url":"/docs/tasks/comments","title":"Comment on a task","searchDescription":"Add general task context, manage comments you own, and distinguish task comments from review feedback.","sectionLabel":"Work with tasks","headings":["Add and manage a general comment","Use the right kind of comment"],"headingIds":["add-and-manage-a-general-comment","use-the-right-kind-of-comment"],"prose":"$55","code":""},{"url":"/docs/tasks/review","title":"Review and recover task work","searchDescription":"Submit Person work for review, use project default review branch guidance, or continue and recover coding-agent work.","sectionLabel":"Work with tasks","headings":["Submit and review Person work","Review completed work","View delivered code changes","Recover incomplete work","Choose the replacement coding agent","Continue"],"headingIds":["submit-and-review-person-work","review-completed-work","view-delivered-code-changes","recover-incomplete-work","choose-the-replacement-coding-agent","continue"],"prose":"$56","code":"main main main main main main main main"},{"url":"/docs/tasks/review-history","title":"Read review history","searchDescription":"Compare current and prior work runs, their review output, comments, attribution, and completion history.","sectionLabel":"Work with tasks","headings":["Inspect a work run","Understand continuation"],"headingIds":["inspect-a-work-run","understand-continuation"],"prose":"$57","code":""},{"url":"/docs/task-builder/overview","title":"Plan work with Task Builder","searchDescription":"Prepare proposed Plans and typed task drafts, edit draft content in the browser, and review the complete set before publication.","sectionLabel":"Plan work with Task Builder","headings":["Choose the right starting point","Keep the conversation and publication separate","Understand a Task Builder Session","Know what proposed Plans and drafts contain","Choose your next step"],"headingIds":["choose-the-right-starting-point","keep-the-conversation-and-publication-separate","understand-a-task-builder-session","know-what-proposed-plans-and-drafts-contain","choose-your-next-step"],"prose":"$58","code":"task list task get task create task update task delete taskNumber planNumber sessionNumber draftPlanId draftId"},{"url":"/docs/task-builder/start","title":"Start a planning session","searchDescription":"Create or select a Building Task Builder Session from a local AI planning conversation.","sectionLabel":"Plan work with Task Builder","headings":["Start with a planning conversation","Continue an existing plan","Check the structured result","Next step"],"headingIds":["start-with-a-planning-conversation","continue-an-existing-plan","check-the-structured-result","next-step"],"prose":"$59","code":""},{"url":"/docs/task-builder/refine","title":"Refine proposed Plans and draft tasks","searchDescription":"Edit Building draft type, content, Plan, labels and dependencies in the browser; refine proposed Plans, order and scheduling through the CLI.","sectionLabel":"Plan work with Task Builder","headings":["Improve the session first","Organize proposed Plans","Shape draft tasks","Edit draft content in the browser","Update draft content through the CLI","Assign a future Sprint","Recover saved Milestone intent","Set dependencies and order","Keep track of identities","Check the plan again"],"headingIds":["improve-the-session-first","organize-proposed-plans","shape-draft-tasks","edit-draft-content-in-the-browser","update-draft-content-through-the-cli","assign-a-future-sprint","recover-saved-milestone-intent","set-dependencies-and-order","keep-track-of-identities","check-the-plan-again"],"prose":"$5a","code":"--mass --weight task-builder task set-metric-exclusion /edit alterac-ai task-builder show <SESSION-NUMBER> updatedAt --expected-updated-at --expected-updated-at <TIMESTAMP> --mass --weight show set-plan set-labels set-dependencies --expected-updated-at show --help --expected-updated-at alterac-ai task-builder task set-sprint <DRAFT-ID> --sprint <SPRINT-NUMBER> --session <SESSION-NUMBER> alterac-ai task-builder task set-sprint <DRAFT-ID> --session <SESSION-NUMBER> alterac-ai task-builder show <SESSION-NUMBER> --json --session alterac-ai task-builder task set-milestone <DRAFT-ID> --milestone <MILESTONE-NUMBER> --session <SESSION-NUMBER> alterac-ai task-builder task set-milestone <DRAFT-ID> --milestone <MILESTONE-NUMBER> --milestone-change scope-change --session <SESSION-NUMBER> alterac-ai task-builder task set-milestone <DRAFT-ID> --session <SESSION-NUMBER> --session set-milestone --milestone-change"},{"url":"/docs/task-builder/review-and-publish","title":"Review and publish a session","searchDescription":"Review and edit Building draft content, review optional estimates and resolve scheduling blockers, and explicitly publish the complete Task Builder Session.","sectionLabel":"Plan work with Task Builder","headings":["Review the Building session","Resolve readiness messages","Resolve saved Milestone intent","Publish the complete set","Continue with normal task management"],"headingIds":["review-the-building-session","resolve-readiness-messages","resolve-saved-milestone-intent","publish-the-complete-set","continue-with-normal-task-management"],"prose":"$5b","code":"Started alterac-ai task-builder task set-sprint <DRAFT-ID> --sprint <SPRINT-NUMBER> --session <SESSION-NUMBER> --sprint task-builder task set-milestone Started --milestone-change scope-change task-builder task set-milestone <DRAFT-ID> --session <SESSION-NUMBER>"},{"url":"/docs/task-builder/archive-and-history","title":"Archive and review sessions","searchDescription":"Find Building and Published Task Builder Sessions, control archive visibility, and review publication history.","sectionLabel":"Plan work with Task Builder","headings":["Find the right session","Archive or restore a session","Understand published history","Find an archived session"],"headingIds":["find-the-right-session","archive-or-restore-a-session","understand-published-history","find-an-archived-session"],"prose":"$5c","code":""},{"url":"/docs/coding-agents/overview","title":"Configure a coding agent","searchDescription":"Bring your own coding agent through a compatible local command, configure its definition, and start listening for queued work.","sectionLabel":"Configure coding agents","headings":["Create your first definition","Make it available","Queue and approve a first run","Use optional code-exploration tools","Next steps"],"headingIds":["create-your-first-definition","make-it-available","queue-and-approve-a-first-run","use-optional-code-exploration-tools","next-steps"],"prose":"$5d","code":"{alterac-ai-message} Codex {alterac-ai-message} alterac-ai listen approve-changed"},{"url":"/docs/coding-agents/scopes","title":"Choose where a coding agent belongs","searchDescription":"Understand personal, organization, and project coding-agent ownership and the entries available when work is queued.","sectionLabel":"Configure coding agents","headings":["Ownership and availability","Enabled, hidden, and deleted are different","Copy a definition safely"],"headingIds":["ownership-and-availability","enabled-hidden-and-deleted-are-different","copy-a-definition-safely"],"prose":"$5e","code":""},{"url":"/docs/coding-agents/defaults-and-inheritance","title":"Set defaults and inheritance","searchDescription":"Set coding-agent defaults, understand organization policy, and predict the command selected for a project.","sectionLabel":"Configure coding agents","headings":["Set a default","Understand the selection order","Set organization policy","Check the effective choice"],"headingIds":["set-a-default","understand-the-selection-order","set-organization-policy","check-the-effective-choice"],"prose":"$5f","code":""},{"url":"/docs/coding-agents/worktrees","title":"Prepare repositories for task worktrees","searchDescription":"Understand how alterac.ai uses linked Git worktrees and what to check before concurrent task work.","sectionLabel":"Configure coding agents","headings":["Know what a new worktree contains","Use the repository's normal setup","Make hooks location-aware","Isolate parallel resources","Keep alterac.ai commands in the retained checkout","Clean up after review"],"headingIds":["know-what-a-new-worktree-contains","use-the-repositorys-normal-setup","make-hooks-location-aware","isolate-parallel-resources","keep-alteracai-commands-in-the-retained-checkout","clean-up-after-review"],"prose":"$60","code":".env pnpm install repository_root=\"$(git rev-parse --show-toplevel)\" \"$repository_root/scripts/check-before-commit.sh\" workspace_id=\"$(git branch --show-current | tr '/.' '-')\" ./scripts/start-local.sh --name \"$workspace_id\" --allocate-port .alterac-ai alterac-ai work-run complete 00000000-0000-0000-0000-000000000000 \\ --summary-file /path/to/repository/worktrees/301-example/summary.md \\ --hand-off-file /path/to/repository/worktrees/301-example/hand-off.md"},{"url":"/docs/coding-agents/codegraph","title":"Use CodeGraph with a coding agent","searchDescription":"Use optional CodeGraph alongside alterac.ai with agent access and a separate index for each task worktree.","sectionLabel":"Configure coding agents","headings":["Make it available in task worktrees","Add a short repository instruction"],"headingIds":["make-it-available-in-task-worktrees","add-a-short-repository-instruction"],"prose":"$61","code":"codegraph status --json projectPath codegraph_explore projectPath --path .codegraph/ ## CodeGraph Use CodeGraph only when already available; do not install it for a task. Initialize its index in the assigned task worktree and verify projectPath. If that worktree has no .codegraph directory, initialize it before exploration. For MCP, pass that absolute worktree root as projectPath to codegraph_explore. Keep repository exclusions and generated graph data ignored. Set CODEGRAPH_TELEMETRY=0 and DO_NOT_TRACK=1 for CLI and MCP processes. Run codegraph sync after edits before relying on results. If unavailable or unhelpful, use source search and direct reads. Follow the alterac.ai process and required repository validation throughout."},{"url":"/docs/coding-agents/command-templates","title":"Write a coding-agent command","searchDescription":"Write and validate a coding-agent command that receives alterac.ai routing and exact work-run context instructions.","sectionLabel":"Configure coding agents","headings":["Multi-line commands","Required placeholder and quoting","Fields and validation","Add queue-time option selectors","What is snapshotted"],"headingIds":["multi-line-commands","required-placeholder-and-quoting","fields-and-validation","add-queue-time-option-selectors","what-is-snapshotted"],"prose":"$62","code":"{alterac-ai-message} \\ coding-agent \\ --option value \\ \"{alterac-ai-message}\" coding-agent --option value \"...\" C:\\tools\\codex.exe \\\" ^ .alterac-ai/process.md task-work-run-id=[00000000-0000-0000-0000-000000000000] alterac-ai work-run get 00000000-0000-0000-0000-000000000000 {alterac-ai-message} {Alterac-ai-message} {Label:first option|second option} careful --mode coding-agent --mode {Mode:careful|quick} \"{alterac-ai-message}\" {Sandbox:|--sandbox workspace-write}"},{"url":"/docs/coding-agents/example-commands","title":"Example coding-agent commands","searchDescription":"Get started with copyable Claude Code, Codex, and Cursor CLI templates, tested CLI versions, and unverified variants.","sectionLabel":"Configure coding agents","headings":["Claude Code","Codex","Cursor CLI","Unverified Claude model and effort selectors"],"headingIds":["claude-code","codex","cursor-cli","unverified-claude-model-and-effort-selectors"],"prose":"$63","code":"claude --model {Model:opus|sonnet|haiku} --effort {Effort:high|medium|low|max} --permission-mode acceptEdits --verbose --output-format stream-json \"{alterac-ai-message}\" 2.1.280 fable codex --model {Model:gpt-6.1-sol|gpt-6-astra} --sandbox workspace-write --ask-for-approval on-request -c 'approvals_reviewer=\"auto_review\"' -c 'sandbox_workspace_write.network_access=true' -c 'model_reasoning_effort=\"{Effort:xhigh|high|medium|low|max}\"' -c 'model_reasoning_summary=\"concise\"' -c 'show_raw_agent_reasoning=false' -c 'model_verbosity=\"low\"' --search \"{alterac-ai-message}\" 0.159.2 agent --model auto \"{alterac-ai-message}\" 2026.10.01-e373342 agent --model claude-{Model:opus|sonnet}-5-5-{Effort:medium|high|low|xhigh|max} \"{alterac-ai-message}\" sonnet high claude-sonnet-5-5-high"},{"url":"/docs/coding-agents/trust","title":"Choose a command trust mode","searchDescription":"Choose how the local listener asks for approval before it runs a queued coding-agent command.","sectionLabel":"Configure coding agents","headings":["Trust modes","What counts as changed","Waiting for input"],"headingIds":["trust-modes","what-counts-as-changed","waiting-for-input"],"prose":"$64","code":"alterac-ai config trust approve-changed approve-changed always-allow approve-every-run always-allow always-allow approve-changed {alterac-ai-message}"},{"url":"/docs/coding-agents/listener","title":"Run the local task listener","searchDescription":"Start a local listener for queued work, approve commands safely, and understand terminal launches and queue snapshots.","sectionLabel":"Configure coding agents","headings":["Start listening","Understand launches and output","Why a task can remain queued","Recover safely"],"headingIds":["start-listening","understand-launches-and-output","why-a-task-can-remain-queued","recover-safely"],"prose":"$65","code":".alterac-ai alterac-ai listen Ctrl+C {alterac-ai-message} .alterac-ai/process.md {alterac-ai-message} alterac-ai config trust alterac-ai listen"},{"url":"/docs/projects/organizations-and-projects","title":"Create organizations and projects","searchDescription":"Start free with one person per organization and all features, then create the projects that hold your tasks and coding agents.","sectionLabel":"Manage your team and projects","headings":["Create an organization","Create a project","Understand ownership and access","Choose the organization time zone","Continue with local alterac.ai setup"],"headingIds":["create-an-organization","create-a-project","understand-ownership-and-access","choose-the-organization-time-zone","continue-with-local-alteracai-setup"],"prose":"$66","code":""},{"url":"/docs/projects/metrics","title":"Use project Metrics","searchDescription":"Choose a date range and understand what the project Metrics page shows when delivery data is or is not available.","sectionLabel":"Manage your team and projects","headings":["Choose a date range","Read completed-task throughput","Read accepted without follow-up","Read AI work time per completed task","Read human review time during working hours"],"headingIds":["choose-a-date-range","read-completed-task-throughput","read-accepted-without-follow-up","read-ai-work-time-per-completed-task","read-human-review-time-during-working-hours"],"prose":"$67","code":"N/A N/A N/A N/A N/A"},{"url":"/docs/projects/sprints","title":"Prepare and manage Sprints","searchDescription":"Prepare Sprints, inspect daily work and progress, complete or safely reopen existing Sprints, and correct retained history.","sectionLabel":"Manage your team and projects","headings":["Before you begin","Browse and prepare Sprints","Understand Sprint lifecycle availability","Read the Sprint Horizon","Read Sprint progress","Use the Sprint Team Pulse","Manage tasks on a Sprint page","Complete a Sprint and correct its history","Disabled Sprints","Reset a task view","Complete and start the following Sprint"],"headingIds":["before-you-begin","browse-and-prepare-sprints","understand-sprint-lifecycle-availability","read-the-sprint-horizon","read-sprint-progress","use-the-sprint-team-pulse","manage-tasks-on-a-sprint-page","complete-a-sprint-and-correct-its-history","disabled-sprints","reset-a-task-view","complete-and-start-the-following-sprint"],"prose":"$68","code":""},{"url":"/docs/projects/milestones","title":"Create and manage Milestones","searchDescription":"Manage Milestone tasks, complete and safely reopen outcomes, and correct retained history.","sectionLabel":"Manage your team and projects","headings":["Before you begin","Find an outcome","Read the Milestone Horizon","Read Milestone progress","Inspect task states and membership","Manage tasks on a Milestone page","Create or edit a Milestone","Start or complete a Milestone","Correct retained history","Safely reopen a Milestone","Delete a Planned record","Assign tasks with the CLI","Disabled Milestones","Reset a task view"],"headingIds":["before-you-begin","find-an-outcome","read-the-milestone-horizon","read-milestone-progress","inspect-task-states-and-membership","manage-tasks-on-a-milestone-page","create-or-edit-a-milestone","start-or-complete-a-milestone","correct-retained-history","safely-reopen-a-milestone","delete-a-planned-record","assign-tasks-with-the-cli","disabled-milestones","reset-a-task-view"],"prose":"$69","code":"task create --milestone <milestoneNumber> task update <taskNumber> --milestone <milestoneNumber> --clear-milestone task list --milestone <milestoneNumber> --milestone-change correction --milestone-change scope-change"},{"url":"/docs/projects/members-and-roles","title":"Manage members and roles","searchDescription":"Inspect license capacity, add members, and choose the access each person needs.","sectionLabel":"Manage your team and projects","headings":["Before you begin","Inspect license capacity","Add an organization member","Add a member to a project","Change a role or remove someone","Choose the right role"],"headingIds":["before-you-begin","inspect-license-capacity","add-an-organization-member","add-a-member-to-a-project","change-a-role-or-remove-someone","choose-the-right-role"],"prose":"$6a","code":""},{"url":"/docs/projects/labels","title":"Manage labels","searchDescription":"Create shared organization labels and project-specific labels that keep tasks, plans, and drafts organized.","sectionLabel":"Manage your team and projects","headings":["Before you begin","Start with default labels","Create a label","Choose an owner for the label","Use scoped labels","Keep shared definitions clear"],"headingIds":["before-you-begin","start-with-default-labels","create-a-label","choose-an-owner-for-the-label","use-scoped-labels","keep-shared-definitions-clear"],"prose":"$6b","code":"#175CD3 priority::high priority::high :: priority::high :: priority::high priority::low priority::low priority::high ::"},{"url":"/docs/projects/settings","title":"Change or delete an organization or project","searchDescription":"Change workspace details, configure independent Sprint and Milestone settings and review branch guidance, or delete a project or organization.","sectionLabel":"Manage your team and projects","headings":["Before you begin","Update details","Configure review branch guidance","Configure Sprints and Milestones","Browse and prepare Sprints","Read the Sprint Horizon","Read Sprint progress","Use the Sprint Team Pulse","Manage tasks on a Sprint page","Complete a Sprint and correct its history","Change automatic project access","Set the organization time zone","Configure working hours","Delete an organization or project","Set coding-agent policy separately"],"headingIds":["before-you-begin","update-details","configure-review-branch-guidance","configure-sprints-and-milestones","browse-and-prepare-sprints","read-the-sprint-horizon","read-sprint-progress","use-the-sprint-team-pulse","manage-tasks-on-a-sprint-page","complete-a-sprint-and-correct-its-history","change-automatic-project-access","set-the-organization-time-zone","configure-working-hours","delete-an-organization-or-project","set-coding-agent-policy-separately"],"prose":"$6c","code":"America/New_York"},{"url":"/docs/account/create-account","title":"Create an account","searchDescription":"Sign up, confirm your email, protect your account with an authenticator, and finish your profile.","sectionLabel":"Manage your account and security","headings":["Before you start","Create and confirm your account","Public page measurement","Set up an authenticator","Save recovery codes safely","What happens next"],"headingIds":["before-you-start","create-and-confirm-your-account","public-page-measurement","set-up-an-authenticator","save-recovery-codes-safely","what-happens-next"],"prose":"$6d","code":""},{"url":"/docs/account/log-in","title":"Log in","searchDescription":"Sign in with your password and authenticator, use a recovery code, and sign out safely.","sectionLabel":"Manage your account and security","headings":["Log in with an authenticator","Use a recovery code instead","Sign out","If you cannot log in"],"headingIds":["log-in-with-an-authenticator","use-a-recovery-code-instead","sign-out","if-you-cannot-log-in"],"prose":"$6e","code":""},{"url":"/docs/account/reset-password","title":"Reset a password","searchDescription":"Request a password-reset email, set a new password, and recover when a reset link does not work.","sectionLabel":"Manage your account and security","headings":["Request a reset link","If the email or link does not work"],"headingIds":["request-a-reset-link","if-the-email-or-link-does-not-work"],"prose":"$6f","code":""},{"url":"/docs/account/profile-and-layout","title":"Update your profile","searchDescription":"Complete your required display name and manage the profile details shown in your account settings.","sectionLabel":"Manage your account and security","headings":["Complete your profile","Manage account details"],"headingIds":["complete-your-profile","manage-account-details"],"prose":"Finish your profile after first-time authenticator setup so alterac.ai can show your required display name. Later, open account settings to review and update your current profile details. After saving recovery codes, enter your display name on Finish your profile . You can add a profile picture if you want. Select Save profile . The display name is required before you can enter the app. If you leave the flow before finishing it, log in again and complete the displayed profile step. Open Account settings from the app to update your profile and review security settings. In the left sidebar of an organization or project, the muted Version value above Collapse sidebar shows the exact running product version to share during support and deployment verification. If the version is unavailable, wait and try again later rather than reporting a guessed release. Keep your account email current so you can receive confirmation and password-reset emails. Use Change your email for that separate security-sensitive action.","code":""},{"url":"/docs/account/change-email","title":"Change your email","searchDescription":"Update the email used for your account and confirm the new address before it takes effect.","sectionLabel":"Manage your account and security","headings":["Change the address"],"headingIds":["change-the-address"],"prose":"Change your account email from Account settings when you need to use a different inbox for sign-in and account recovery. Open Account settings in the app. In the email section, enter the new email address and complete the requested confirmation. Open the confirmation email sent to the new address and use its link. The new address takes effect only after confirmation. Keep access to your current inbox until you finish, because alterac.ai sends a security notice when an email change is requested and again when it completes. If alterac.ai cannot send the confirmation email, your current address stays active. Keep the new address in the form and select Send confirmation again to request a fresh email. If you no longer control either inbox, do not repeatedly submit change requests. Restore access to your current account email first, or use the recovery path in Fix account access .","code":""},{"url":"/docs/account/change-password","title":"Change your password","searchDescription":"Change your signed-in account password after confirming your current password and second factor.","sectionLabel":"Manage your account and security","headings":["Change your password securely"],"headingIds":["change-your-password-securely"],"prose":"Change your password from Account settings when you can already sign in and want a new password. Open Account settings and select Change password . Confirm your current password and either the current code from your authenticator app or one recovery code. Enter and confirm the new password. Select Change password . Use at least 8 characters with uppercase, lowercase, a digit, and a symbol. The second confirmation protects this sensitive change if someone has access to an unlocked browser session. After a successful change, the browser session where you changed the password stays signed in. Other browser sessions and CLI credentials must sign in again with the new password and your second factor. Changing your password does not replace your recovery codes. If you used one as the second factor, it no longer works; check the remaining-code count and generate new recovery codes when needed.","code":""},{"url":"/docs/account/two-factor","title":"Manage an authenticator","searchDescription":"Set up or replace the authenticator app that protects your alterac.ai sign-in.","sectionLabel":"Manage your account and security","headings":["Set up your first authenticator","Replace an authenticator app","Recover when no authenticator or recovery code remains"],"headingIds":["set-up-your-first-authenticator","replace-an-authenticator-app","recover-when-no-authenticator-or-recovery-code-remains"],"prose":"$70","code":""},{"url":"/docs/account/recovery-codes","title":"Use recovery codes","searchDescription":"Store, use, and replace one-time recovery codes for safe backup account access.","sectionLabel":"Manage your account and security","headings":["Store codes when they are shown","Use a code to sign in","Generate new codes"],"headingIds":["store-codes-when-they-are-shown","use-a-code-to-sign-in","generate-new-codes"],"prose":"$71","code":""},{"url":"/docs/troubleshooting/account-access","title":"Fix account access","searchDescription":"Recover from confirmation, password, authenticator, recovery-code, and profile-completion, and legal-agreement access problems.","sectionLabel":"Solve a problem","headings":["You cannot confirm your email","You cannot sign in with your password","Your authenticator code is rejected","You signed in but must complete your profile","Agree to the Privacy Policy and Terms of Use","Next step"],"headingIds":["you-cannot-confirm-your-email","you-cannot-sign-in-with-your-password","your-authenticator-code-is-rejected","you-signed-in-but-must-complete-your-profile","agree-to-the-privacy-policy-and-terms-of-use","next-step"],"prose":"$72","code":""},{"url":"/docs/troubleshooting/cli-authentication","title":"Fix CLI login","searchDescription":"Recover when alterac.ai CLI login fails, credentials expire, or two-factor challenges, or current legal agreement is required.","sectionLabel":"Solve a problem","headings":["The CLI says you need to sign in","Stored credentials are rejected or have expired","A command still targets the wrong environment or account","Current legal agreement is required","Next step"],"headingIds":["the-cli-says-you-need-to-sign-in","stored-credentials-are-rejected-or-have-expired","a-command-still-targets-the-wrong-environment-or-account","current-legal-agreement-is-required","next-step"],"prose":"$73","code":"alterac-ai alterac-ai login alterac-ai login alterac-ai logout alterac-ai login alterac-ai login 403 Forbidden code: \"LegalAgreementRequired\" requiredDocuments agreementUrl: \"/account/legal-agreement\" GET /legal/privacy-policy GET /legal/terms-of-use POST /account/legal-agreement agreeToPrivacyPolicy agreeToTermsOfUse true privacyPolicyVersion termsOfUseVersion privacyPolicyIntegrityIdentifier termsOfUseIntegrityIdentifier integrityIdentifier hasAcceptedCurrentDocuments: true GET /account/legal-agreement 400 legalAgreement LegalAgreementRequired"},{"url":"/docs/troubleshooting/repository-setup","title":"Fix repository setup","searchDescription":"Recover an uninitialized, missing, invalid, stale, or wrongly selected alterac.ai repository configuration.","sectionLabel":"Solve a problem","headings":["The repository is not initialized","The selected project is wrong or no longer available","Managed files are missing or stale","A task worktree is missing dependencies or local configuration","The CLI itself is unavailable","Command not found after install","Install script errors","A newer CLI version is available","Next step"],"headingIds":["the-repository-is-not-initialized","the-selected-project-is-wrong-or-no-longer-available","managed-files-are-missing-or-stale","a-task-worktree-is-missing-dependencies-or-local-configuration","the-cli-itself-is-unavailable","command-not-found-after-install","install-script-errors","a-newer-cli-version-is-available","next-step"],"prose":"$74","code":".alterac-ai alterac-ai init .alterac-ai .alterac-ai alterac-ai init alterac-ai docs-update alterac-ai init .env alterac-ai --version alterac-ai init ~/.zshrc ~/.bash_profile ~/.bashrc ALTERAC_AI_NO_MODIFY_PATH=1 alterac-ai alterac-ai.exe sudo sudo alterac-ai --version"},{"url":"/docs/troubleshooting/listener","title":"Fix the local listener","searchDescription":"Diagnose unavailable coding agents, local approval waits, terminal launch fallback, duplicate listeners, and queued work.","sectionLabel":"Solve a problem","headings":["There is no available coding agent","The listener is not running","The listener is waiting for approval","A worker terminal did not open","The coding agent is waiting for permission or input","The task remains queued or an old listener is still shown","The organization license expired","Next step"],"headingIds":["there-is-no-available-coding-agent","the-listener-is-not-running","the-listener-is-waiting-for-approval","a-worker-terminal-did-not-open","the-coding-agent-is-waiting-for-permission-or-input","the-task-remains-queued-or-an-old-listener-is-still-shown","the-organization-license-expired","next-step"],"prose":"$75","code":"alterac-ai listen Active Active always-allow Ctrl+C Ctrl+C"},{"url":"/docs/troubleshooting/tasks-and-review","title":"Fix task and review workflows","searchDescription":"Recover when a task is unavailable, cannot be queued, has an unexpected state, or review and follow-up actions are unavailable.","sectionLabel":"Solve a problem","headings":["A task cannot be found or opened","Queue is unavailable or work does not start","A task stays Agent working after agent work stops","The work run is superseded or completion is rejected","Review actions are unavailable","Next step"],"headingIds":["a-task-cannot-be-found-or-opened","queue-is-unavailable-or-work-does-not-start","a-task-stays-agent-working-after-agent-work-stops","the-work-run-is-superseded-or-completion-is-rejected","review-actions-are-unavailable","next-step"],"prose":"$76","code":""},{"url":"/docs/troubleshooting/task-builder","title":"Fix Task Builder workflows","searchDescription":"Recover stale browser and CLI draft saves, optional estimates, scheduling intent, readiness, archive visibility, and Task Builder publication.","sectionLabel":"Solve a problem","headings":["The active session is missing or stale","The session is Published and cannot be edited","A browser save conflicts with a newer draft","A version-checked CLI update conflicts","Readiness shows errors or warnings","A dependency cycle or unavailable label blocks the session","Saved Sprint membership blocks publication","Saved Milestone intent blocks publication","A proposed Plan or draft ID is rejected","Publication did not complete or archived work is not visible","Next step"],"headingIds":["the-active-session-is-missing-or-stale","the-session-is-published-and-cannot-be-edited","a-browser-save-conflicts-with-a-newer-draft","a-version-checked-cli-update-conflicts","readiness-shows-errors-or-warnings","a-dependency-cycle-or-unavailable-label-blocks-the-session","saved-sprint-membership-blocks-publication","saved-milestone-intent-blocks-publication","a-proposed-plan-or-draft-id-is-rejected","publication-did-not-complete-or-archived-work-is-not-visible","next-step"],"prose":"$77","code":"alterac-ai task-builder show <SESSION-NUMBER> --expected-updated-at updatedAt set-plan set-labels set-dependencies show --expected-updated-at set-sprint set-milestone task-builder task set-milestone --milestone-change correction --milestone-change scope-change Started draftPlanId draftId"},{"url":"/docs/releases/v1.7.0","title":"Release notes for v1.7.0","searchDescription":"Edit Task Builder drafts in the browser, protect reviewed CLI changes, and get clearer organization and project setup guidance.","sectionLabel":"Release notes","headings":["Highlights","What changed","Important information"],"headingIds":["highlights","what-changed","important-information"],"prose":"$78","code":"--expected-updated-at --expected-updated-at"},{"url":"/docs/releases/v1.6.1","title":"Release notes for v1.6.1","searchDescription":"Fixes task creation with No Sprint selected, including in projects with no Sprints.","sectionLabel":"Release notes","headings":["Highlights","What changed"],"headingIds":["highlights","what-changed"],"prose":"Create your first task in a project without preparing a Sprint first. Fixed an error that blocked creating Coding-agent and Person tasks with No Sprint selected. Creation also works after selecting a Sprint and then clearing it. See Create and edit a task .","code":""},{"url":"/docs/releases/v1.6.0","title":"Release notes for v1.6.0","searchDescription":"New features, improvements, and fixes in alterac.ai v1.6.0.","sectionLabel":"Release notes","headings":["Highlights","What changed","Important information"],"headingIds":["highlights","what-changed","important-information"],"prose":"$79","code":""},{"url":"/docs/releases/v1.5.0","title":"Release notes for v1.5.0","searchDescription":"Plan queueing, Coding-agent review follow-ups, and other improvements in alterac.ai v1.5.0.","sectionLabel":"Release notes","headings":["Highlights","What changed"],"headingIds":["highlights","what-changed"],"prose":"$7a","code":""},{"url":"/docs/releases/v1.4.0","title":"Release notes for v1.4.0","searchDescription":"One-command CLI installs, timely update warnings, and first-pass task acceptance reporting in alterac.ai v1.4.0.","sectionLabel":"Release notes","headings":["Highlights","What changed","Important information"],"headingIds":["highlights","what-changed","important-information"],"prose":"$7b","code":""},{"url":"/docs/releases/v1.3.0","title":"Release notes for v1.3.0","searchDescription":"New features, improvements, and fixes in alterac.ai v1.3.0.","sectionLabel":"Release notes","headings":["Highlights","What changed","Person tasks: track human work next to agent work","Mass and Weight: size work the way it is done","Close tasks you no longer plan to finish","Plan mixed teams in Task Builder","A clearer start for every coding agent","More improvements and fixes","Important information"],"headingIds":["highlights","what-changed","person-tasks-track-human-work-next-to-agent-work","mass-and-weight-size-work-the-way-it-is-done","close-tasks-you-no-longer-plan-to-finish","plan-mixed-teams-in-task-builder","a-clearer-start-for-every-coding-agent","more-improvements-and-fixes","important-information"],"prose":"$7c","code":"--weight {alterac-ai-message} {task-work-run-id}"},{"url":"/docs/releases/v1.2.0","title":"Release notes for v1.2.0","searchDescription":"New features, improvements, and fixes in alterac.ai v1.2.0.","sectionLabel":"Release notes","headings":["Highlights","What changed","Important information"],"headingIds":["highlights","what-changed","important-information"],"prose":"$7d","code":""},{"url":"/docs/releases/v1.1.0","title":"Release notes for v1.1.0","searchDescription":"New features, improvements, and fixes in alterac.ai v1.1.0.","sectionLabel":"Release notes","headings":["Highlights","What changed","Important information"],"headingIds":["highlights","what-changed","important-information"],"prose":"$7e","code":""},{"url":"/docs/reference/cli-commands","title":"CLI command reference","searchDescription":"Find exact production alterac.ai command syntax, inputs, validation, output, and local state effects.","sectionLabel":"Reference","headings":["Command discovery","Repository setup and local state","Authentication","Listener and trust configuration","Label discovery","Create a task","Task discovery","Task details","Delete a published task","Update a task","Task Builder draft content","Task Builder draft labels, dependencies, and Plan membership","Task Builder future Sprint membership","Task Builder Milestone membership","Sprint membership and estimate changes","Milestone membership and estimate changes","Milestone records","Task comments","Work runs","Text, files, JSON, and project resolution","Retrospective Correction compatibility"],"headingIds":["command-discovery","repository-setup-and-local-state","authentication","listener-and-trust-configuration","label-discovery","create-a-task","task-discovery","task-details","delete-a-published-task","update-a-task","task-builder-draft-content","task-builder-draft-labels-dependencies-and-plan-membership","task-builder-future-sprint-membership","task-builder-milestone-membership","sprint-membership-and-estimate-changes","milestone-membership-and-estimate-changes","milestone-records","task-comments","work-runs","text-files-json-and-project-resolution","retrospective-correction-compatibility"],"prose":"$7f","code":"$80"},{"url":"/docs/reference/terminology","title":"alterac.ai terminology","searchDescription":"Look up the shared names for organizations, projects, tasks, work runs, Task Builder sessions, identifiers, states, task size, coding agents, and listeners.","sectionLabel":"Reference","headings":["Workspace and task terms","Task states","Task Builder terms","Coding-agent terms","Related recovery"],"headingIds":["workspace-and-task-terms","task-states","task-builder-terms","coding-agent-terms","related-recovery"],"prose":"$81","code":"alterac-ai listen"},{"url":"/docs/reference/manual-cli-install","title":"Download the CLI manually","searchDescription":"Download a verified stable alterac.ai CLI archive and set up a user-owned installation when you cannot run the install script.","sectionLabel":"Reference","headings":["3. Confirm it works","When the CLI reports a newer version","Important: unsigned-binary warnings","If something goes wrong"],"headingIds":["3-confirm-it-works","when-the-cli-reports-a-newer-version","important-unsigned-binary-warnings","if-something-goes-wrong"],"prose":"$82","code":"alterac-ai --version alterac-ai docs-update alterac-ai alterac-ai.exe alterac-ai alterac-ai --version"}],"children":"$L83"}] </article></body></html>