Document conversational operations and bound skill worker launches

README.md

@@ -17,7 +17,7 @@ You use Wrighty from a local directory on your machine that contains the project
 
 | Via | What it provides |
 | --- | --- |
-| **Interactively from within an AI agent.** | Use the Wrighty Skill to create, pick, and implement work items. |
+| **Interactively from within an AI agent.** | Use the Wrighty skill as a conversational alternative to the web console: summarize work, inspect processing state, manage Local Markdown workflow actions, and start or stop workers. You can also create, pick, and implement items. |
 | **Wrighty web console.** | Manage, sort, and filter the Local Markdown board; organize operational items and manage settings for both backends. |
 | **GitHub issues.** | Manage work items if using GitHub backend. |
 | **Wrighty worker.** | Automatically pick work items, execute them (headless) in a local AI agent, resume work after AI agent usage has expired, or hand off to another local AI agent. |
@@ -28,6 +28,13 @@ You use Wrighty from a local directory on your machine that contains the project
 > - All of Wrighty functionality (worker, web console, skill) is accessed or exposed via the Wrighty CLI app. 
 > - Access to work items is managed via claim tokens to avoid multiple consumers (human/agent/worker/ CLI) working on the same item.
 
+For **Local Markdown**, use the web Board or ask the skill to summarize columns and queue, send
+back, or resume eligible items, individually or in reviewed batches. For **GitHub**, plan work in
+GitHub Issues and Project views; the skill can summarize those items, but the Board workflow
+executors and batches are Local Markdown-only. Processing-state inspection and worker controls
+are available through the skill and web **Operations** for both backends. See
+[skill capabilities by backend](docs/reference/agent-skills.md#capabilities-by-backend).
+
 ## Where Wrighty has the most impact
 
 | Situation | What Wrighty does |
@@ -231,12 +238,12 @@ flowchart LR
 
 ### Choose your next step
 
-- Follow [Wrighty workflows](docs/workflows.md) to switch safely between the CLI and web console.
+- Follow [Wrighty workflows](docs/workflows.md) to switch safely between the skill, CLI, and web console.
 - Configure a [continuous unattended worker](docs/reference/worker.md) to process a bounded queue.
 - Use the [GitHub backend](docs/reference/configuration.md#initialize-the-github-backend) when
   workers need to coordinate across computers.
-- Install and invoke the [agent skill](docs/reference/agent-skills.md) for supervised, interactive
-  work.
+- Install and invoke the [agent skill](docs/reference/agent-skills.md) to manage work and workers
+  conversationally, or implement an item in your current agent session.
 - Tune model and reasoning choices with [execution profiles](docs/reference/execution-profiles.md).
 
 ## Recover a blocked agent without starting over
@@ -311,7 +318,8 @@ failure classification, retry schedule, provider circuit, and per-vendor support
 
 ## Work with an agent interactively
 
-Install the bundled skill, then invoke it explicitly from your agent:
+Use the skill to operate Wrighty from your conversation as well as implement tasks. Install the
+bundled skill, then invoke it explicitly from your agent:
 
 ```shell
 wrighty skill install
@@ -326,6 +334,8 @@ local installation, or `--scope project` for a deliberate repository-scoped copy
 /wrighty Pick the next available item, implement it, run its tests, and finish it.
 
 # Codex CLI, Desktop, or IDE extension
+$wrighty Show my board by status, with counts and item IDs. What needs attention?
+$wrighty Which workers are running, and can an existing worker pick up this item?
 $wrighty Help me turn this feature idea into a well-scoped work item. Show me the proposed
 title and body before creating it.
 
@@ -335,7 +345,11 @@ title and body before creating it.
 
 If a Copilot surface has no skill command, name the Wrighty skill in the prompt. The skill directs
 agents to mutate tracker state only through the CLI and to branch on structured error codes. See
-[Agent skills](docs/reference/agent-skills.md) for per-surface activation and update mechanics.
+[Agent skills](docs/reference/agent-skills.md) for backend support, queueing and worker-control
+examples, and installation/update mechanics. Worker launch is separate from queueing. The skill
+defaults to attached single-item runs; explicitly requested `--max-items` runs are also supported.
+Start continuous workers yourself in a terminal or the web console; the skill provides
+instructions and can inspect or stop existing runs. It does not keep a worker alive in the background.
 
 ## Ownership in four rules
 
@@ -354,8 +368,8 @@ backend, and the lower-level escape hatches.
 | Topic | Reference |
 | --- | --- |
 | Complete behavior reference | [Wrighty reference index](docs/reference/README.md) |
-| Workflows end to end (CLI and web console) | [docs/workflows.md](docs/workflows.md) |
-| What each action supports in the web console, GitHub, and CLI | [Operator actions by surface](docs/reference/operator-actions.md) |
+| Workflows end to end (skill, CLI, and web console) | [docs/workflows.md](docs/workflows.md) |
+| What each action supports in the skill, web console, GitHub, and CLI | [Operator actions by surface](docs/reference/operator-actions.md) |
 | Backends, `wrighty init`, `.wrighty.json` | [Configuration](docs/reference/configuration.md) |
 | User-scoped settings (`wrighty config`, host label) | [User settings](docs/reference/user-settings.md) |
 | IDs, create, edit, move, archive, import | [Work items](docs/reference/work-items.md) |
@@ -365,7 +379,7 @@ backend, and the lower-level escape hatches.
 | Choosing a model and reasoning effort per run | [Execution profiles](docs/reference/execution-profiles.md) |
 | Quota exhaustion, deferred retry, agent handoff | [Usage recovery and agent handoff](docs/reference/usage-recovery-and-agent-handoff.md) |
 | The web console | [Web console](docs/reference/web-console.md) |
-| Skill installation per agent surface | [Agent skills](docs/reference/agent-skills.md) |
+| Conversational operations, backend support, and skill installation | [Agent skills](docs/reference/agent-skills.md) |
 | What is stored where, version control | [Storage and version control](docs/reference/storage.md) |
 | Physical item metadata per backend | [Item metadata](docs/item-metadata/README.md) |
 | Architecture and protocol rationale | [Design documents](docs/design/) |

docs/reference/README.md

@@ -13,8 +13,8 @@ first-run guide. These pages are the authority for options, guarantees, and edge
 - [Claims and ownership](claims.md) — claimant attribution, the ownership rules, fencing
   guarantees per backend, recovery paths, and escape hatches.
 - [Action discovery](actions.md) — current actions, blocked alternatives, stable names, and JSON.
-- [Operator actions by surface](operator-actions.md) — task-oriented comparison of what the Local
-  web console, GitHub, and CLI can view or perform, with links to the authoritative procedures.
+- [Operator actions by surface](operator-actions.md) — task-oriented comparison of the skill,
+  web console, GitHub, and CLI, with backend support and links to the authoritative procedures.
 - [Supported agents and surfaces](supported-agents.md) — which agent families Wrighty supports for
   skills, headless work, session resume, Desktop opening, and handoff.
 - [Autonomous worker mode](worker.md) — eligibility, workspace modes, needs-attention and
@@ -28,11 +28,13 @@ first-run guide. These pages are the authority for options, guarantees, and edge
   and opt-in cross-agent handoff.
 - [Web console](web-console.md) — shared configuration and operations for both
   backends, plus the Local Markdown board/editor.
-- [Agent skills](agent-skills.md) — installing and updating the bundled skill per agent surface.
+- [Agent skills](agent-skills.md) — conversational board and worker operations, backend support,
+  example requests, and installation/update instructions per agent surface.
 - [Storage and version control](storage.md) — what each backend stores where, and what to
   commit.
 
 Related: [workflow guide](../workflows.md), [item metadata](../item-metadata/README.md), and
 [design documents](../design/).
 
-- [Worker discovery](workers.md): scoped run inspection and item pickup assessment.
+- [Worker discovery and control](workers.md): scoped run inspection, item pickup assessment,
+  drain, and interrupt.

docs/reference/actions.md

@@ -15,8 +15,10 @@ reason codes. An optional action name selects one descriptor; an unknown name re
 Wrighty's normal nonzero exit status and stderr JSON contract. Do not combine a selected name with
 `--all`.
 
-Discovery is read-only. Queue, Send back, and Resume report `execution: "supported"`; other
-catalogue entries remain `manual-only`. Listing an action never claims an item, starts a vendor
+Discovery is read-only. On Local Markdown, Queue, Send back, and Resume provide workflow
+executors; check each action's availability as well as its execution metadata. On GitHub those
+Board actions are unavailable with `NOT_SUPPORTED`. Other catalogue entries remain `manual-only`.
+Listing an action never claims an item, starts a vendor
 session, grants permission, or overrides a pending retry.
 
 ## Execute one workflow action
@@ -28,7 +30,7 @@ wrighty actions local:42 send-back --exec --yes --json
 wrighty actions local:42 resume --exec --yes --json
 ```
 
-These three executors support Local Markdown and share the web Board's policy and backend
+These three executors support Local Markdown only and share the web Board's policy and backend
 operation. `--exec` requires one action name and cannot use `--all`. An interactive invocation
 shows the consequence and prompts; redirected input and JSON require `--yes`. This authorizes
 only the named operation. Neither discovery nor `--yes` grants takeover or starts a worker.

docs/reference/agent-skills.md

@@ -1,7 +1,116 @@
 # Agent skills
 
-The package contains a narrow `wrighty` Agent Skill shared by Codex, Claude Code, GitHub Copilot,
-and OpenCode:
+The bundled `wrighty` skill lets you manage work and workers from Codex, Claude Code, GitHub
+Copilot, or OpenCode. It is a conversational alternative to the web console for everyday board
+and processing operations, and can also help author or implement a work item in the current
+agent session. It operates through the Wrighty CLI against the same items and claims as the web
+console; switching surfaces requires no synchronization.
+
+## Capabilities by backend
+
+Workflow status describes where an item sits in planning. Operational state describes its
+processing: for example, an In Progress item may be working, awaiting clarification, or scheduled
+to retry. The skill keeps these views separate, just as the web console separates Board from
+Operations.
+
+| Ask the skill to… | Local Markdown | GitHub |
+| --- | --- | --- |
+| Summarize items by workflow status, including counts and IDs | Yes; a conversational view of the Local Markdown board | Yes; reads tracked issues and configured Project statuses. GitHub Project views remain the planning board |
+| Explain processing state, blockers, claims, and available actions | Yes | Yes; exact local session and workspace details require the recording installation |
+| Create, inspect, or implement a work item | Yes, through the existing claim-aware CLI workflows | Yes, through the existing claim-aware CLI workflows |
+| Queue, Send back, or Resume through the Board workflow executors | Yes, for eligible items | Not supported by these executors; use the appropriate GitHub planning or Wrighty continuation workflow |
+| Apply those workflow actions in a reviewed batch | Yes, on the exact frozen selection | Not supported; the skill should explain the limitation without applying a substitute mutation |
+| List workers and assess pickup for an item | Yes, within the local configuration scope | Yes, within the local configuration scope; this is not a list of workers on every GitHub-connected computer |
+| Start an exact-item, next-item, or bounded queue worker | Yes, when authorized and the host can own the process | Yes, subject to the same launch checks, including GitHub execution/context approval |
+| Start continuous processing | Instructions for the user to start it in a terminal or web console; the skill does not launch it | Same boundary |
+| Inspect, drain, or interrupt a registered worker | Yes, for verified local CLI or web-hosted runs | Yes, for verified local CLI or web-hosted runs |
+
+The web **Board** and general item editor exist only for Local Markdown. With GitHub, manage
+planning in Issues and Project views; web **Operations** remains available for worker and item
+processing state on both backends. An unsupported Board action does not mean the GitHub backend
+cannot process or continue work. Inspect the item's available actions and use the supported
+[GitHub workflow](../workflows.md#approve-github-context-and-invalidate-edits) or
+[targeted continuation](worker.md#the-two-path-resume-model). Generic status moves are not
+substitutes for Queue, Send back, or Resume semantics.
+
+## Example requests
+
+These examples use Codex's `$wrighty` invocation. Use the equivalent form for your
+[agent surface](#supported-skill-surfaces), and replace IDs with those returned for your tracker.
+
+```text
+$wrighty Show active work grouped by status, with counts and canonical item IDs.
+$wrighty What needs attention? Separate blocked items from scheduled retries.
+$wrighty Can an existing worker pick up this item? Explain the evidence; do not start one.
+
+# Local Markdown workflow actions
+$wrighty Queue local:12 for automatic processing. Do not start a worker.
+$wrighty Send local:19 back to the backlog.
+$wrighty Resume the recorded session for local:23 by queueing it for a worker.
+$wrighty Preview queueing the Todo items in area=api. Show exactly what would change first.
+
+# Worker operations on either backend
+$wrighty Process this exact item with the configured worker agent and a 30-minute item timeout.
+I authorize unattended processing of this item only. Keep the run attached and report the outcome.
+$wrighty Process at most three eligible items with a 30-minute item timeout and a five-minute
+idle timeout. Keep the run attached and report the results.
+$wrighty Show me how to start a continuous worker in my terminal.
+$wrighty Stop worker <run-id> after its current item; let that item finish.
+$wrighty Interrupt worker <run-id> now, including its active agent. Report any recovery needed.
+```
+
+The skill uses the configured workflow statuses and reports filters or incomplete counts.
+Queueing, resuming a recorded session for a worker, and starting a worker are separate effects.
+Requests that authorize an effect can proceed without repeated confirmation; a preview alone
+does not authorize execution. Batch results identify applied, skipped, failed, or uncertain items.
+With the worker-queue policy enabled, Queue authorizes automatic processing and Send back revokes
+that authorization. If the policy is disabled, execution permission remains a separate setting.
+See [workflow actions](actions.md) for eligibility and revalidation.
+
+Worker pickup is advisory: “could pick up” is not a reservation or a timing guarantee, and
+“unknown” is not permission to launch a duplicate. Worker inspection covers registrations in the
+current local configuration; remote, unregistered, and other-configuration workers can be outside
+that view. See [worker discovery and control](workers.md).
+
+## Worker ownership and stopping
+
+The skill launches only finite runs attached to their invoking command. It defaults to
+`worker --item ID` for an exact item or `worker --once` for the next eligible item. An explicitly
+requested bounded queue run may use `--max-items N`, with item and idle timeouts. That limits the
+number processed, not total elapsed time or the identities of the selected items: the worker
+selects eligible work as it proceeds. It is different from a frozen batch of workflow actions.
+
+**Start continuous workers yourself**, either in your terminal or with **Start worker** in the
+web console. The skill supplies instructions and states that it has not started the process;
+it does not launch a continuous worker even if the agent host offers a retained terminal. An
+idle timeout alone does not change this rule. It also does not repeat finite runs to simulate
+continuous processing. The skill can inspect, assess pickup from, drain, and interrupt workers
+you have already started.
+
+For allowed finite runs, if the agent surface cannot keep the command attached through
+completion, the skill supplies the command for you to run instead. This is a skill guidance
+boundary; the CLI continues to support continuous workers for terminals and the web host.
+
+A conversation does not guarantee background execution or monitoring after task cancellation,
+application exit, logout, or restart. There is no Wrighty detach command, service installation, or
+startup/restart management in this workflow. Worker-spawned implementation sessions cannot
+recursively start workers.
+
+**Drain** closes intake and lets the current item finish. **Interrupt** cancels the current agent
+process tree and performs interruption bookkeeping; it does not mark the item successfully
+completed. Both address a verified run ID, including individual web-hosted runs that share a
+process. The skill distinguishes an accepted stop request from completed shutdown, checks the
+item outcome, and does not fall back to killing an OS process. See [worker control](workers.md#cooperative-control).
+
+## Install and maintain the skill
+
+Run your agent in the configured project with access to the `wrighty` executable. For GitHub,
+the agent's command environment also needs network access and an authenticated `gh` CLI with
+the repository/Project permissions described in [configuration](configuration.md#initialize-the-github-backend).
+Installing a skill does not grant those permissions. If tracker access fails, the agent should
+report which observations are unavailable rather than invent counts or eligibility.
+
+Install for a selected agent, or all supported destinations:
 
 ```shell
 wrighty skill install --agent codex
@@ -180,19 +289,8 @@ incomplete, but the skill does not present them as ready or enable automatic pro
 same assessment passes. Fresh worker sessions independently assess the approved context they
 receive; the skill does not stamp items with a reusable “verified” marker.
 
-The bundled skill supports board overview using configured workflow order, operational triage,
-shared action discovery, and scoped worker/pickup assessment. `list --json` keeps its `result` array
-and adds `listing` metadata: status order, archive/filter/limit scope, returned count, and whether
-the result may be truncated. See [worker discovery](workers.md). Update an installed skill through
-the existing `wrighty skill update` command to receive these workflows.
-
-The bundled skill also executes individual Local Markdown Queue, Send back, and Resume requests
-through `actions <id> <name> --exec --yes --expected-version <stateVersion> --json`, after the
-requested effect is authorized. CLI and web share eligibility and locked revalidation. Execution
-returns the resulting state and refreshed worker pickup evidence; it does not launch a worker.
-See [action execution](actions.md).
-
-The skill also supports reviewed Local Markdown batches through `batch preview`, `batch show`,
-and `batch execute --yes`. It reports the exact frozen subset and partial results, including
-uncertain outcomes after interruption. CLI and web batch operations share the Core execution loop;
-the CLI persists its own previews/results for cross-process use. See [batch workflow actions](actions.md#batch-workflow-actions).
+The skill's Local Markdown workflow actions share eligibility and locked revalidation with the
+web Board. CLI and web batches share the Core execution loop; the CLI persists its own previews
+and results for use across invocations. Worker discovery and cooperative control also use the
+shared Core services. The skill describes these outcomes in conversation; it does not maintain a
+separate board or worker scheduler.