@c4a/context-cli 0.7.5 → 0.7.8

package/indexers/bundles/context-sessions-indexer/templates/domain-reference.md

@@ -0,0 +1,31 @@
+# What this means
+
+This is the page shape for one durable term, relationship or rule. Use it as an
+outline, not a form to fill.
+
+## Section blueprint
+
+```markdown
+## <the term or rule>
+- Definition: what it means here
+- Applies to: the boundary within which the definition holds
+- Related: the neighbouring terms readers confuse with it, and the difference
+- Example: one concrete case that shows the definition in use
+```
+
+`Definition` is required and comes first. `Applies to` is what separates a
+definition from a slogan: the same word often means different things in two
+systems, and a definition without its boundary will be applied where it is wrong.
+`Related` earns its place only when a real confusion exists.
+
+A page may define one concept or a coherent group of terms and rules needed to
+understand it. Give each term a searchable heading. Split independent subjects,
+not every term: avoid both unrelated glossary dumps and thin one-term pages.
+Group by what readers need together, not the order of a discussion.
+
+Sessions are where terms get pinned down, usually because two people meant
+different things by one word. That makes them a strong source for `Related` and
+`Applies to` — the disagreement itself shows where the boundary lies. It also
+makes them easy to overstate: agreement among participants establishes shared
+usage in that context, not an organization-wide standard. If the discussion
+settled the meaning for one team or one system, the boundary says so.

package/indexers/bundles/context-sessions-indexer/templates/faq-support.md

@@ -0,0 +1,33 @@
+# Answer the question
+
+Use this outline for one question or a coherent group of related questions.
+Repeat the answer sections when that helps lookup; it is not a form to fill.
+
+## Section blueprint
+
+```markdown
+## <the question, phrased the way a reader would ask it>
+- Answer: the direct answer, in one or two sentences
+- Applies when: the version, platform, configuration or role that bounds it
+- What to do: the action or check that follows, when one does
+- Not covered: the adjacent question a reader would otherwise assume is answered
+```
+
+The answer comes first and is required. Everything else exists to stop a reader
+from applying the answer where it does not hold. Give `Applies when` whenever the
+discussion bounds the answer; qualify a missing boundary when it changes how a
+reader can use the answer, not as a generic disclaimer. Omit `What to do` when no
+action follows.
+
+Group by the reader's task, not by the number or order of questions in a thread.
+Related questions about the same task can share a page with searchable headings;
+separate questions with independent scope or use. Preserve existing page
+identities when updating.
+
+A session answers questions through people talking, which means the strength of
+an answer varies inside one thread. Someone asking, someone guessing and someone
+confirming are three different things; the page carries only what was actually
+settled, at the strength it was settled. If the thread ended with the question
+still open, that is not a FAQ entry — say the question is unresolved, or leave the
+source saved without a page. An answer that was corrected later in the same
+discussion uses the correction, not the first reply.

package/indexers/bundles/context-sessions-indexer/templates/incident-review.md

@@ -0,0 +1,37 @@
+# What happened and what changes
+
+This is the page shape for one incident. Use it as an outline, not a form to
+fill.
+
+## Section blueprint
+
+```markdown
+## <the incident, named by its impact rather than its date>
+- Impact: who or what was affected, and for how long
+- Sequence: what happened, only to the detail that explains the outcome
+- Cause: established causes, kept separate from hypotheses still open
+- Changed: what was actually changed as a result
+- Change discussed: the associated change, where a reader needs to check it
+- Still open: follow-ups that have not landed
+```
+
+`Impact` and `Cause` are required. A hypothesis stays labelled as one for as long
+as it is unconfirmed; an unlabelled guess in `Cause` is the failure mode this
+profile exists to prevent. Keep `Sequence` only as long as it explains the
+outcome — a troubleshooting discussion contains many attempts, and reproducing
+them in order is not an explanation.
+
+Separate what was tried and failed from what actually resolved the incident.
+Under `Changed`, a remediation someone proposed during the discussion is not a
+change; proposals belong in `Still open` until an authorized source shows they
+landed. The same distinction applies to causes: "we think it was the cache" from
+mid-discussion is a hypothesis even when the incident later resolved.
+
+`Change discussed` renders the source's optional `changes` association as readable
+prose, for a reader who needs to open the fix and see it. It does not establish
+that the fix shipped or worked; keep it out of the page frontmatter.
+
+A session records the incident as the participants understood it at the time.
+Where their account cannot establish impact or cause, record that gap rather than
+completing the story — a review that reads as resolved while its cause is
+unknown is the version people stop questioning.

package/indexers/bundles/context-sessions-indexer/templates/product-requirements.md

@@ -0,0 +1,35 @@
+# Expected behavior
+
+This is the page shape for one required behavior. Use it as an outline, not a
+form to fill.
+
+## Section blueprint
+
+```markdown
+## <the requirement, named by the behavior it demands>
+- Expected: the behavior as agreed
+- Accept when: the conditions that make it satisfied
+- Today: how the current implementation differs, where that is known
+- Change discussed: the associated change, where a reader needs to check it
+- Undecided: what the discussion left open
+```
+
+`Expected` and `Accept when` are required. Keeping `Expected` and `Today` distinct
+is the entire reason this profile exists: a requirement agreed in a discussion
+written as current behavior misleads every later reader, and the mistake becomes
+invisible once the page is approved. When no authorized source establishes current
+behavior, write that it has not been checked rather than leaving `Today` absent.
+
+`Accept when` must be checkable. Requirements clarified in conversation often
+arrive as intent — "it should retry" — with no condition attached. If the
+discussion gives no checkable condition, record that gap; an untestable
+requirement will be declared met by whoever wants it met.
+
+Distinguish what participants agreed from what one participant proposed. An
+unanswered suggestion is not a requirement, and `Undecided` is where it belongs.
+A requirement agreed for a future release coexists with current behavior that
+does not satisfy it; keep both, and keep them labelled.
+
+`Change discussed` renders the source's optional `changes` association as readable
+prose, for a reader checking how far the requirement has been carried. It does
+not establish that the requirement is met. Keep it out of the page frontmatter.

package/indexers/bundles/context-sessions-indexer/templates/runbook.md

@@ -0,0 +1,32 @@
+# Diagnose and recover
+
+This is the page shape for one operational situation. Use it as an outline, not a
+form to fill.
+
+## Section blueprint
+
+```markdown
+## <the symptom, as an operator first encounters it>
+- Symptom: what is observed, including the actual message or signal
+- Confirm: how to tell this case apart from ones that present the same way
+- Act: the ordered steps, with anything irreversible marked as such
+- Verify: how to know recovery actually worked
+- Escalate: who or what to fall back on when the steps do not resolve it
+```
+
+`Symptom` and `Act` are required; a page missing either is not usable under
+pressure. `Verify` is the section most often dropped and the most consequential:
+an unverifiable recovery invites an operator to declare success early. When the
+discussion never says how recovery was confirmed, record that as a gap rather
+than inventing a check. Omit `Escalate` when no fallback is known.
+
+A troubleshooting session is mostly attempts that did not work. Only what
+actually resolved the situation belongs in `Act`, and only in the order that was
+actually effective — not the order people tried things. A step someone suggested
+mid-discussion and nobody ran is not part of the procedure; if it is worth
+keeping, it is a hypothesis, not an instruction.
+
+Watch for the case where the incident resolved and nobody established why.
+Participants often settle on a cause by agreement rather than by evidence. Keep
+that out of `Confirm`, because a guessed discriminator sends the next operator
+down the wrong path while a real incident is running.

package/indexers/bundles/context-sessions-indexer/templates/technical-guide.md

@@ -0,0 +1,31 @@
+# Complete the task
+
+This is the page shape for one repeatable task. Use it as an outline, not a form
+to fill.
+
+## Section blueprint
+
+```markdown
+## <the task, named by what the reader accomplishes>
+- Goal: the end state the reader reaches
+- Before you start: prerequisites, permissions and required prior state
+- Steps: ordered, each one with an observable outcome
+- Check: how the reader knows the task succeeded
+- When it fails: the failures actually encountered, and what to do about them
+```
+
+`Goal`, `Steps` and `Check` are required. A step whose outcome the reader cannot
+observe is not a step — either give what it produces or say the outcome is
+unknown. `Before you start` is required whenever a missing prerequisite would fail
+the task partway. Keep `When it fails` to failures the discussion actually
+records.
+
+A session describes a task as it was worked out, not as it should be performed.
+Those differ: the working-out includes dead ends, corrections and steps that were
+later found unnecessary. Reconstruct the procedure that a reader should follow,
+and drop the path taken to discover it. Where the discussion corrected an earlier
+step, the page carries the corrected version only.
+
+Do not fill gaps with generic advice such as "check your configuration". A guide
+with three established steps and one stated unknown is more useful than five
+steps where two were inferred from context.

package/indexers/bundles/context-sessions-indexer/templates/test-validation.md

@@ -0,0 +1,37 @@
+# What was checked
+
+This is the page shape for one validation. Use it as an outline, not a form to
+fill.
+
+## Section blueprint
+
+```markdown
+## <what was validated>
+- Checked: the behavior or property under test
+- How: the method, environment and scope
+- Result: what the run actually showed
+- Change discussed: the associated change, where a reader needs to check it
+- Not covered: what this validation does not establish
+```
+
+`Checked` and `Result` are required, and `Result` must carry the strength of its
+evidence. In a discussion, "I tested it and it works" is a reported result: write
+it as reported unless the actual output is in authorized scope. `Not covered` is
+required whenever the scope is narrower than the claim a reader would naturally
+draw from it.
+
+`How` matters because a result without its method cannot be repeated. Discussions
+routinely omit the environment — record that as a gap rather than describing a
+plausible setup.
+
+`Change discussed` renders the source's optional `changes` association as readable
+prose. Be especially careful here: a change link proves neither that tests ran on
+that change nor that they passed. Someone saying "tested" in a conversation about
+a commit does not establish that the commit's final state was covered, and the
+change may have moved afterwards. Keep the association out of the page
+frontmatter.
+
+Evidence strength depends on what the session contains. Actual output with its
+relevant scope can support a verified result; an unsupported claim remains a
+reported result. Attribute and bound it without downgrading actual evidence
+merely because it was supplied in a conversation.

package/indexers/bundles/context-sessions-indexer/templates/user-and-developer-guide.md

@@ -0,0 +1,31 @@
+# Use this in practice
+
+This is the page shape for putting one capability to use. Use it as an outline,
+not a form to fill.
+
+## Section blueprint
+
+```markdown
+## <the capability, named by what the reader does with it>
+- When to use it: the situation it fits, and the nearby one it does not
+- How: the minimal path that actually works
+- Important combinations: options or settings that only make sense together
+- Limits: what it will not do, and what to reach for instead
+```
+
+`When to use it` and `How` are required. The negative half of `When to use it`
+carries most of the value — a reader who picks the wrong capability is not helped
+by a correct description of it. `How` shows the minimal working path, not every
+option raised in discussion.
+
+`Important combinations` exists because the costly mistakes are usually
+combinations rather than single settings. Discussions are a good source for these,
+since they often start from someone hitting the combination. Include it when a
+real dependency was established, and omit it rather than generalizing from one
+report.
+
+A session gives you practice and preference mixed together. "We always do it this
+way" establishes a convention among those participants; it does not establish a
+requirement or a recommendation the organization holds. Say which one you have.
+Where a preference was stated without a reason, either the reason is in scope or
+the page presents the usage without the recommendation.

package/indexers/bundles/context-sessions-indexer/tests/fixtures/profiles.json

@@ -0,0 +1,281 @@
+[
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-domain-reference",
+    "anonymized": true,
+    "profile": "domain-reference",
+    "source_role": "authoritative-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-domain-reference",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-purpose"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-domain-reference-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-domain-reference-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-product-requirements",
+    "anonymized": true,
+    "profile": "product-requirements",
+    "source_role": "authoritative-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-product-requirements",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-purpose"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-product-requirements-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-product-requirements-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-technical-guide",
+    "anonymized": true,
+    "profile": "technical-guide",
+    "source_role": "authoritative-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-technical-guide",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-structure"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-technical-guide-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-technical-guide-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-user-and-developer-guide",
+    "anonymized": true,
+    "profile": "user-and-developer-guide",
+    "source_role": "supporting-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-user-and-developer-guide",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-operation"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-user-and-developer-guide-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-user-and-developer-guide-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-runbook",
+    "anonymized": true,
+    "profile": "runbook",
+    "source_role": "operational-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-runbook",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-operation"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-runbook-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-runbook-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-faq-support",
+    "anonymized": true,
+    "profile": "faq-support",
+    "source_role": "supporting-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-faq-support",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-purpose"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-faq-support-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-faq-support-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-decision-record",
+    "anonymized": true,
+    "profile": "decision-record",
+    "source_role": "decision-record",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-decision-record",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-purpose"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-decision-record-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-decision-record-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-incident-review",
+    "anonymized": true,
+    "profile": "incident-review",
+    "source_role": "operational-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-incident-review",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-operation"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-incident-review-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-incident-review-source"
+    ]
+  },
+  {
+    "protocol": "context.indexer.authoring-fixture/v1",
+    "id": "anonymous-sessions-test-validation",
+    "anonymized": true,
+    "profile": "test-validation",
+    "source_role": "authoritative-document",
+    "logical_unit_id": "reader-subject",
+    "logical_unit_ref": "node:anonymous-test-validation",
+    "canonical_facts": {
+      "target": {
+        "eligible": true
+      }
+    },
+    "artifact_policy_variant": "standard",
+    "artifacts": [
+      {
+        "artifact_id": "content",
+        "artifact_kind": "content",
+        "purpose": "required",
+        "reader_question_refs": [
+          "question:reader-operation"
+        ],
+        "evidence_refs": [
+          "evidence:anonymous-test-validation-source"
+        ]
+      }
+    ],
+    "evidence_refs": [
+      "evidence:anonymous-test-validation-source"
+    ]
+  }
+]