@c4a/context 0.7.5 → 0.7.8

package/docs/guides/knowledge-updates.md

@@ -0,0 +1,324 @@
+# Update existing knowledge
+
+Use the same Context conversation and the current workspace. Identify whether
+this is a continuation, an adjustment to the current task, a correction to one
+page, or an independent task. An old Route does not incorporate a new request.
+For explicit workspace preparation, Git commit or historical restoration, use
+[prepare](workspace-prepare.md), [commit](workspace-commit.md) or
+[restore](workspace-restore.md); these Agent-led operations do not automatically
+start production. Otherwise, do not start an independent task while another remains: explain what is saved
+and unfinished, and obtain the user's choice to finish or roll back the current
+work. Do not delete runtime files to simulate rollback.
+
+For an unambiguous page correction, use `context revise "<path or title>"
+--instruction "<correction>" --format json`. Context supplies the existing text
+and continues through Review and delivery. Expression-only changes need no
+source capture or Parser. Preserve prior confirmed contributions; distinguish
+actual behavior, a confirmed decision, and a proposal that is not implemented.
+
+## Edit one section or review part of a batch
+
+For a reading-directory-only change, use the existing `context task adjust
+--input <file|-> --format json` action with `reading_structure`. Supply its
+current `expected_revision`, explicit `upsert` entries and `remove` keys. Each
+entry retains its stable key, parent, title and order; optional targets use
+article identity and section key. The current structure preview supplies those
+identities. Use `expected_revision: null` only when no reading structure exists.
+After adjustment, follow status to rebuild affected packages. This changes the
+reading organization without capturing sources or rewriting approved prose.
+Do not directly edit generated package navigation or use titles as identities.
+
+The current approved-revision Route accepts either full `markdown` or explicit
+`sections` edits. Use an existing `writing_context.current_sections` ID and an
+ordered `content` list of `{ "markdown": "new text" }` and/or
+`{ "program": "exact current program token" }`. Unchanged sections and the
+selected section's source references remain intact. Use full Markdown when
+changing structure, adding a page or when a section has no unambiguous ID.
+
+For an optional check, append `--preview` to the current `action complete-current`
+command with the same revision and input file. It validates and returns the
+assembled page and previous text without accepting the edit. Submit the same
+input without that flag to continue. A preview is not approval and does not make
+a stale revision valid.
+
+Review can approve checked pages while leaving repair pages pending. The HTML
+review code includes pending positions; managed Review provides the same current
+scope as a JSON template. Send decisions only for pages actually reviewed. Omit
+means a durable exclusion, not repair. Partial approval alone does not build.
+
+When the user requests an earlier delivery, use the Route's `context run
+--deliver` request. Independently approved pages can pass close/build while
+pending candidates remain for Review or repair. Links to pending or missing
+pages keep their necessary scope together. Source processing baselines advance
+only after the entire update finishes. Failed builds retain the selected delivery
+and pending work; repair the cause and follow the current Route.
+
+## Acquire the selected change once
+
+Use the host's existing Git, code-hosting or document tools and their installed
+guidance. Context does not poll a platform, discover remote changes, or infer
+that a merge request is merged. Reading an already selected source does not
+require a new permission question when access was already authorized. Do not
+change the user's checkout or fetch another repository without that scope.
+
+For a branch or MR/PR, establish the repository, intended target branch, merge
+state and actual fixed target commit. An unmerged proposal is not the current
+mainline. A merge, squash or rebase can produce different commit identities;
+use the target branch's actual result, not the feature branch SHA. Include
+other intervening changes between the last processed version and the selected
+target when they affect the registered modules. Reverts are real changes.
+
+Use already available local Git objects to compare the selected module trees
+and necessary diffs. A new repository commit with unchanged module trees can
+be a no-knowledge-change conclusion. That conclusion must also account for any
+new note or development context. If a baseline is unavailable after force push,
+a shallow checkout or history cleanup, state that a complete old diff is
+unavailable; compare current material with approved knowledge in the confirmed
+scope. Do not claim no change because a Git command failed. A repeated MR may
+still bring new relevant context; it does not justify moving the code baseline
+backwards or summarizing unrelated commits as part of that MR.
+
+For documents, a revision shortcut is valid only if the host actually exposes a
+reliable version for the selected document and its needed images/attachments.
+Otherwise read that selected document and resources. Keep the returned bytes
+for the existing capture/import action; do not fetch them again as verification.
+An unchanged body does not prove images are unchanged. Distinguish lack of
+permission, deleted content, and moved content; a read failure is not permission
+to retire a knowledge page. CLI status describes local acquisition only.
+
+After the current source configuration and material identify the chosen fixed
+versions, submit the update with `context update --input <file|-> --format json`.
+Write ordinary YAML or JSON with the host's editor, without a generated wrapper
+program. Input files belong under this workspace's `.tmp/`.
+
+```yaml
+scopes:
+  - requirement_ref: reader-guide
+    source_ref: repo:20260901/library
+changes: The selected change adds one public option; inspect its explanation and examples.
+```
+
+`requirement_ref` is the existing requirement id. Omit `module_refs` for a whole
+confirmed source scope. `processed_version` may be supplied to bind the exact
+acquired commit or document content digest; otherwise Context captures it from
+the existing local material. A supplied version must match that material.
+Follow the returned Route. The candidate list is a conservative source match,
+not a list of pages that must change. Read the actual change and current pages,
+also checking additions that have no old page reference. The scope is complete
+only after every required change is reviewed, closed and built, or after an
+explicit conclusion that it needs no knowledge changes.
+
+Before importing a `note`, read [note source preparation](note.md).
+Before importing `sessions`, read [development summary preparation](sessions.md).
+Choose the reference for the actual input; do not read both by default.
+
+## Save text without an external file
+
+Use `context source import --input <file|-> --format json`:
+
+```yaml
+type: note
+name: 20260907/decision-context.md
+markdown: |
+  # Decision context
+
+  The selected discussion confirmed this exception for the stated situation.
+  The implementation has not yet changed. Source: the discussion supplied here.
+```
+
+The body is saved directly under `sources/note/` or `sources/sessions/`; no
+external `local`, capture, registry or second copy is required. Use a readable
+semantic filename under an eight-digit date directory. Do not put a date, hash
+or session id into the filename again. Keep the path for retries and later
+edits. To revise an existing source, read it and pass its current `base_digest`
+with the replacement Markdown. Distinct same-day material needs a distinct
+semantic name, never a silent overwrite. `source list`, `source get` and
+`source inspect` expose the actual source paths. Removal uses the existing
+preview and exact plan digest, and refuses still-referenced text.
+
+Saving alone does not start indexing. If the user only wants the source saved,
+report its path and stop. For production, reuse the existing requirement:
+put independent content in `target_scope`; put supporting material in
+`evidence_source_scope` and ensure the selected Indexer's existing `read_scope`
+covers it. Do not create a separate Markdown production target for a supporting
+explanation of a code page. In the source-update decision, include its exact
+`supporting_sources` on the affected page. Include that source's scope in this
+update so completion can distinguish code from newly processed context.
+
+## Development context accompanying a commit
+
+Use `trace-session` only as this conditional source-preparation step. If the MR,
+code and existing design already explain the relevant information, cite them.
+Write a `sessions` source only when real, explicitly available development
+context contains useful decisions, reasons or limits missing from those sources.
+Do not fabricate discussion from a diff, search host session storage, ask for
+nonessential history, or create an empty/skip report. This is only the code-related subcase. An authorized conversation summary
+without an MR or commit is also `sessions`; see the sessions source guide.
+Optional `changes` belongs in the source frontmatter, not knowledge headers.
+
+Use the available merge date, or commit date for a pure commit, for the initial
+directory; if unavailable or saving an unmerged discussion explicitly, use the
+current collection date and explain the context. Do not query a platform just
+for this date. Keep the path when later adding a reference or retrying another
+day. One coherent change can share one summary; separate unrelated changes.
+
+The shortest useful body is the real repository/MR/commit reference plus one
+paragraph explaining what the code does not tell a later reader. Describe only
+the actually associated commit subset. Omit a full change recap, transcript,
+test log, session id and formal approval claim. Write confirmed decisions as
+such, alternatives as alternatives, and unresolved proposals as unresolved.
+Do not claim execution or tests that were not observed. The writing aid below
+is optional; no section is mandatory:
+
+```markdown
+# <Change topic>
+
+<Reference the actual repository and MR or concrete commits already available.>
+
+<Explain the useful decision, reason or constraint absent from the code/design.
+State its applicability and distinguish implemented behavior from a proposal.>
+```
+
+Late context can update a page even when the code version is already processed.
+Reuse that fixed code version and current approved prose; do not restart Parser
+merely because a summary arrived. Import once, then include the necessary
+context with the same knowledge update. Saved context survives a failed build;
+saving it does not mean its knowledge impact has been delivered.
+
+## Optional correction of an upstream document
+
+Local knowledge approval and fully managed execution do not authorize a remote
+write. First determine whether the knowledge misunderstood correct source text,
+a confirmed decision has not reached the source, or the conclusion is still
+uncertain. The first needs only a local correction; the second can use a note
+locally while an upstream change is considered; uncertainty is not a fact.
+
+Present the exact document, affected passage, proposed before/after text, reason
+and affected knowledge. Reuse existing authorization for that concrete edit;
+otherwise ask for it. Before writing, read the affected passage again using the
+host document tool. Adapt only within the authorized scope if another person
+has edited it; ask again only when the requested change materially differs.
+
+Execute with the host tool and read back the result. If the write result is
+uncertain, read back before retrying an insertion. Only the actual returned
+source text and resources may refresh its snapshot. Feed them into the same
+local capture/update route; a note or proposed patch is not a remote snapshot.
+If the remote edit succeeded but local build failed, resume local delivery;
+do not repeat the remote edit. Explain remote and local outcomes separately.
+Do not automatically delete an absorbed note, post comments, notify groups or
+change permissions. Permission failure can leave a concrete suggestion for
+the user without blocking an independently supported local correction.
+
+## Import a document response already read by the host
+
+For a registered Lark source, retain the actual full JSON response from
+`lark-cli docs +fetch` and each returned continuation page. Do not reconstruct a
+response from a summary. Use the same source import command:
+
+```yaml
+type: lark
+name: 20260907/guide
+access_identity: user
+response_files: [.tmp/guide-response.json]
+media_files:
+  actual-image-token: .tmp/downloaded-image.png
+```
+
+Only include real media tokens and downloaded files. Context runs the ordinary
+capture normalization and resource checks on these bytes. It does not fetch the
+provided document again; missing required resources follow existing capture
+handling. Partial outline/section fragments cannot replace a full snapshot.
+Use the identity that actually produced the response, not a credential fallback
+chosen to bypass permissions. Subsequent local updates use the captured version
+and the same Review/build route.
+
+## Adjust or roll back current work
+
+For an explicit same-task change to native Indexer source inputs, use
+`context task adjust --input <file|-> --format json` with `scopes` containing the
+selected `source_ref` and optional `module_refs`, plus an `instruction` explaining
+the adjustment. It invalidates those old worksets and retains independent work.
+Import the fixed replacement material before following the refreshed Route.
+Do not execute the old batch payload. A local page correction still uses
+`revise`; it is not a reason to invalidate an entire source.
+
+For an independent task, complete the old Route unless the user chooses a
+concrete rollback. Without an identifiable baseline or attribution of changes,
+ask about that gap or offer completion; never guess original bytes. Prepare
+`context task rollback --input <file|-> --format json` using:
+
+```yaml
+summary: Restore the selected page and discard unfinished follow-up drafts; keep other work.
+discard_unfinished: true
+files:
+  - path: knowledge/guides/selected-page.md
+    base_digest: sha256:<current-file-digest>
+    content: |
+      <exact recoverable original Markdown, not a newly generated replacement>
+```
+
+`files` contains only the explicitly selected reversions. `content: null` removes
+an explicitly selected file that this task added; `base_digest: null` is for
+restoring an absent file. Include changed sources/configuration/processed scopes
+when they belong to the rollback. Leave unrelated and pre-existing edits alone.
+An empty list only discards unfinished work and must not be described as undoing
+already delivered pages. The preview shows actual before/after contents and
+draft loss. Once the user approves that exact scope, run the preview's apply
+command with its plan digest. Then follow the rollback Route through close,
+build and cleanup. A failed build retries delivery, not the already-applied
+reversions. Begin the independent task only after cleanup succeeds.
+
+A managed source can be explicitly renamed with `context source rename
+"<note:... or sessions:...>" --name "YYYYMMDD/new-name.md" --format json` after
+its active work is finished. Review the file/reference changes, then apply the
+returned digest-bound command. Existing references move with it; the original
+body is not copied into another source type. Follow status to refresh affected
+knowledge structure and packages.
+
+To move an approved page, use `context revise "<old path>" --move-to "<new path>"
+--instruction "<requested move and content changes>" --format json`. The new
+path stays in the same collection. The revision retains the page identity,
+rebases outgoing links and updates incoming Markdown links at approval. A new
+subject name alone only needs a title/content revision; do not create duplicate
+pages. Retirement is a content decision: explain the inapplicable material and
+supported replacement before changing its page and referring navigation.
+
+### Adjust inputs while a local update is unfinished
+
+`context task adjust --input <file> --format json` also applies to an active
+approved-page revision or source-update queue. Keep `scopes` and `instruction`
+explicit. First call without `refresh`; it authorizes replacing only those
+inputs and blocks page completion while acquisition is pending. Import the
+selected new material, then repeat with `refresh: true` to bind the actual local
+versions and obtain the new Route. Do not submit the old revision. Current
+prose and queued pages remain; an affected draft returns to writing/review.
+An unrelated queued page does not revoke an unchanged current page's review.
+If a page has already been applied, finish its close/build before changing its
+inputs. Only the final completed scope advances its processed baseline.
+
+For several documents, `source import` also accepts a JSON/YAML array of the same
+single-document inputs. Its receipt reports each zero-based input index and
+success or error separately; a partial batch returns a nonzero exit code.
+Keep successful sources and retry only failed entries. It does not fetch a
+successful prefetched document again or roll back an unrelated saved note.
+
+To add a new supporting source to an unfinished local revision, first save it
+and include it in the current requirement's evidence scope and the selected
+Indexer's read scope. Its `task adjust` scope also supplies the explicit
+`requirement_ref`. This extends the current page's available sources and keeps
+queued pages; it does not silently start another task or another Indexer.
+
+### Replacing supporting article identities
+
+When an upstream article is split, merged or removed, start `context revise` for
+its consumer and use `context task adjust --input - --format json` with
+`instruction` and `knowledge_dependencies: { dependencies }`. Each dependency
+uses an approved `artifact_ref`, optional `section_refs`, and `required` flag.
+The current Author input returns authorized replacement facts and their evidence.
+Repeat the adjustment with `knowledge_dependencies.sections`, selecting each
+retained `section_key` and its full `fact_refs` and `evidence_refs` support. Then
+revise the explanation and complete normal Review, close and build. An explicit
+empty dependency list removes the relationship only when remaining sections have
+valid direct support. Missing dependencies, changed approvals and invalid source
+references cannot silently become current evidence. Writing quality remains an
+Agent/Review decision; no chapter-count or wording gate is introduced.

package/docs/guides/lark-resources.md

@@ -2,7 +2,11 @@
 
 Lark documents can contain evidence that is not present in the readable text
 body. Context handles these resources mechanically during `captureLark`; the
-Agent does not download, summarize, or reconstruct them itself.
+Agent does not reconstruct resource bytes or substitute a summary for them.
+When the host already fetched the document, `context source import` accepts the
+actual full response files and downloaded media for the same normalization and
+resource checks; it does not fetch that supplied body again. See
+[importing an existing response](knowledge-updates.md#import-a-document-response-already-read-by-the-host).
 
 ## Resource policy
 

package/docs/guides/markdown-indexer-skill-authoring.md

@@ -5,7 +5,12 @@ versioning, Bundle, requirement, trust, Result and customization contracts as
 Code Providers. Read the shared
 [Code Indexer author checklist](./code-indexer-skill-authoring.md) and
 [Provider selection/customization guide](./indexer-provider-and-customization.md)
-first. This page defines the Markdown-specific boundary.
+first. This page defines the boundary for captured file/Lark documents.
+Saved notes and conversation summaries use their dedicated Note/Sessions
+Providers, or an explicitly selected business replacement, on the same protocol.
+They reuse Markdown reading without a second capture phase. A Markdown page may
+still consume either as authorized supporting material; specialized extension
+guidance does not transfer primary ownership.
 
 ## Capture before semantics
 
@@ -41,8 +46,10 @@ Author Results propose logical Sections and their intent; they do not write
 
 Context owns the closed mapping from profile/Section intent to collection and
 path. The layout resolver reuses an existing Artifact by stable identity,
-detects add/remove/rename/split/merge/move changes and requests a human Gate
-only for destructive or ambiguous existing-layout changes. A Provider cannot
+detects add/remove/rename/split/merge/move changes. Ordinary production reviews
+the proposed new structure before Author, including new topics in an update.
+Protected changes to an approved layout have their own human-only Gate; this
+is distinct from ordinary structure review and its managed delegation. A Provider cannot
 avoid that Gate by emitting a path or relabeling the change.
 
 ## Reusing Code Nodes
@@ -77,10 +84,12 @@ collection-wide recomputation.
 
 Editorial instructions may guide clarity, consolidation, ordering and
 reader-facing terminology. They cannot alter facts, evidence, source role,
-requirement scope, protected values, revision identity, collection authority or
-hard metrics. Deterministic blocks render only registered facts; semantic prose
-must cite consumed evidence. Placeholders, speculation, fabricated transitions
-and “content unavailable” pages are invalid even when the structure looks rich.
+requirement scope, protected values, revision identity or collection authority.
+Deterministic blocks render only registered facts; semantic prose cites consumed
+evidence. The Agent or user assesses missing explanations, speculation and
+unfilled placeholders in the existing content Review. Context does not scan
+words, braces, comments or headings to reject content, and an editorial hint
+does not create another gate or require a signal-clearing receipt.
 
 ## Missing material
 

package/docs/guides/note.md

@@ -0,0 +1,37 @@
+# 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/docs/guides/package-outputs.md

@@ -4,8 +4,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
@@ -68,26 +70,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
@@ -162,7 +167,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
@@ -259,11 +264,11 @@ Which one should I declare first?
 
 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.
+If its Skills need a short prefix, the author maintains those final names
+independently from package paths; this is not a mandatory question.
 
-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.
+If the user requests multiple outputs, declare and verify each requested package.
+There is no additional confirmation just because two outputs were already chosen.
 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.

package/docs/guides/sessions.md

@@ -0,0 +1,50 @@
+# 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/docs/guides/workspace-commit.md

@@ -0,0 +1,45 @@
+# 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.