@c4a/context 0.7.4 → 0.7.8

package/docs/guides/indexer-skill-creation.md

@@ -0,0 +1,99 @@
+# Creating a reusable Indexer Skill
+
+A Provider is a portable Skill bundle. Workspace-local customization changes a
+selected Provider for one workspace; it is not the packaging format for a new
+Provider. Start from the source interpretation and reader task, then choose
+primary replacement or an advertised extension.
+
+## Package and protocol
+
+A typical instruction-only bundle contains:
+
+```text
+context-example-indexer/
+  SKILL.md
+  context-indexer.yaml
+  references/indexer.md
+  references/writing.md
+  templates/reader-guide.md
+```
+
+The name is illustrative. Use a discoverable context-…-indexer… name and an
+explicit Provider identity/version. SKILL.md describes when the lifecycle may
+select it; context-indexer.yaml declares context.indexer.provider/v1, domains,
+activation, profiles, operations and resources. Instructions and templates must
+be declared for the profiles using them. Do not copy unused profiles, composers
+or resource paths. Do not add a provider manifest to the creation assistant itself.
+
+Start from the [minimal manifest](indexer-manifest-example.md), which gives the
+field tree in three groups: required, required once a capability is declared, and
+optional. Read the [protocol](../reference/indexer-provider-protocol.md) for the
+subsystem rules behind those fields — selection validation, partition authority,
+overlays, controlled invocation — and the [selection
+guide](indexer-provider-and-customization.md) for composition.
+The four built-in examples are context-code-indexer, context-markdown-indexer,
+context-note-indexer and context-sessions-indexer. The latter two are independent
+source interpreters using markdown-domain contracts. Use their source-specific
+references instead of making a Markdown Provider accept everything.
+
+## Find a real example
+
+If Context CLI is available, inspect `context indexer catalog --format json`.
+Use the selected entry's guidance.skill_path and guidance.manifest_path to locate
+its bundle; read only that example and its declared resources. Alternatively use
+an exact Host-exposed installed Skill. Do not guess cache paths. This read-only
+catalog use is for Provider development, not a new production discovery gate.
+
+Choose one profile and follow its manifest references through instructions and
+template to its declared results. A code example demonstrates parser facts and
+public APIs; a document example demonstrates evidence-based consolidation;
+a note example demonstrates excerpts versus summaries; a sessions example
+separates decisions, rejected proposals and optional change associations.
+Adapt behavior, not only names. The example's breadth is not a minimum feature
+requirement for a specialized Provider.
+
+## Validate against the installed SDK
+
+Use the matching SDK's public exports. For community installations the package
+is @c4a/context; for an internal distribution use its supplied SDK coordinates.
+With the SDK available, this Node ESM check validates the manifest and declared resource paths:
+
+```js
+import { loadIndexerProviderManifest } from '@c4a/context';
+const manifest = await loadIndexerProviderManifest(process.argv[2]);
+console.log(manifest.id, manifest.version);
+```
+
+The argument is the Skill bundle directory. This check does not establish that
+all resources are usable or that the Provider can produce useful pages. Check
+all declared resource paths stay within the bundle and exist; validate templates
+with the SDK template loader and their declared profile contracts. Consult the
+installed exported signatures before writing the runner: do not invent a CLI
+validate command or fabricate a production Route to run a development check.
+
+Template protocol is context.indexer.template/v1. Semantic prose and deterministic
+Facts have separate variables; registered renderers own program blocks. A
+Provider cannot invent a renderer or an arbitrary document kind. Use supported
+profile/artifact contracts or the existing declared overlay mechanism.
+
+Use anonymous fixtures that demonstrate the advertised source interpretation:
+one useful result, material that cannot support a claim, and an existing-page
+update. Test primary/extension ownership only if that composition is advertised.
+Test the complete selected bundle in a disposable workspace through the normal
+lifecycle when the necessary CLI and materials are available. Preserve the
+user's live workspace. Record exact commands and failures; clearly distinguish
+schema/resource checks from semantic review and lifecycle verification.
+
+## Distribution and use
+
+Keep references and templates inside the bundle, with portable relative paths.
+The complete runtime file ledger determines integrity; do not hand-write a hash
+or copy another bundle's integrity. Use the target distribution's existing
+packaging/resolution tools. Development fixtures need not be shipped as runtime
+resources. Installation may use any supported organizational channel.
+
+A business Provider may be enabled through the host and selected instead of the
+default. Prefixes aid discovery; the manifest and verified resources determine
+compatibility. Select through the current Context Provider-selection Route when
+the user requests actual use. No new CLI install registry or creation-specific
+production state is needed.

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
 
@@ -96,6 +105,15 @@ content Review. There is no answer-only operation or evidence-specific Review.
 A blocking gap closes only through current source or an explicit non-delegable
 requirement change.
 
+## Bounded execution
+
+Each captured document remains an independently recoverable Partition input,
+but Context may transport several documents in one bounded Agent step. Return
+one result for every supplied task key and let global convergence merge
+documents that establish the same Subject. Batch order, filename order and
+heading order never create Subject identity. Author and Review use the same
+bounded transport rule without adding intermediate user approvals.
+
 ## Markdown author fixture checklist
 
 Release fixtures should cover:

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.