@c4a/context-cli 0.7.5 → 0.7.9

package/providers/context/resources/manuals/guides/note.md

@@ -0,0 +1,43 @@
+---
+id: context.sdk.note
+kind: procedure
+mediaType: text/markdown
+---
+
+# Prepare a note source
+
+Read this before importing or correcting a note. The CLI saves supplied Markdown;
+source preparation happens before knowledge production.
+
+A note may contain supplied original text, selected verbatim excerpts, a summary,
+or a useful combination. Do not require raw text plus a summary for every note.
+If both exist, distinguish them with readable headings or prose. Preserve short
+original text when useful; do not duplicate it just to fill a form. Label an
+external or Agent summary as a summary, never an original transcript.
+
+For long inputs, retain relevant excerpts or summarize within the agreed purpose.
+Keep qualifications, exceptions, disagreement and unresolved questions that affect
+the conclusion. State the available origin and selected scope, including material
+omissions when consequential. Quote only actual verbatim input. Do not invent
+links, speakers, dates or confirmation. A link does not mean its target was read;
+ask about essential missing context rather than fetching everything for a label.
+
+Save the body under sources/note/YYYYMMDD/topic.md with the existing import action.
+No extra raw/summary fields, sidecar, duplicate file or mandatory section template
+is needed. Saving alone does not start indexing. Independent reader topics can
+use the selected Note Provider (default or business replacement); supporting
+explanations use the current page's evidence/read scope, retaining its primary.
+When specialized interpretation is needed, explicitly select a compatible
+extension layer. Do not enable another skill merely because a note exists.
+
+Knowledge integrates the useful information into explanations, rules or steps
+for the reader. Do not copy the note wholesale or turn proposals into facts.
+An exact short passage is appropriate when its wording matters. Cite the stored
+material actually read, without claiming access to an unavailable original.
+
+If the note misrepresents the supplied material, explicitly correct the source
+with its current base_digest, following task adjust first for pinned inputs.
+Do not overwrite original text merely to fit new prose. If the source is correct
+but the knowledge is misleading, revise only that page through Author/Review.
+A confirmed future decision may differ from current implementation; make the
+boundary clear. Knowledge approval does not change or remove the note.

package/providers/context/resources/manuals/guides/package-outputs.md

@@ -10,8 +10,10 @@ Package outputs are generated folders under `dist/`. They turn approved
 knowledge from `knowledge/` into a shape that another consumer can install,
 read, or import.
 
-Package output is a human decision gate. Do not add package declarations until
-the user chooses the intended consumer and output shape.
+Package output is a semantic decision: establish the intended consumer and output
+shape before declaring it. Reuse the user's existing choice. A current managed
+Route may delegate this decision to the Agent; it does not require a repeated
+permission question.
 
 Package build consumes approved and closed knowledge. If status reports that
 close is required, run deterministic close before build. Current close derives
@@ -19,11 +21,85 @@ close is required, run deterministic close before build. Current close derives
 final verify gate without rewriting approved Markdown. References, changelog,
 package index, and section fingerprint rebuilds are not current close output.
 
-## Recommended First Output: Agent Knowledge-Base Package
+## Default New-Workspace Outputs: Knowledge Base + Website
 
-Choose an agent knowledge-base package first when the knowledge should help
-Coding Agents work with the project. After the user chooses this semantic
-output shape, implement it with `kbPackage()`.
+Output channels support multiple selection. In a new workspace without explicit
+preferences, the Agent proposes and configures KB + website as the default. Honor
+user feedback, session authority and existing workspace declarations; LLMS is an
+additional selectable channel. This is an Agent configuration default, not an SDK
+change that silently enables websites for existing packages.
+
+### Static documentation website
+
+To include the default browser-readable site, enable `site` on the same
+package. The normal `context build` produces both the Agent KB and a standalone
+`dist/<base>-site/` directory containing `index.html`, article HTML,
+local search, scripts, styles and the selected bundled resources.
+
+`<base>` is the package name with one trailing `-kb` removed, when present.
+For example, `project-kb` produces `dist/project-kb/` and `dist/project-site/`;
+`project` produces `dist/project/` and `dist/project-site/`. Output directories
+must not collide with another package or website. `site.base` controls URL
+prefixes only, not filesystem output paths.
+
+```ts
+kbPackage({
+  name: "project-kb",
+  template: "src/package-templates/kb",
+  site: { title: "Project knowledge", lang: "en-US", base: "/" },
+});
+```
+
+`site` is opt-in; omission keeps the existing KB-only output. Optional fields
+are `title` (defaults to the package name), `description`, `lang` (defaults to
+`en-US`), and `base` (defaults to `/`; use `/docs/` when hosted under that path).
+The website uses a full-width VitePress theme with system fonts, compact navigation,
+a wide reading area and a smaller article outline. It starts in
+light mode regardless of the operating system; an explicit reader choice is
+remembered in browser storage. Search runs locally, without a search service.
+Mermaid renders in the browser with a restrained theme; invalid diagrams retain
+their source instead of blocking publication. Code samples and raw HTML are
+displayed as content, not executed as Vue components or scripts.
+
+The accepted `src/knowledge-map.yaml` controls sidebar organization. Entries
+bind to `artifact_ref` and optionally `section_key`; the builder resolves these
+against this package's selected approved articles. Navigation labels and parent
+groups do not determine website paths. One article may have several navigation
+placements while keeping one URL. Pending/excluded targets generate warnings
+and no invented link. Every selected article with an artifact identity must have
+a valid reading target before packaging, including packages without a website.
+Missing bindings or invalid section references block the staged output and
+return the missing article list plus a navigation-only task adjustment input.
+Category nodes can remain empty while future articles are planned. The builder
+does not infer business categories or alter article content.
+
+Top navigation contains the first-level reading directories. Selecting
+a section shows only its descendants in the left sidebar; opening an article
+directly selects its section. Skills and their Markdown references remain
+reachable as linked read-only pages, but have no automatically added navigation
+section. A reader-facing usage guide can link them where appropriate.
+Section landing pages have stable URLs separate from article URLs.
+
+`dist/<base>-site/context-site-map.json` records each article's approved path, KB path and
+site path, plus the projected menu and unresolved targets. URLs are derived from
+article identity; legacy pages without `artifact_ref` use their approved path,
+so moving those legacy files changes their URL. The shared knowledge map,
+KB layout and production Markdown remain unchanged.
+
+Article pages include a small source footer from recorded article source references and the source registry. Repository entries link to the recorded revision and module (or an explicitly referenced file); document entries link to their registered HTTP(S) URL. Unrecorded associations are not inferred from prose. Source-footer changes participate in the website build fingerprint without modifying knowledge Markdown.
+
+The website reuses resource delivery already performed for the KB: bundled
+resources are copied into the site's `resources/`; Git raw links remain remote,
+and explicit resource omission remains omission. It does not copy source trees
+or capture audits. Website generation completes in a sibling staging directory
+before either output is published, so a failed website build preserves the
+previous KB and website. The website is not included in the KB directory.
+Disabling the option removes the old site on the next successful package build.
+
+Preview through an HTTP static server. Deploy the **contents of `dist/<base>-site/`** using
+the user's chosen static hosting tool; no hosting SDK, login, deployment or
+platform-specific skill is part of Context's build. Keep hosting credentials
+out of package templates and published content.
 
 Typical output:
 
@@ -74,26 +150,29 @@ Do not ask for another distribution namespace. Older workspaces may still
 contain `distribution.knowledgeNamespace`; Context accepts that legacy input
 without using it to shape the package.
 
-Skill names are separate. Ask whether the author wants a short optional Skill
-prefix, then maintain the complete final template directory name directly—for
+Skill names are separate. If a short prefix is useful, maintain the complete
+final template directory name directly—for
 example `skills/android-query/SKILL.md`. Package-root layout never renames a
 Skill.
 
 The default `knowledge-query` Skill is a complete generic query entry. It
 carries the structure-first query discipline: start from OKF directory indexes, use
 `context-build-inventory.json` edge records for package-visible relationships,
-inspect page `sources` / `context:section` source_ref metadata, cite
-page/section evidence, and report explicit gaps when the package does not cover
-a requested fact. It does not treat direct grep over bundled OKF root
+read candidate pages, cite their visible headings and relevant passages, and
+report gaps when the package does not cover a requested fact. Consumer pages
+omit `sources` and `context:section` metadata. For exact upstream attribution,
+a maintainer needs the original workspace page mapped by the inventory; a
+package-only reader must not claim to have read that source. It does not treat direct grep over bundled OKF root
 directories as the primary discovery path. When indexes do not narrow the
 scope, or a candidate page is too large to read directly, its bundled
 `scripts/search.mjs` provides deterministic BM25 ranking over mechanically
 bounded Markdown chunks. Search results are leads; page bodies and typed edge
-records remain the evidence. Its final template-author section
-requires package authors to replace or edit the generic routing when the
-package needs project-specific terminology, entry points, known limits, or
-task workflows. Authors may explicitly accept the generic default when it is
-intentionally sufficient.
+records establish what the package actually says. Package authors edit the source
+template when project-specific terminology, entry points or task workflows are
+needed. Authoring instructions should be template comments or separate guidance,
+not a final section addressed to authors in the delivered query Skill. The
+current template-review Route can accept an intentionally sufficient generic
+default under its applicable authority.
 
 When approved pages reference materialized resources, Context keeps their
 production copies in content-addressed `knowledge/assets/` paths and bundles
@@ -168,7 +247,7 @@ It links directly to pages in small child directories and to a child
 The default threshold is 50 selected knowledge pages. Use Handlebars variables such as
 `knowledgeGroups`, `knowledgeItems`, and `knowledgeTree` when a project needs
 custom navigation. Before customizing it, read
-`node_modules/@c4a/context/docs/reference/template-variables.md`.
+[Template Variables](../reference/template-variables.md).
 
 Newly initialized generic templates must be replaced, edited, or explicitly
 accepted before the first build. `context status` exposes that choice as a
@@ -206,7 +285,9 @@ Typical output:
 
 ```text
 dist/<package-name>/
-└── llms.txt
+├── llms.txt                  # knowledge-map index
+├── llms-full.txt             # consolidated approved text
+└── llms/pages/<identity>.txt # individual approved articles
 ```
 
 Choose this when the user wants:
@@ -227,49 +308,139 @@ knowledge/
 └── ...
 ```
 
-## How To Ask The User
-
-When `workflow.current.reason_code` is `route.package.output-required`,
-explain the choices with the output tree. Do not ask the user to pick from
-unexplained labels.
-Use the host's native multi-choice tool when available. If unavailable, fall
-back to a short Markdown A/B/C question. The option labels should be:
-agent knowledge-base package, LLM text bundle, and skip package output for now.
-
-Recommended question shape:
+## Agent configuration and delivery recipe
+
+Use this guide when the user asks to generate a documentation website, selects
+outputs in the work-start report, or the current Route asks for package output.
+Read the current Route and existing `src/index.ts` first. Reuse settled choices;
+follow its configuration/read-acknowledgement contract rather than replaying a
+previous revision. The Agent edits SDK configuration; the user need not write code.
+
+1. Record all selected channels together. For new workspaces with no explicit
+   preference, use KB + website. Preserve existing declarations and explicit
+   KB-only, LLMS-only or deferred-delivery choices.
+2. Configure the existing KB declaration below, substituting the actual name,
+   title and workspace language. Retain its sources, phases, selection and resource
+   policy. This is one KB package with an additional website channel, not two KBs.
+3. If LLMS is selected, add its declaration and import in the same edit. Ensure
+   both template directories exist and resolve generic-template review using the
+   current Route. Do not independently ask approval for each already selected channel.
+4. Refresh `context status --format json`. Follow the returned continuation for
+   knowledge-map adjustment, required review, close, verification and build.
+   Missing article bindings require explicit targets from current CLI diagnostics;
+   do not classify articles from `wikis/` or `codeindex/` directory names alone.
+5. Run `context build` when ready. Verify each selected output and report its
+   actual location; a failed selected website is not completed delivery.
+6. Preview the generated website directory through a local HTTP server. Verify HTTP succeeds
+   before giving its URL. Publishing requires the user's chosen hosting tool and
+   authorization; do not install a hosting SDK merely to build the website.
 
-```text
-The reviewed knowledge is approved. The next decision is how to package it.
-
-Recommended: agent knowledge-base package
-dist/<name>-kb/
-├── AGENTS.md
-├── skills/knowledge-query/SKILL.md
-└── wikis/
-    ├── index.md
-    ├── <group-page>.md
-    └── <large-group>/index.md
-
-This is best if agents should use the knowledge as a reusable knowledge base.
-
-Alternative: LLM text bundle
-dist/<name>-llms/
-└── llms.txt
-
-This is best if you need one text bundle for model/RAG import.
-
-We can also skip package output for now and keep only knowledge/.
-
-Which one should I declare first?
+```ts
+import { defineProject, kbPackage, llmsPackage } from "@c4a/context";
+
+// Edit only the packages field of the existing defineProject declaration.
+// Keep the actual project's other declarations intact.
+const packages = [
+  kbPackage({
+    name: "project-kb",
+    template: "src/package-templates/kb",
+    site: { title: "Project knowledge", lang: "en-US", base: "/" },
+  }),
+  // Include this entry only when LLMS text is selected.
+  llmsPackage({ name: "project-llms", template: "src/package-templates/llms" }),
+];
+// Existing defineProject({ ...existing declarations, packages }).
 ```
 
-If the user chooses the Agent knowledge-base package, explain that its OKF
-roots are flat within `dist/<package-name>/`; do not ask for a second namespace.
-Ask whether its Skills need a short prefix. The author maintains final Skill
-names independently from package paths.
+The configuration is a small source edit, not custom frontend implementation.
+Website output reuses approved articles, knowledge map and packaged assets;
+rendering/search generation adds build time and size, not another indexing pass.
+Measure actual cost instead of quoting a universal estimate.
+
+| User request | Agent action |
+| --- | --- |
+| KB + website | One `kbPackage` with `site` enabled |
+| KB only / disable website | Omit `site` on that KB and rebuild; old site output is removed |
+| Add website later | Add `site` to existing KB, repair missing reading bindings, rebuild |
+| Website only for distribution | Explain the KB is still built; share only the sibling website directory |
+| Also produce LLMS | Add `llmsPackage` alongside the KB in the same change |
+| Keep current knowledge only | Postpone packaging; do not label it completed package delivery |
+
+```sh
+python3 -m http.server 8000 --bind 127.0.0.1 --directory dist/project-site
+```
 
-Do not offer `both` as a shortcut. If the user wants multiple outputs, add one
-package first, verify the shape, then add another package after confirmation.
-The default adaptive index policy avoids one-page directory indexes. Configure
-`kbPackage().navigation` when a package needs a different inline-entry
-threshold or a fully expanded index at every directory.
+The completion report lists KB root, website directory and LLMS file separately,
+with generated/failed/not-selected status. Include website navigation coverage,
+verified preview URL when running, and any remaining errors. The website contains
+source cards and article update times; it does not imply an article history browser.
+
+## How To Present The Choice
+
+Include a compact multi-select list in the work-start report, and reuse it later:
+
+- [x] Agent knowledge-base package — default for a new workspace.
+- [x] Documentation website — default with the KB, local preview or later hosting.
+- [ ] LLMS text — optional model-context or RAG input.
+
+Explicit choices override defaults. When current Route authority requires a user
+decision, ask once for the combination rather than a sequence of mutually exclusive
+questions. If the host tool supports only single selection, let the user state the
+combination in text instead of presenting it as multi-select. There is no `both`
+factory, separate website skill, or second permission per selected output.
+
+## Website deployment handoff after every successful build
+
+After every successful website build, including intermediate delivery and an
+unchanged output reused by build, tell the user the website can be deployed with
+a deployment skill. Include the actual `dist/<base>-site/` directory and whether
+it contains only the currently delivered scope. This notice does not wait for the
+whole knowledge task to finish and does not block its next Route.
+
+Reuse existing publishing configuration and the user's chosen target. Otherwise,
+inspect the available deployment skills, recommend a compatible static-site skill,
+or let the user specify one. Do not invent installed skills or a deployed URL.
+If no compatible skill is available, report that and provide the site directory
+for the user's deployment tool. Do not install a deployment dependency by default.
+
+When publishing is already authorized for that target, follow the selected skill
+with the built site directory; otherwise offer deployment and wait for the user's
+publishing instruction. Preserve the configured base path; rebuild if the target
+requires a different base. Pass only the website output, not sources, private
+workspace state or the entire KB package. Report success only after checking the
+hosting result and published URL. A failed deployment leaves the local build valid;
+report the deployment failure and its next step separately.
+
+
+### Persistent knowledge map and report proposals
+
+`src/knowledge-map.yaml` is the persistent knowledge map; retain it after delivery.
+Its protocol is `context.knowledge-map/v1`; structure and adjustment inputs use
+`knowledge_map`, and SDK functions use `KnowledgeMap` naming. It organizes website
+navigation and LLMS without changing article identities or section bindings.
+
+The work-start report explains the proposed directory and chapters, followed by
+a text wireframe of the website. Material changes are communicated with the updated
+report link and a short explanation. This does not build a temporary website or
+create a persistent article-plan file. Website packaging uses the accepted knowledge map
+and approved articles; the report is not a configuration input.
+
+### Website LLM Docs
+
+Every website build also builds LLMS from the same selected approved articles and
+knowledge map. The final top-navigation item is always **LLM Docs**, opening
+`llms/index.html`. This page links to `llms.txt`, the structured index,
+`llms-full.txt`, the complete approved text, and raw Markdown text articles under
+`llms/pages/`. These files ship inside the sibling website directory and use the configured site base.
+No separate LLMS package declaration or additional build command is required.
+Website LLMS text files include a UTF-8 BOM so browsers can identify the encoding
+when a static host omits the charset. Hosting should serve them as
+`text/plain; charset=utf-8`. The HTML landing page shows one index/full-text
+toolbar followed by the knowledge map; Changelog is available in the site navbar.
+
+The index preserves knowledge-map grouping, order and repeated placements. The
+full text includes each selected article only once, in first-placement order.
+Only approved selected content is exported. A map or article change invalidates
+both website and LLMS outputs; failure preserves the previous staged package.
+Standalone `llmsPackage()` uses the same map organization and supplies the full
+text and raw article files alongside its template-rendered `llms.txt` index.

package/providers/context/resources/manuals/guides/sessions.md

@@ -0,0 +1,56 @@
+---
+id: context.sdk.sessions
+kind: procedure
+mediaType: text/markdown
+---
+
+# Prepare a conversation-summary source
+
+Use sessions for a bounded summary formed from an authorized conversation:
+requirements, design, troubleshooting, operational or general knowledge.
+Code association is optional. An Agent or external supplier prepares the summary
+before import. Do not scan host history, ingest the full transcript, invent a
+conversation from a diff, or move an unrelated conversation into note merely
+because it lacks a commit.
+
+Keep the problem, confirmed decisions, useful reasons, constraints and open
+questions. Remove repetitive turns, tool logs and abandoned attempts unless they
+explain a current limit. Preserve whether each statement was proposed, agreed,
+implemented or verified. If only a supplied summary is available, say so; do not
+claim to have read the original. Do not make up speakers, dates or approval.
+A session with no reusable information can remain outside the workspace.
+
+Save through `context source import --input <file> --format json`, using
+`type: sessions`, `name: YYYYMMDD/topic.md` and the prepared `markdown` string.
+Choose the actual conversation date, or collection date if unknown, and retain
+the same path for corrections. The summary needs no mandatory body headings.
+
+Optional `changes` associates one or several code changes. Each row accepts
+`commit` (full 40/64 hexadecimal Git SHA), `mr` (HTTP(S) MR/PR URL), and optional
+`repository`. At least commit or mr is needed per row; omit the entire field
+for unrelated sessions. Use actual known identifiers, never fabricated hashes.
+A reference does not prove merge, deployment, tests or authorize fetching code.
+The CLI stores this field in the source's YAML frontmatter, discovers it from
+that same file, and does not introduce a sidecar or separate registry.
+
+For example, an import may have `changes: [{mr: "https://git.example.org/team/project/merge_requests/42"}]`.
+This is an illustrative URL, not a lookup target. The same payload without
+changes imports an independent requirements discussion normally. Use the current
+base_digest to change text or associations; explicit `changes: []` clears the
+associations. Omission leaves the source's inline changes intact. When replacing
+only the summary body, preserve existing associations unless explicitly removed.
+Do not duplicate commit/MR fields into knowledge frontmatter.
+
+Saving alone does not start indexing. Select a compatible Sessions Provider for
+an independent reader topic, or keep an existing page's Code/Markdown primary
+and include the summary in its authorized evidence/read scope. If specialized
+interpretation is needed, explicitly select an extension from the Sessions or
+business Provider. Knowledge turns useful conclusions into answers, explanations
+and procedures, not a meeting recap. Existing structure.yaml source references
+connect each relevant page/section to the saved summary and its optional changes.
+
+Correct a faulty summary through source import with current base_digest and task
+adjustment for pinned inputs. If the summary is accurate but the page is wrong,
+revise the approved page. A new topic goes through structure review then normal
+Author/Review. Neither knowledge approval nor source storage approves an upstream
+change. A failed update retains source and approved knowledge for recovery.

package/providers/context/resources/manuals/guides/workspace-commit.md

@@ -0,0 +1,51 @@
+---
+id: context.sdk.workspace-commit
+kind: procedure
+mediaType: text/markdown
+---
+
+# Commit workspace results
+
+Use Host Git tools, not an invented Context commit command. Commit only when
+the user requests it; fully managed production does not itself authorize Git
+commits or pushes. At the end of the entire requested production scope, after
+close and all requested builds with no pending tasks, a single optional commit
+suggestion is enough. Intermediate delivery is not that endpoint.
+
+## Select the files
+
+Locate the Context workspace and its actual Git root. Inspect status, staged
+changes, unstaged changes, untracked files and ignore rules. In an embedded
+workspace the Git root may be a much larger source repository. Explicitly select
+workspace files; never run blanket `git add -A` or commit the entire staged index.
+Check source records for required recovery information; a commit does not bundle
+ignored checkouts or runtime progress. Do not force-add ignored files or assume
+`dist` belongs in Git. Generated files are included only if the project's rules
+and selected scope require them.
+
+If there is no Git repository, establish the intended repository location before
+initializing one. If nothing changed, report that no commit is necessary. If the
+user asks for an intermediate snapshot, explain which saved files it contains
+and that it cannot resume ignored Author state from Git alone.
+
+## Commit the selected change
+
+Summarize the actual change and choose a message consistent with repository rules.
+Use precise paths and Git's scoped commit facilities or a carefully isolated
+index. `git commit --only -- <paths>` can exclude unrelated staged files; new files
+must first be known to the index. Inspect overlapping partially staged files
+before selecting this approach: do not silently include changes the user did
+not select. Preserve unrelated staged entries, including staged deletions.
+
+Git identity, hooks, signing, conflicts and permissions are environmental
+issues for the Agent to diagnose. Do not disable hooks or signing, rewrite global
+Git configuration, stash other work or bypass ignore rules to force success.
+Use an available authorized alternative or report the specific blocker.
+
+## Verify the result
+
+Read the actual commit SHA and its changed files/diff; compare against the
+selected scope. Verify unrelated worktree and index content remain unchanged.
+If a hook changed the result, inspect and report it before claiming completion.
+Report the SHA and a brief description. Do not push, publish or create a remote
+repository without the corresponding explicit request.

package/providers/context/resources/manuals/guides/workspace-prepare.md

@@ -0,0 +1,78 @@
+---
+id: context.sdk.workspace-prepare
+kind: procedure
+mediaType: text/markdown
+---
+
+# Prepare a workspace for the next task
+
+Use only for an explicit workspace preparation request. The goal is usable
+registered sources and no unfinished task, while retaining approved knowledge
+and configuration. Lead with Host tools and actual observations; do not start
+indexing merely because a status response offers production work.
+
+## Establish the scope
+
+Use `context entry` to locate the workspace. Inspect current work, active
+processes, Git changes and source registrations. Explain which unfinished
+drafts and queued maintenance will be discarded. Reuse the user's explicit
+authorization; ask only about an unresolved loss, version or access boundary.
+Wait for an active writer to finish and obtain its receipt before changing state.
+If status is broken, inspect its diagnostic and files with Host tools rather
+than treating failure as proof that the workspace is empty.
+
+## End the old task
+
+Run `context task prepare --format json`. It previews the exact Context-owned
+task files, including production, Review and maintenance state. It preserves
+approved pages, source records and snapshots, project configuration, repository
+checkouts, other `.tmp` files and existing outputs. It does not claim the output
+or sources are current.
+
+Once discarding the shown scope is authorized, execute the returned apply
+command with its plan digest. If the preview changes, inspect the new differences.
+On interruption, rerun the preview and use its resume command; never clear a
+transaction journal or repeat old Author submissions. Other incomplete writes
+must be recovered before cleanup. The completion clears task state only; check
+sources next. Do not manually delete the runtime directory to emulate this action.
+
+Other caches are optional cleanup, not a requirement to empty `.tmp`. Inspect
+their ownership and recoverability before deleting them with Host tools. Keep
+reports, unique material, unknown files and modified checkouts unless their
+specific loss is authorized. Do not delete locks, transaction records or active
+tool directories. Empty task directories can remain.
+
+## Restore usable sources
+
+For repositories, run `context source recovery-plan --format json` and read
+the installed repository recovery procedure and schema supplied by entry's
+workflow bundle: `repository-source-recovery.md` beside this guide and
+`../../schemas/repository-source-recovery.schema.json`. Reuse a matching local
+checkout or, when authorized, clone into a bounded location using
+`context source restore --input <workspace-input-file> --format json`.
+Group modules sharing a remote and fixed commit; do not clone per module.
+Check registered commit and module paths. Never reset a supplied dirty checkout.
+Authentication or checkout problems can be diagnosed with Host Git tools;
+refresh the recovery plan after fixing them. Do not substitute a newer commit.
+
+For Lark, inspect the stored body and required attachments against the source
+records. Use the Host's document tools and the [existing capture guide](knowledge-updates.md)
+to repair missing material, retaining the registered identity. A current remote
+response is not proof of an older snapshot: if it differs, explain that source
+updating is needed and resolve that choice before claiming recovery. If an old
+snapshot is unavailable, report the exact limitation. Do not automatically
+follow every document link or reread already complete materials.
+
+For note, sessions and local files, preserve formal source content and verify
+that declared paths can be read. Do not reconstruct lost original sources from
+generated knowledge or scan arbitrary local directories.
+
+## Finish
+
+Verify that no task files remain in the preparation preview, no writer remains,
+the required configuration can load, and selected sources resolve to their
+registered versions and paths. CLI inspection or direct Host checks are both
+valid; a failed check is not ready. Report outstanding blockers and their next
+action. Stop when ready for the next user request, without running Author or
+recapturing everything. Historical restoration may additionally require a
+close/build; see [restore a version](workspace-restore.md).

package/providers/context/resources/manuals/guides/workspace-restore.md

@@ -0,0 +1,65 @@
+---
+id: context.sdk.workspace-restore
+kind: procedure
+mediaType: text/markdown
+---
+
+# Restore a historical workspace version
+
+Use the Agent's Git and environment tools. This restores selected workspace
+files and usable sources; it does not reset the entire repository, rewind source
+repositories, or restore ignored runtime progress.
+
+## Resolve the target
+
+Locate the workspace and Git root, then inspect history for that workspace path.
+With no explicit target, select the most recent commit saving its state to undo
+uncommitted results. “Previous version” instead selects the preceding relevant
+saved state, not mechanically `HEAD~1` of a large repository. Validate an explicit
+SHA. For dates, use the user's timezone and actual meaning (for example, as of
+end of that day), inspect candidate history and resolve ambiguity with the user.
+Git history can be nonlinear; do not choose an unrelated branch by timestamp.
+The final target is a concrete SHA and path scope, never a date string alone.
+
+Compare target files with current tracked, untracked and staged files. Include
+current additions absent at the target in the proposed removal scope. Keep
+unrelated files, existing staged work and ignored source checkouts. Account for
+workspace moves or renames instead of treating a missing old path as an empty
+version. Reuse explicit authorization; ask when the target or loss is unresolved.
+
+## Restore files and environment
+
+Wait for active Context writers and obtain their result. Use the task-state
+preview/apply from [workspace preparation](workspace-prepare.md) to abandon the
+authorized old work before restoring files; it also clears pending maintenance.
+Do not use an old Route after restoration.
+
+Use Git to restore only the agreed paths from the selected SHA. A scoped
+`git restore --source=<sha> --worktree -- <paths>` preserves branch history;
+decide separately how authorized overlapping staged changes should be handled.
+Use explicit deletion for agreed additions absent at the target. Never use a
+whole-repository `reset --hard` or `clean -fdx` as a workspace shortcut.
+
+Use the restored source records with the preparation guide to restore pinned
+repository versions, module paths, document snapshots and attachments. New remote
+content cannot stand in for lost old snapshots. Do not reclone usable sources.
+On interruption, inspect the actual file diff and remaining source gaps and
+continue those operations; do not assume the previous Git command completed or
+replay old task submissions.
+
+Old build output does not describe the restored version. If output is requested,
+follow the current close/build or approved-output rebuild capability from the
+[knowledge update guide](knowledge-updates.md); do not start full indexing merely
+because the restored source configuration is available. Until rebuilt, state
+that existing output is stale. If the historical schema is incompatible, diagnose
+the available migration or tool-version choice, report necessary adaptations,
+and do not pretend incompatible content is current or silently rewrite all pages.
+
+## Verify and stop
+
+Compare the selected files with the target commit, identify any agreed adaptations,
+verify unrelated changes/index entries survived, and check source readiness and
+absence of old task state. When building was requested, check the new output as
+well. If only some sources could be restored, report partial completion with the
+specific missing access or version. No automatic commit, branch rewrite or push;
+the user may separately [commit the restored results](workspace-commit.md).