@dotdrelle/wiki-manager 0.15.42 → 0.15.48

package/README.md

@@ -8,7 +8,7 @@ endpoints, and provides the `donna` shell: an agent-first terminal UI that can
 inspect workspaces, run safe manager commands, call MCP tools, guide production
 jobs, and run one-shot headless tasks.
 
-Current coordinated release: **0.14.11**. Managed `llm-wiki` services expose
+Current coordinated release: **0.15.48**. Managed `llm-wiki` services expose
 the Wiki Graph v2 browser and APIs; rebuild the `llm-wiki` image when deploying
 this release through Docker.
 
@@ -198,7 +198,7 @@ Then send a one-line prompt to confirm the **LLM answers**, e.g.
 > separate `baseUrl`/`apiKey`, and reranking) used for retrieval-grounded answers.
 
 **7 — Try a few commands & prompts.**
-Plain-language prompts (web chat **or** `donna` shell):
+Plain-language prompts (the web **Agent/Donna** mode or the `donna` shell):
 
 ```text
 "Summarize wiki/index.md and list the pages it links to."
@@ -210,7 +210,7 @@ Slash primitives (shell):
 
 ```text
 /wiki                # inspect the wiki
-/skills              # bundled examples: pipeline, diagnose, status, wiki-sync
+/skills              # bundled workflows: pipeline, wiki-sync, wiki-build, deliver, new-template, diagnose, status
 /skills run pipeline # run the shipped end-to-end example
 ```
 
@@ -273,7 +273,7 @@ just reopens the web page.)*
 The scaffold ships **ready-to-use examples**. In the shell, explore them:
 
 ```text
-/skills              list the bundled examples (diagnose, pipeline, status, wiki-sync…)
+/skills              list the bundled examples (pipeline, wiki-sync, wiki-build, deliver, diagnose, status…)
 /skills show <name>  see what an example does
 /skills run <name>   run it to see the result
 ```
@@ -307,12 +307,15 @@ the rules in the **build-context**.
 The process always follows the same chain. Two entry points depending on your
 starting source.
 
-Everything is driven **in plain language** (the web interface chat or the `donna`
-shell), or by running a ready-made **skill**. No command line needed.
+Everything is driven **in plain language** from Agent/Donna mode, or by running
+a ready-made **skill**. Direct Chat is deliberately read-only with respect to
+production orchestration: it can answer and inspect allowed data, but it does
+not start a skill or a production job. No command line is needed.
 
 ### Entry point A — from a wiki / Confluence export
 
-At each step, either you **ask for it in plain language**, or you **run the skill**.
+At each step, either you **ask Donna for the action in Agent mode**, or you
+**run the skill explicitly**.
 
 1. **Export** Confluence (via the CME agent) → the markdown lands in
    `raw/untracked/`.
@@ -329,8 +332,12 @@ At each step, either you **ask for it in plain language**, or you **run the skil
    rendering.
    → *"Export and polish the deliverables"*
 
-> 💡 Even simpler: `/skills run wiki-sync` chains export + ingestion, and
-> `/skills run pipeline` runs the whole chain end to end.
+> 💡 Even simpler: `/skills run wiki-sync` chains export + ingestion,
+> `/skills run wiki-build` regenerates the deliverables, `/skills run deliver`
+> publishes them (add `polish` to refine the rendering), and
+> `/skills run pipeline` runs the whole chain end to end. The three step skills
+> take an optional argument — a source name, or a template with or without its
+> `.md` extension.
 
 ### Entry point B — from a simple PDF (the fastest)
 
@@ -556,6 +563,14 @@ including under `"*"`. Multi-step work belongs to `/agent`.
 An `allowActions` key written by an older manager is folded into `allow` on
 read and removed on the next `agents up`.
 
+`chatAccess` is not how workspace context reaches chat. The workspace profile
+(`.wiki/profile.md`) is read from disk and injected into the system prompt of
+both modes, so durable preferences — tone, formatting, notification recipient —
+shape every reply without a tool call and without an allow-list entry. Adding
+`profile_read` here would help no existing install anyway: the scaffold's
+additive merge only fills missing top-level keys and never edits an allow-list
+you already have.
+
 ### Adding a connector from the served chat UI
 
 `mcp.endpoints.json` stays hand-editable, but the Connectors panel of
@@ -619,22 +634,25 @@ Each recovery is emitted as `run_replanned` and appears in runtime state as
 `replans`. Limit attempts with `WIKI_MANAGER_REPLANNER_MAX_REPLANS` or per run
 with `"replans": 1` in the `/run` body.
 
-Runtime approvals support two levels. For run-level approval, post `/run` with
-`"requireApproval": true`; the runtime emits `run_pending_approval` before the
-first action and waits for `POST /approve?runId=...`. For tool-level approval,
-set `requireApproval` on an external endpoint, or set
-`WIKI_MANAGER_REQUIRE_APPROVAL_TOOLS=production.production_start_job` for
-workspace-native MCP tools. Pending tool approvals appear in the queue with
-status `pending_approval` and can be approved with `POST /approve?itemId=...`
-or the shell command `/approve item <id>`. The approval timeout defaults to 10
+Runtime approvals are bounded to a run, plan revision and approval class.
+Mutating orchestrated tasks **wait for approval by default**, including tasks
+created by a skill or a directly selected capability such as ingest or
+pipeline. Approve them by replying "valide tout", running `/approve`, or
+clicking Approve in either UI (Shell right-pane banner, or the `serve` banner
+above the composer). `POST /approve` also accepts an explicit run scope.
+
+An explicitly launched skill is also approval-gated. For an orchestrated skill,
+the scheduler blocks each uncovered mutating task; for a `direct` skill, the
+run-level gate blocks its first direct mutation. Declaring `execution: direct`
+changes routing and available tools—it does not grant automatic approval.
+
+External direct MCP tools may additionally declare a per-tool `requireApproval`
+policy. Their pending entries can be approved with
+`POST /approve?itemId=...` or `/approve item <id>`. The timeout defaults to ten
 minutes and can be changed with `WIKI_MANAGER_APPROVAL_TIMEOUT_MS` or
-`approvalTimeoutMs` in the `/run` body.
-
-Directly-launched capability runs (ingest, pipeline) now **wait for approval by
-default** before their mutating tasks: reply "valide tout", run `/approve`, or
-click Approve in either UI (Shell right-pane banner, or the `serve` banner above
-the composer). Auto-approval only happens when the run is started with
-`autoApprove: true` (headless/CI).
+`approvalTimeoutMs` in the `/run` body. Auto-approval is never inferred from a
+skill or an interactive UI: it requires the caller to pass
+`autoApprove: true`, intended for headless/CI (`--auto-approve`).
 
 ### Parallelism & throughput
 
@@ -844,6 +862,38 @@ wiki-workspace wiki my-project build --plan
 wiki-workspace wiki my-project build
 ```
 
+### Resetting a workspace
+
+```bash
+wiki-workspace wiki my-project down            # the services must be stopped
+wiki-workspace wiki my-project reset --dry-run # what would go, what stays
+wiki-workspace wiki my-project reset
+```
+
+`reset` empties a workspace while keeping the **method**: `.wikirc*` (provider,
+model, retrieval, per-profile variants), `templates/` and `build-context/` —
+plus `.env`, which holds the workspace's ports and MCP tokens and without which
+nothing could be restarted.
+Everything the workspace produced, cached or logged goes — `wiki/`,
+`deliverables/`, `raw/untracked/`, `raw/ingested/`, `.wiki/` (vector index,
+cache, logs, tmp, build state, skills, profile, system prompt), `CLAUDE.md`,
+`.gitignore` — then `wiki init` puts the empty structure back.
+
+Three things worth knowing:
+
+- `.git/` is kept when present, so the state from before the reset stays
+  reachable through `wiki restore`. It is the only undo there is.
+- The command refuses to run while workspace services are up: a container
+  writing into the bind mount would recreate part of what was erased and leave
+  files owned by another UID behind.
+- It stops there. Nothing is re-synced and nothing is rebuilt — refilling the
+  workspace is a decision, not a side effect of emptying it.
+
+It is available **only** here: there is no `wiki reset` CLI subcommand, no
+production job type, no MCP tool and no skill for it. Nothing Donna can call
+may erase a workspace. Confirmation is interactive (retype the workspace name)
+unless you pass `--yes`.
+
 ## Services
 
 The shared `docker-compose.yml` starts one workspace stack:
@@ -991,6 +1041,61 @@ Useful primitives:
 Skills are loaded only from the active workspace. The manager itself has no root
 `SKILL.md` and no root `skills/` directory.
 
+Executable skills are resolved by the runtime, not expanded into a private LLM
+prompt by each UI. `/skills run <name>` and `/<name>` therefore use the same
+path in the Shell and in `llm-wiki serve`; headless `--skill` posts the same
+invocation to `/run`. Built-in commands keep priority (`/status` remains the
+Shell status primitive), while `/skills run status` explicitly selects a skill
+with the same name.
+
+Donna receives only the sanitized skill catalogue (name, description and
+parameters) when selecting a skill from natural language. The runtime rereads
+and compiles the body after selection. Conversation, queue, audit, SSE and run
+records expose only the public invocation, for example
+`/wiki-build template="overview"`; the compiled objective remains private
+execution material. An informational question about a skill therefore remains
+a question—it does not launch that skill. A natural-language action launches a
+skill only when Donna finds one strong, unique match and all required parameters
+are present; an explicit command always wins.
+
+Every skill may declare its execution policy in front matter:
+
+```yaml
+---
+name: new-template
+description: Create one reusable deliverable template
+execution: direct
+params:
+  - family
+  - intent
+---
+```
+
+`execution: orchestrated` is the default. It gives the compiled run read tools
+plus capability delegation, but no direct mutating MCP tools. Use it for
+production workflows whose agents provide a plan, locks, progress and bounded
+approvals. `execution: direct` gives the compiled run its ordinary direct tools
+and removes runtime delegation; use it for a focused operation such as writing
+one template file. The policy is snapshotted when the chain is created, so an
+edited skill cannot change permissions halfway through an existing chain.
+
+The runtime compiles a skill into natural-language objectives. Paragraphs alone
+do not split work: an existing complex capability such as `knowledge.pipeline`
+stays one objective, one capability resolution and one run. Strong workflow
+boundaries create a sequential execution chain instead. In the shipped
+scaffold, `pipeline`, `wiki-ingest`, `wiki-build`, `deliver`, `diagnose`,
+`status` and `new-template` each compile to one run; `wiki-sync` compiles to an
+export run followed by an ingest run. Chain items contain `chainId`, sequence,
+optionality and continuation policy, but never a precomputed `capabilityPlan`.
+Each item is resolved only when its run starts.
+
+`/run cancel` cancels the current run and skips only the remaining required
+items of the same chain. It leaves standalone requests and other chains intact.
+`/run kill` deliberately keeps its broader workspace scope and purges every
+queued control request. `/queue cancel <id>` remains item-scoped. The Activity
+views in both UIs derive their Chain section from the event-sourced control
+queue, including `skipped` and `skipReason`; no separate chain state exists.
+
 Workspace switching is isolated. When you run `/use my-project`, the shell
 switches both the displayed conversation and the LLM history to `my-project`.
 Returning to another workspace restores that workspace's in-memory conversation
@@ -1073,9 +1178,16 @@ node ./bin/wiki-manager.js --headless --workspace my-project --prompt "check pro
 
 Headless mode creates a normal session, runs `/use`, and writes a log under
 `.wiki/logs/` by default. `--prompt` runs one agent turn unless `--wait` is passed.
-`--skill` uses the agentic loop by default: agent turn, wait for active MCP jobs
-declared through `_activity.poll`, then re-invoke the agent with the completed job
-summary so it can start the next required step.
+`--skill "<name> [arguments...]"` submits `/<name> <arguments...>` to the same
+runtime resolver used by the Shell and Serve. It waits for the complete
+`chainId`, not only the first run: every control item must become terminal, and
+any failed item yields exit code 1. A chain waiting for approval returns
+immediately with guidance unless `--auto-approve` was requested. Combining
+`--prompt` with runtime `--skill` ignores the prompt and reports that fact in
+the headless log. `--no-runtime` keeps the legacy local execution path as an
+explicit compatibility mode, but it still enforces the skill's declared
+`execution` policy. A direct legacy skill requires the explicit
+`--auto-approve` opt-in before receiving direct tools.
 
 Useful headless controls:
 

package/mcp.endpoints.example.json

@@ -29,7 +29,7 @@
   "chatAccess": {
     "maxToolIterations": 8,
     "servers": {
-      "llm-wiki":         { "allow": ["help_list", "help_read", "help_search", "wiki_workspace_status", "wiki_list_pages", "wiki_read_page", "wiki_read_pages", "wiki_search_context", "wiki_collect_context", "wiki_read_ingested_source"] },
+      "llm-wiki":         { "allow": ["help_list", "help_read", "help_search", "wiki_workspace_status", "wiki_list_pages", "wiki_read_page", "wiki_read_pages", "wiki_search_context", "wiki_collect_context", "wiki_read_ingested_source", "wiki_outline", "template_read", "template_write", "build_context_write"] },
       "wiki-production":  { "allow": ["production_job_status", "production_jobs_list"] },
       "cme":              { "allow": ["cme_status", "cme_sources_list", "cme_export_status"] }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.15.42",
+  "version": "0.15.48",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",
@@ -11,7 +11,7 @@
   },
   "scripts": {
     "start": "bun ./bin/wiki-manager.js",
-    "test": "node --test src/cli/runtimeStartup.test.js src/cli/wiki-manager.test.js src/agent/graph.test.js src/contracts/schemas.test.js src/core/activity.test.js src/core/env.test.js src/core/agentsCompose.test.js src/core/profileServiceStatus.test.js src/core/buildInfo.test.js src/core/agentEvents.test.js src/core/runtimeLog.test.js src/activity/activityAggregator.test.js src/graph/runGraphProjector.test.js src/core/workflow.test.js src/core/planPatch.test.js src/core/agentLoop.test.js src/core/plan.test.js src/core/mcp.test.js src/core/toolLoop.test.js src/core/documentIntake.test.js src/core/dockerCompose.test.js src/core/otherWorkspacesRunning.test.js src/core/wikiSetup.test.js src/core/wikiWorkspace.test.js src/core/wikirc.test.js src/core/workspaceInherit.test.js src/core/cacert.test.js src/core/composeOverrides.test.js src/core/setEnvValue.test.js src/core/commandFailure.test.js src/core/googleGrants.test.js src/core/modelFetch.test.js src/core/startupCheck.test.js src/core/queueStore.test.js src/orchestrator/agentRegistry.test.js src/orchestrator/capabilityRegistry.test.js src/orchestrator/capabilityResolver.test.js src/orchestrator/planValidator.test.js src/orchestrator/planIntegrator.test.js src/orchestrator/taskStatuses.test.js src/orchestrator/scheduler.test.js src/orchestrator/attemptManager.test.js src/orchestrator/resultAggregator.test.js src/orchestrator/approvalPolicy.test.js src/orchestrator/dispatcher.test.js src/orchestrator/objectiveResolver.test.js src/commands/slash.test.js src/shell/repl.test.js src/shell/setupWizardModality.test.js src/shell/setupWizardPlaceholders.test.js src/shell/setupWizardSuggestions.test.js src/shell/setupWizardDiscovery.test.js src/shell/wrapText.test.js src/runtime/lifecycle.test.js src/runtime/store.test.js src/runtime/controlMessages.test.js src/runtime/recoveryManager.test.js src/runtime/server.test.js src/runtime/supervisor.test.js src/runtime/delegation.test.js src/runtime/runner.test.js src/runtime/runner.e2e.test.js src/runtime/donna-contract.test.js src/runtime/auth.test.js",
+    "test": "node --test src/core/skillInvocation.test.js src/core/skillCompiler.test.js src/runtime/skillRun.test.js src/runtime/controlDrain.test.js src/runtime/controlCancellation.test.js src/cli/runtimeStartup.test.js src/cli/wiki-manager.test.js src/agent/graph.test.js src/agent/skillRecursion.test.js src/contracts/schemas.test.js src/core/activity.test.js src/core/env.test.js src/core/agentsCompose.test.js src/core/profileServiceStatus.test.js src/core/workspaceProfile.test.js src/core/buildInfo.test.js src/core/agentEvents.test.js src/core/skillChainView.test.js src/core/runtimeLog.test.js src/activity/activityAggregator.test.js src/graph/runGraphProjector.test.js src/core/workflow.test.js src/core/planPatch.test.js src/core/agentLoop.test.js src/core/plan.test.js src/core/mcp.test.js src/core/toolLoop.test.js src/core/documentIntake.test.js src/core/dockerCompose.test.js src/core/otherWorkspacesRunning.test.js src/core/wikiSetup.test.js src/core/wikiWorkspace.test.js src/core/wikirc.test.js src/core/workspaceInherit.test.js src/core/cacert.test.js src/core/composeOverrides.test.js src/core/setEnvValue.test.js src/core/commandFailure.test.js src/core/googleGrants.test.js src/core/modelFetch.test.js src/core/startupCheck.test.js src/core/queueStore.test.js src/orchestrator/agentRegistry.test.js src/orchestrator/capabilityRegistry.test.js src/orchestrator/capabilityResolver.test.js src/orchestrator/planValidator.test.js src/orchestrator/planIntegrator.test.js src/orchestrator/taskStatuses.test.js src/orchestrator/scheduler.test.js src/orchestrator/attemptManager.test.js src/orchestrator/resultAggregator.test.js src/orchestrator/approvalPolicy.test.js src/orchestrator/dispatcher.test.js src/orchestrator/objectiveResolver.test.js src/commands/slash.test.js src/shell/repl.test.js src/shell/setupWizardModality.test.js src/shell/setupWizardPlaceholders.test.js src/shell/setupWizardSuggestions.test.js src/shell/setupWizardDiscovery.test.js src/shell/wrapText.test.js src/runtime/lifecycle.test.js src/runtime/store.test.js src/runtime/workspaceIsolation.test.js src/runtime/controlMessages.test.js src/runtime/recoveryManager.test.js src/runtime/server.test.js src/runtime/supervisor.test.js src/runtime/delegation.test.js src/runtime/runner.test.js src/runtime/runner.e2e.test.js src/runtime/skillChain.e2e.test.js src/runtime/donna-contract.test.js src/runtime/auth.test.js",
     "check-versions": "node scripts/check-versions.js",
     "prepack": "node scripts/check-versions.js",
     "prepublishOnly": "node scripts/check-versions.js",