@c4a/context-cli 0.7.8 → 0.7.10-alpha.1

package/providers/context/provider.yaml

@@ -1,6 +1,6 @@
 schema: agent-graph.provider.v1
 id: c4a/context
-version: 0.7.8
+version: 0.7.10-alpha.1
 name: Context workflow
 description: Internal work contract for Context knowledge workspaces.
 graphs:

package/providers/context/resources/contracts/indexer-provider-guide.yaml

@@ -2,5 +2,5 @@ schema: agent-graph.resource.file.v1
 id: context.indexer.provider-guide
 kind: procedure
 mediaType: text/markdown
-path: skills/configure-indexer-providers/references/guides/indexer-provider-and-customization.md
-description: Current registry examples, Provider selection and customization instructions with bundled linked manuals.
+path: resources/manuals/guides/indexer-provider-and-customization.md
+description: Current requirements, lightweight Indexer guidance, stage-directory writing and temporary storage boundaries.

package/providers/context/resources/diagnostics/verification.md

@@ -10,14 +10,12 @@ Context reports one root diagnostic with counts and keeps derived findings in a
 separate detail view. Codes are stable machine identifiers; this document gives
 the shared recovery boundary.
 
-Broken source references or invalid stored structure require a corrected
-candidate or an explicit evidence-maintenance decision. Projection-only
+Invalid stored structure requires a corrected candidate. Projection-only
 failures can be repaired by deterministic close. Content-quality suggestions,
 including suspected unfilled placeholders, are advisory: they do not change a
 successful CLI outcome or add a gate. The existing Agent or user Review decides
 whether the content needs revision.
 
-`approved-source-orphaned` is a persistent warning produced only after an
-explicit `keep-orphaned` decision. It records that the page remains usable by
-policy while its original source document cannot be resolved. It does not
-permit changed source content to bypass replacement Review.
+Changed, missing or ambiguously relocated source regions identify articles to
+inspect through the normal revision workflow. Warnings do not add a separate
+maintenance gate, silently rewrite articles or confirm that the prose is current.

package/providers/context/resources/dialogue/package-output.md

@@ -10,10 +10,17 @@ Explain output shapes before SDK factory names. Offer:
 
 - an Agent knowledge-base package with `AGENTS.md`, a knowledge-query Skill,
   approved OKF roots, and adaptive indexes;
+- a searchable documentation website with the approved knowledge map, source cards and local-time update timestamps;
 - one LLM text bundle for model context or RAG import.
 
+These are multi-select channels, not exclusive options. For a new workspace with
+no explicit preference, propose KB + website as the default in the work-start
+report. Reuse that decision or session delegation at packaging; do not ask again
+for each channel. Preserve an existing workspace's configured output choices.
+A user can add a website later by asking to generate a documentation website.
+
 The user may postpone packaging and keep the approved Markdown in `knowledge/`.
-Pause at this choice and resume when an output is selected; postponing is not a
+When a user decision is required by the current Route and no session authority exists, collect the choices together; postponing is not a
 package declaration or a completed delivery. Do not write a `none` factory or
 claim that `packages: []` records a finished output choice.
 
@@ -35,6 +42,8 @@ explicit omission only when the author asks for another delivery policy. Git
 raw uses an immutable derived URL or an author-provided HTTPS `urlPrefix`;
 publishing and access remain the author's responsibility.
 
-Do not offer a hidden `both` shortcut. If the user wants multiple outputs,
-declare and inspect one first, then obtain confirmation for the next. Mention
-`kbPackage` and `llmsPackage` only after the semantic output choice.
+Map KB + website to one `kbPackage` with `site` configured, and LLM text to an
+additional `llmsPackage`. There is no `both` factory. If only a website is wanted,
+explain that it is built alongside the KB and only the sibling `dist/<base>-site/` directory needs
+to be distributed. The Agent makes the small SDK configuration edit; users do
+not need to write webpage code. Do not add a separate confirmation per output.

package/providers/context/resources/dialogue/source-boundary.md

@@ -6,6 +6,12 @@ mediaType: text/markdown
 
 # Source-boundary dialogue
 
+Confirm the reader purpose and source boundary, reusing explicit choices already
+provided by the user. Read a supplied plan as task guidance, not automatically as
+source material. Register and capture confirmed sources for lightweight
+investigation; the work-start report follows planning and must receive feedback
+before bulk writing. Source registration carries no report path or digest.
+
 Describe the boundary in user terms before showing a registration command. For
 code, distinguish a whole repository/subspace from one concrete package or
 subdirectory. For documents, distinguish one file, a local document directory,
@@ -23,7 +29,9 @@ Do not invent `-A`, `-B`, or sequence suffixes. If today's batch exists, append
 the newly confirmed module to it.
 
 When the current request already lists exact local modules or documents, do not
-repeat the source-boundary question in either ordinary or fully managed mode.
+repeat those source names as a separate question in either ordinary or fully managed
+mode. Their presence does not by itself settle reader purpose, output language,
+delivery choices or other required work-start information.
 Resolve each named module to one unique existing local path inside the
 user-scoped root, then pass that path in the batch payload. Repository paths are
 relative to the Context project root; the CLI may mechanically read their Git

package/providers/context/resources/dialogue/workflow-mode-after-creation.md

@@ -6,22 +6,20 @@ mediaType: text/markdown
 
 # Workflow mode after workspace creation
 
-After the workspace is created, explain the two execution modes only when the
-conversation has not already selected a mode and no earlier mode question was
-asked. If the entry plan or initialization confirmation already resolved this
-choice, continue without asking again.
+Explain the modes only when the conversation has no explicit choice and no mode
+question has already been asked. Reuse an explicit choice in a task brief the
+user asked you to execute, including fully managed authorization. Do not repeat
+the choice after capture or continuation, or persist session authority in files.
 
-- Ordinary review mode is the default. Context pauses at review decisions and
-  provides HTML reports for the user to inspect. The current product estimate is
-  that these review rounds make the overall workflow about 40% slower, with the
-  exact difference depending on workspace size and user response time.
-- Fully managed mode skips delegatable content-review surfaces and continues
-  with the same revision-bound resolution Actions. It is faster, but gives the
-  user fewer opportunities to control or adjust intermediate content.
+Describe both modes neutrally in the user's language:
 
-Make clear that fully managed mode does not bypass source boundaries, external
-permissions, hard validation, evidence checks, verification failures, or other
-non-delegatable safety boundaries. Ask whether the user wants to keep the
-default ordinary review mode or authorize fully managed operation for the
-current conversation. This is a one-time conversation choice: do not repeat it
-after capture or resume, and do not persist it in project files.
+- Ordinary review pauses at review decisions and provides HTML reports, giving
+  the user opportunities to inspect content, catch deviations and adjust direction.
+- Fully managed operation delegates eligible reviews to the Agent and continues
+  with the same revision-bound Actions, reducing manual involvement. The user
+  has fewer opportunities to inspect intermediate results before delivery.
+
+Neither mode bypasses source boundaries, external permissions, evidence checks,
+verification failures or non-delegatable decisions. Do not promise a percentage
+speed difference. When a choice is needed, ask which mode the user prefers for
+this conversation.

package/providers/context/resources/manuals/guides/code-indexer-skill-authoring.md

@@ -0,0 +1,84 @@
+---
+id: context.sdk.code-indexer-skill-authoring
+kind: procedure
+mediaType: text/markdown
+---
+
+# Code Indexer Skill authoring
+
+An Indexer exposes the source skeleton and guides source-grounded writing.
+Read [planning and writing guidance](./indexer-provider-and-customization.md)
+for the current workflow. Do not recreate routing inside a Skill.
+
+## Skill responsibilities
+
+Describe the supported technology, activation signals, useful reader questions,
+and how to investigate an authorized module. A module may use several Skills for
+different concerns. There is no exclusive primary owner, version pin, integrity
+receipt or production registration prerequisite. Skill names and optional usage
+configuration are temporary planning guidance, not article metadata.
+
+Keep `SKILL.md` focused on discovery and decisions. Put optional detailed writing
+guidance and reusable scripts beside it, with relative links and clear triggers.
+Distribution metadata does not impose workspace version validation.
+
+## Skeleton first
+
+During planning, prefer directories, manifests, registration points and bounded
+search. Either let the Agent inspect these directly or offer a fast helper suited
+to the stack. Report matching names, known counts and file locations. Do not
+require complete symbol extraction, call graphs or reading every implementation
+before proposing articles.
+
+Distinguish file-list counts from syntax-derived feature counts. A helper with a
+budget must identify inspected and uninspected scope, return a continuation when
+available, and label partial counts. Never present a stopped scan as a full total.
+Representative deeper reading is optional when it clarifies a topic boundary.
+
+Signals suggest topics; they do not prove semantics. A route registration can
+suggest an API topic, but not its error behavior or business meaning. Prefer
+reader questions to a mechanical page for each directory, symbol or heading.
+Keep module directories explicit in task guidance when needed, without adding
+a separate persisted boundary protocol or a new validation gate.
+
+## Writing and evidence
+
+Once the current report is confirmed, read the source needed for each assigned
+article. Describe contracts, state changes, failure behavior and integration
+points where relevant. Optional parsing can help locate declarations; it is not
+proof of runtime behavior. Preserve expressions without executing project code,
+distinguish declaration defaults from implementation defaults, and state unknowns.
+
+Use the current stage's Markdown and reference-file schemas. Each fragment cites
+at most three actual source locations; the CLI computes regional digests. Split
+an explanation when it needs separate evidence, not to fill a fixed template.
+Reuse stable article and fragment identities when revising. Supporting documents,
+notes or sessions may contribute to the same article without becoming code facts.
+
+The Agent plans batches and chooses reading order within the work released by
+the CLI. If supported, workers write assigned drafts and the coordinator submits
+completed subsets. Do not require every batch to finish before submission.
+Use the existing missing-material and repair outputs, not a per-member ledger,
+another content audit or a Skill-specific retry protocol.
+
+## Optional scripts
+
+Scripts serve a concrete repeated task; they are not mandatory for every stack.
+Take explicit authorized paths and bounded options, keep source files read-only,
+and return concise output or a file in the supplied temporary area. Do not execute
+repository code, read credentials, traverse unrelated directories or contact
+external services implicitly. Full parsing belongs to selected writing tasks.
+Report unsupported syntax and incomplete traversal separately from zero matches.
+
+## Validation and distribution
+
+Test supported technology with anonymous fixtures: feature discovery, bounded
+stopping, unsupported input, repeated names in different paths, and final article
+references. For generated API explanations, verify defaults, shared types and
+unresolved cross-file links in the final page as well as the parser output.
+Use relevant fixtures, not a mandatory matrix for unrelated technologies.
+
+Verify packaged relative links and executable helpers. Keep community examples
+free of company-specific services; organization and project knowledge belongs in
+their own Skills. Publishing or installing a Skill requires the appropriate
+authorization and does not add a hash or version check to knowledge production.

package/providers/context/resources/manuals/guides/indexer-provider-and-customization.md

@@ -0,0 +1,117 @@
+---
+id: context.sdk.indexer-provider-and-customization
+kind: procedure
+mediaType: text/markdown
+---
+
+# Indexer guidance for planning and writing
+
+Follow the current Route returned by `context run` or `context status --format json`.
+The CLI prepares a stage directory and returns its instructions, schemas and
+submission command. Use those files instead of copying long content into arguments.
+
+## Responsibilities
+
+An Indexer helps expose the source skeleton and guides source-grounded writing.
+It is not a mandatory full symbol scan or a semantic classifier owned by the CLI.
+Use a visible Skill directly, or its bounded CLI-assisted discovery, as appropriate
+for the technology. Multiple Indexers may explain different aspects of one module.
+There is no mandatory primary-owner selection or Provider resolution stage.
+
+At the start of this continuous work, declare the available relevant Skills and
+whether the Agent can schedule sub-agents. Use the capability schema supplied in
+the stage directory. A new session must declare its actual capabilities; do not
+inherit another session's parallel scheduling claim. Skill names and optional
+configuration are guidance, not version pins or evidence of completed reading.
+Do not inspect caches, compare Skill hashes, resolve exact versions or create a
+second installation registry. Installation and enabling Skills belong to the Host.
+
+## Confirmed requirements
+
+The configuration Route names the required file and supplies its schema. The
+requirements-only registry records reader goals and authorized sources, not
+production assignments. For example, replace the source and goals with the
+user's actual scope:
+
+```yaml
+protocol: context.indexer.registry/v1
+requirements:
+  - id: integration-guide
+    purpose: Help application developers understand and integrate the system.
+    reader_goals: [understand-system, integrate-system]
+    coverage_domains:
+      architecture: required
+    target_scope:
+      targets:
+        - source_ref: repo:sample
+    evidence_source_scope:
+      targets:
+        - source_ref: repo:sample
+indexers: []
+```
+
+Use registered source identities, not guessed paths or URLs. Keep any confirmed
+exclusions and supporting-source boundaries. Sources needed for another requirement
+are not globally excluded. Module directory boundaries can be supplied in task
+instructions by the Agent or CLI; do not invent persistent article fields or
+extra module-path validation. A module name alone does not identify its directory.
+
+## Lightweight investigation and planning
+
+For code, inspect directories, manifests and registration points. Return names,
+known counts and locations, not every symbol, call graph or implementation detail.
+Discovery has a bounded budget. Report incomplete coverage honestly; partial
+feature counts are not totals. Read representative code only when it helps make
+the plan. Deep extraction belongs to writing the selected topic.
+
+For documents, start with titles, bounded introductory text and heading outlines.
+Read more when necessary. Reuse code topics or existing articles where the content
+belongs, without forcing business concepts into physical directory names. Notes
+and sessions can directly suggest a new article or an amendment to an existing one.
+
+Submit article paths, reader questions, source associations and writing batches
+using the supplied planning schema. Record selected Skill names and configuration
+in the temporary plan's `indexer_usage`; the CLI can return it during planning
+and writing. It is not persisted on articles, sections or production results.
+Known one-to-one tasks can use the direct-writing path without an extra semantic
+planning submission. Do not create an inventory-member disposition ledger.
+
+Present the final work-start report after the relevant source overviews and plan
+are ready, before bulk writing. Wait for the user's confirmation, including in
+managed mode. Do not add approval for internal batch counts or Skill choices.
+
+## Directory-based writing
+
+The CLI determines which batches are ready and supplies their material and
+acceptance rules. Within that authorized work the Agent chooses reading order,
+writing order and, when supported, sub-agent scheduling. Without sub-agent support,
+work serially through the returned batch. Workers may write their assigned draft
+files; the coordinator submits completed subsets and owns shared CLI writes.
+
+Write Markdown and references into the stage's temporary output directory. Submit
+the short file manifest with stage-relative paths. Whole-article submissions and
+section repairs use the returned schemas. Read the receipt for accepted tasks,
+precise errors and next ready work; do not resubmit accepted content unnecessarily.
+Multiple authorized sources may support an article. A new task or changed plan
+must still respect confirmed requirements and the work-start report boundary.
+
+## Storage and continuation
+
+Drafts, capability declarations, plans, candidates, acceptance receipts and
+transaction state remain in `.tmp`. Only formal knowledge, necessary source
+material and long-term requirements belong in durable project content.
+With intact temporary state the current work can resume or retry safely. After
+clearing `.tmp` or cloning elsewhere, start new production from formal knowledge
+and sources; do not reconstruct the old workflow. There is no historical protocol
+migration or compatibility path.
+
+Source authorization, real references, safe file reads and concurrent-write
+protection still apply. Skill identity is not a production acceptance condition.
+
+## When maintaining a Skill
+
+For an explicitly requested Skill change, use the
+[code Skill authoring guide](./code-indexer-skill-authoring.md) or
+[document Skill authoring guide](./markdown-indexer-skill-authoring.md).
+These are authoring references, not additional reading required for routine
+knowledge production.

package/providers/context/resources/manuals/guides/knowledge-updates.md

@@ -22,18 +22,130 @@ 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
+## First-task intake budget
+
+Before registration and capture, the Agent uses the user's task instructions and
+reads batch metadata titles across the explicitly supplied document list. Lark
+metadata requests accept at most 200 entries each, not 200 words or 200 documents
+overall. H1/H2 may be reused only when metadata returns them without
+body retrieval; Lark batch metadata returns titles, not headings. Batch failure
+falls back to at most 10 unresolved document title lookups total, unless a shared
+authentication failure makes those calls redundant. The Agent does not fetch
+source bodies, outlines, images or attachments. Missing title metadata is
+optional: preserve the original URL without falling back to body retrieval or
+changing credentials. Resolve intent from the conversation; refine provisional
+chapters and module boundaries from evidence after formal capture.
+
+## Agent-planned writing order
+
+Within the tasks available in the current Route, the Agent may choose a writing
+order from the reader's needs and relationships between topics. There is no
+fixed code-first or document-first rule. Prefer foundational concepts and shared
+terminology before walkthroughs or summaries that benefit from them, when this
+reduces rework. Independent topics can proceed without waiting; adjust the order
+as writing progresses instead of maintaining a separate scheduling artifact.
+
+This is an Agent working preference, not a new dependency or completion gate.
+Do not add dependency fields, fetch extra material, or delay useful work merely
+to establish an order. Keep current task boundaries, source permissions and
+submission rules; do not pull future batches forward or change the CLI Route.
+
+## Workspace versions and changelog
+
+`package.json.version` is the workspace SemVer. At completed-scope delivery the
+workflow asks the Agent to inspect formal changes and record an increasing version
+with a concise changelog. Added modules or expanded material coverage increment
+minor; corrections, existing-module updates, navigation and persistent status
+changes increment patch. Major requires an explicit user instruction. Temporary
+progress under `.tmp/` never causes a version increase.
+
+Version recording runs at completed-scope delivery after Review, Close and package
+configuration/template approval, before the final build. The record response
+returns the next workspace Route, so no extra status call is needed. Build retries
+reuse the recorded version when formal content is unchanged. Intermediate batches
+do not each receive a version.
+
+The workspace AGENTS.md and version-writing instructions require each entry's
+details to stay within 1500 visible characters, including punctuation across the
+title, changes, trigger descriptions and actor display name, excluding protocol
+keys, version and date. The Agent compresses longer drafts before submission,
+preserving main changes, impact and triggers instead of truncating text or splitting
+the iteration into extra versions. This is an Agent writing rule, not a prose-quality
+CLI gate.
+
+`context version inspect --format json` returns changed paths and a digest. The
+coordinator submits `context version record --input <file> --format json` with:
 
-For a reading-directory-only change, use the existing `context task adjust
---input <file|-> --format json` action with `reading_structure`. Supply its
+```yaml
+expected_digest: "<digest returned by inspect>"
+version: 0.2.0
+title: Add module recovery guidance
+changes:
+  - Document recovery conditions and the supported retry flow.
+triggers:
+  - kind: module
+    description: Additional module material requested in this iteration.
+actor:
+  kind: lark
+  name: Example User
+```
+
+`actor` is optional; omit it to use local Git `user.name` when configured. Use a
+Lark display name only when explicitly known from the conversation. Trigger kinds
+are `initial`, `note`, `sessions`, `mr`, `module`, `document`, `navigation`,
+`repair`, `dist`, and `other`. Agent-written fields describe the actual diff and
+conversation; they must not expose credentials, raw transcripts or private IDs.
+
+The CLI writes `changelog.yaml`, generated `CHANGELOG.md`, `package.json` and the
+`.context-version.json` content baseline together. Keep these formal files with
+the workspace; do not hand-edit generated baselines. Git-managed and unignored
+new files are compared (without Git, non-runtime workspace files are compared).
+Version metadata itself, `dist`, `.tmp` and dependencies do not cause changes.
+
+Successful builds record version and per-package hashes in `.context-builds.json`.
+They do not increase versions. Before publishing, `context version publish-check
+--format json` compares against `.context-published.json`. A same-version changed
+output requires a patch using `version inspect --publish` and a `dist` trigger,
+then a rebuild. Record `version published --hash <checked-hash> --receipt
+<successful-publication-reference> --format json` only after external success.
+No command commits, tags or uploads automatically.
+
+Website history is available at `changelog.html`: cards are newest first, the
+latest three expanded and older cards collapsed. The History button beside the
+theme switch and footer update timestamps link there. KB and LLMS outputs carry
+the same workspace version and changelog.
+
+## Customize the knowledge map at any time
+
+For a knowledge-map-only change, use the existing `context task adjust
+--input <file|-> --format json` action with `knowledge_map`. 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.
+identities. Read the persistent `src/knowledge-map.yaml`; use
+`expected_revision: null` only when no knowledge map 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.
 
+Users can ask in conversation to move a topic, rename a directory, change order,
+or organize the same articles for another reader task. Handle this during ongoing
+production or after completion through the same adjustment; no active Indexer
+task, source recapture or new mode choice is required. Finish or revoke active
+worker assignments before changing the map. Preserve unrelated entries and page
+identities. The map controls website navigation and LLMS organization together.
+
+For each new or changed article, the Agent decides whether to retain its current
+placement, add another placement, move it, or create a warranted category. Check
+these choices against the user's settled organization before structure approval
+and delivery. New articles must be bound even if the map revision has not changed;
+modifying a title alone is not a reason to change article identity. Never satisfy
+coverage by mechanically placing every new page under an unrelated catch-all.
+Build reports missing bindings for the Agent to resolve; it does not classify
+content. Moving a menu entry does not change the article URL.
+
+## Edit one section or review part of a batch
+
 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
@@ -41,6 +153,13 @@ ordered `content` list of `{ "markdown": "new text" }` and/or
 selected section's source references remain intact. Use full Markdown when
 changing structure, adding a page or when a section has no unambiguous ID.
 
+To change a fragment's citations, include `references` alongside its `section_id`:
+each entry supplies `source_ref` and `locator` (`path`, `start_line`, `end_line`).
+Context computes the region fingerprint. This uses the same revision submission,
+with at most three source positions per fragment. Full Markdown may include a
+`sections` list of reference edits; local section edits may change content,
+references, or both. Omission preserves citations; an empty list removes them.
+
 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
@@ -314,17 +433,17 @@ 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.
+### Revising material reused from another article
+
+When a supporting article changes, revise the affected explanation using
+`context revise`. Read the relevant approved text and, where needed, its original
+sources. Keep direct source regions on the affected output fragments; do not
+recreate an article dependency graph or copy facts and evidence IDs.
+
+Revision section edits may supply `references` as `source_ref` plus a
+`locator` containing `path`, `start_line`, and `end_line`. Context computes the
+regional digest. Omitted references preserve the current fragment's citations;
+an explicit empty list removes them, and deleting a fragment removes its
+citations. Each fragment may cite at most three source positions. Register and
+authorize new material before citing it, then follow normal Review, close and
+build. Article links alone do not authorize reading new sources or prove a claim.

package/providers/context/resources/manuals/guides/markdown-indexer-skill-authoring.md

@@ -0,0 +1,65 @@
+---
+id: context.sdk.markdown-indexer-skill-authoring
+kind: procedure
+mediaType: text/markdown
+---
+
+# Markdown Indexer Skill authoring
+
+Use the shared [planning and writing guidance](./indexer-provider-and-customization.md).
+Document Skills help interpret captured articles; notes and sessions have their
+own guidance but can support the same reader topic. No unique primary owner,
+version lock or per-document disposition ledger is required.
+
+## Captured sources
+
+Start from authorized captured Markdown and its source identity. Capture proves
+which bytes are available, not what they mean. Titles, headings and filenames are
+navigation aids, not proof that the Agent has read the body.
+
+Do not fetch new documents, follow external links or widen source authorization
+implicitly. Request missing material through the current workflow. Keep the
+distinction between a source being unavailable and its contents being irrelevant.
+
+## Planning
+
+Read the supplied titles, bounded introductions and complete H2/H3 outlines.
+The Agent may read additional sections or the full document when needed, then
+chooses article targets and writing batches. Do not require full-body reading of
+every document or a separate planning submission for an already explicit target.
+
+Consult code topics and existing article descriptions and references. Reuse a
+topic when its reader question fits, or propose a clearer business topic instead
+of forcing a document under a code directory. One document may support several
+articles and several authorized documents may support one article.
+
+The final work-start report follows the relevant source overview and plan, and
+must wait for the user before bulk writing, including in managed mode.
+
+## Writing and repairs
+
+Read the actual passages needed for the article. Distinguish authoritative rules,
+examples, decisions and proposals; a session suggestion is not an implemented
+behavior. Write Markdown and references in the supplied temporary directory and
+submit the short stage-relative manifest. Title and description belong to the
+article, not an internal layout-mapping tuple.
+
+Keep stable article and fragment identities when revising. Each fragment cites
+at most three actual source regions. The CLI handles source digests and safety;
+the Agent judges whether the evidence supports the explanation. For a local
+failure, use the returned fragment identifier or position to repair the affected
+part. Completed independent tasks can be submitted without the rest of the batch.
+
+Do not inflate page counts, produce a page for every heading, or turn missing
+evidence into speculative prose. A genuine material gap remains unfinished work;
+an explicit exclusion uses the existing exclusion mechanism. Neither requires
+a new reconciliation ledger or additional content-review stage.
+
+## Useful fixtures
+
+Cover an ordinary one-to-one article, multi-document synthesis, reuse of an
+existing topic, fragment repair, source line changes, links and images, and
+missing material for the document forms the Skill supports. Verify both source
+fidelity and the final page. Keep examples anonymous and check packaged links.
+Drafts and scheduling details remain temporary; deleting `.tmp` starts fresh
+production from formal knowledge and available sources, not a workflow migration.