@c4a/context-cli 0.7.4 → 0.7.8

package/providers/context/skills/configure-indexer-providers/references/guides/markdown-indexer-skill-authoring.md

@@ -0,0 +1,136 @@
+# Markdown Indexer Skill authoring
+
+Markdown Providers use the same `context.indexer.provider/v1` manifest,
+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 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
+
+Capture owns source authorization, retrieval, revision identity, complete bytes,
+Markdown/MDX parsing and evidence spans. A Markdown Indexer starts only from a
+current captured source report and authorized evidence view. URLs, titles,
+filenames, headings and capture success are activation candidates, not semantic
+classification or proof that the whole document was read.
+
+The Provider cannot fetch the document again, follow new links, rewrite source
+revisions or widen capture scope. Missing/unsupported capture capability is an
+explicit unsupported result, never a prose fallback.
+
+## Activation and source roles
+
+Declare document activation signals and map evidence-backed sources to declared
+roles such as authoritative, explanatory, operational, decision or example
+material. Keep role selection separate from collection placement. One document
+may support multiple reader questions, but every consumed span retains its
+source/revision identity and cannot be promoted to a stronger authority by an
+instruction.
+
+## Section projection and collection mapping
+
+Author Results propose logical Sections and their intent; they do not write
+`knowledge/` paths. Each Section binds:
+
+- the canonical SubjectKey/Node target or an explicit independent target;
+- its reader-question refs and exact evidence spans;
+- an Artifact kind and Section key stable across content-only changes;
+- a projection intent describing purpose, not a physical filename;
+- structured content layers and their digests.
+
+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. 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
+
+Use the supplied subject catalog and TargetResolutionView. Equal SubjectKeys use
+the same NodeRef across Code and Markdown. `resolved` enriches the existing
+Node; `absent` may create an explicitly independent subject or a material gap;
+`ambiguous` fails before authoring. Titles, heading similarity and filenames
+are never identity fallback. Unrelated catalog changes must not make a workset
+stale.
+
+## Artifact and Section planning
+
+One logical unit may produce an Artifact Bundle with multiple meaningful
+Sections or semantic split Artifacts. Do not use fixed-count, ordinal or
+alphabetic batches. Do not create one page per heading/member or inflate page
+count to satisfy a metric. The CLI owns Artifact-policy eligibility, physical
+fan-out audit, layout actualization and the final Candidate compile.
+
+The first actual Section of each reader Artifact begins with one concise,
+source-backed level-one heading. Context uses that heading as the outline and
+Candidate Review display title. It never participates in SubjectKey derivation
+or ownership, and later Sections in the same Artifact do not repeat it.
+
+Each Section carries exact positive and negative dependency refs. Incremental
+impact is Section/Artifact-local: a source membership, question denominator,
+candidate pool, evidence span or run-envelope change invalidates only the
+dependent scope. A Provider must not replace this with source-wide or
+collection-wide recomputation.
+
+## Editorial policy
+
+Editorial instructions may guide clarity, consolidation, ordering and
+reader-facing terminology. They cannot alter facts, evidence, source role,
+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
+
+When current material cannot answer a required canonical question, return the
+exact material-question disposition for the supplied owner cell, question
+contract and Subject target. Do not invent a new question contract or landing.
+Context reports the unresolved set in current reconciliation state; it does not
+create a second checkpoint ledger or published gap artifact.
+
+Capture the missing Markdown or other source normally, then rerun `main-index`.
+The new Result updates the same knowledge Candidate and enters the same final
+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:
+
+- complete Markdown and MDX capture plus unsupported parser/capture paths;
+- authoritative reference, guide, runbook, FAQ, decision, incident, policy,
+  test and release/migration document shapes using anonymous content;
+- per-Section projection into every supported collection intent;
+- existing Code Node reuse, independent subject, ambiguity and material gap;
+- content-only reuse plus add/remove/rename/split/merge/collection/path/Section
+  move in both directions;
+- protected values, links, images/assets and source-span fidelity;
+- editorial positives and placeholder/speculation/unsupported negatives;
+- material-gap runtime recovery, main-index retry and no-output-leak;
+- Section-local incremental invalidation, new membership/denominator/candidate
+  pool changes and unaffected Section reuse.
+
+Source authorization, capture revision safety, canonical question/collection
+contracts, layout confirmation, review and build remain Context authority and
+cannot be replaced by the Skill.

package/providers/context/skills/configure-indexer-providers/references/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/providers/context/skills/configure-indexer-providers/references/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.