fix(agents): sync agent.md descriptions with SKILL.md, fix gitignore guidance

.github/agents/pharaoh.activity-diagram-draft.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm.
+description: Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm. Typical ASPICE usage — SWE.3 Software Detailed Design. Renderer tailored via `pharaoh.toml`. Does NOT emit other diagram kinds. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 handoffs: []
 ---
 
 # @pharaoh.activity-diagram-draft
 
-Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm.
+Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm. Typical ASPICE usage — SWE.3 Software Detailed Design. Renderer tailored via `pharaoh.toml`. Does NOT emit other diagram kinds. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 
 See [`skills/pharaoh-activity-diagram-draft/SKILL.md`](../../skills/pharaoh-activity-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.api-coverage-check.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Verify that every public symbol and every raise-site exception in a source file is covered by at least one need in needs.json. Reverse direction of pharaoh-req-from-code — language-parametric via the shared regex table; emits per-symbol and per-raise-site coverage plus a ratio against a tailored threshold.
+description: Use when verifying that a source file is covered by the need catalogue on two axes — (1) at least one CREQ declares the file as its `:source_doc:`, and (2) every project-defined exception class raised in the file is named by some CREQ's title or content. Exception classes not defined in the project source tree (stdlib, third-party deps) are reported as `external` and do not fail the axis. Classifies non-behavioral files (constants, type aliases, bare re-exports) as skipped. Language-parametric via the shared regex table in `skills/shared/public-symbol-patterns.md` (python / rust / typescript / go / c / cpp / java). Single mechanical structural check.
 handoffs: []
 ---
 
 # @pharaoh.api-coverage-check
 
-Verify that every public symbol and every raise-site exception in a source file is covered by at least one need in `needs.json`. Reverse direction of `pharaoh-req-from-code` — language-parametric via the shared regex table in `skills/shared/public-symbol-patterns.md`; emits per-symbol and per-raise-site coverage plus a ratio against a tailored threshold.
+Use when verifying that a source file is covered by the need catalogue on two axes — (1) at least one CREQ declares the file as its `:source_doc:`, and (2) every project-defined exception class raised in the file is named by some CREQ's title or content. Exception classes not defined in the project source tree (stdlib, third-party deps) are reported as `external` and do not fail the axis. Classifies non-behavioral files (constants, type aliases, bare re-exports) as skipped. Language-parametric via the shared regex table in `skills/shared/public-symbol-patterns.md` (python / rust / typescript / go / c / cpp / java). Single mechanical structural check.
 
-See [`skills/pharaoh-api-coverage-check/SKILL.md`](../../skills/pharaoh-api-coverage-check/SKILL.md) for the full atomic specification — inputs, outputs, per-step process, failure modes, and composition patterns.
+See [`skills/pharaoh-api-coverage-check/SKILL.md`](../../skills/pharaoh-api-coverage-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.arch-draft.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Draft a single sphinx-needs architecture element from one parent requirement.
+description: Use when drafting a single sphinx-needs architecture element (component / interface / module) from one parent requirement. Emits an RST directive block linking back to the parent via :satisfies:.
 handoffs: []
 ---
 
 # @pharaoh.arch-draft
 
-Draft a single sphinx-needs architecture element from one parent requirement.
+Use when drafting a single sphinx-needs architecture element (component / interface / module) from one parent requirement. Emits an RST directive block linking back to the parent via :satisfies:.
 
 See [`skills/pharaoh-arch-draft/SKILL.md`](../../skills/pharaoh-arch-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.arch-review.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Audit a single architecture element against ISO 26262-8 §6 axes.
+description: Use when auditing a single architecture element against the 10 ISO 26262-8 §6 axes plus arch-specific axes (traceability back to requirement). Emits structured findings JSON.
 handoffs: []
 ---
 
 # @pharaoh.arch-review
 
-Audit a single architecture element against ISO 26262-8 §6 axes.
+Use when auditing a single architecture element against the 10 ISO 26262-8 §6 axes plus arch-specific axes (traceability back to requirement). Emits structured findings JSON.
 
 See [`skills/pharaoh-arch-review/SKILL.md`](../../skills/pharaoh-arch-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.audit-fanout.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Run a full project audit in parallel across atomic audit skills, sharing findings via Papyrus.
+description: Use when running a full project audit in parallel by dispatching 5 atomic audit skills, each writing findings to a shared Papyrus workspace via pharaoh-finding-record for automatic deduplication. Emits the aggregated deduplicated findings list.
 handoffs: []
 ---
 
 # @pharaoh.audit-fanout
 
-Run a full project audit in parallel across atomic audit skills, sharing findings via Papyrus.
+Use when running a full project audit in parallel by dispatching 5 atomic audit skills, each writing findings to a shared Papyrus workspace via pharaoh-finding-record for automatic deduplication. Emits the aggregated deduplicated findings list.
 
 See [`skills/pharaoh-audit-fanout/SKILL.md`](../../skills/pharaoh-audit-fanout/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.block-diagram-draft.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Use when drafting one SysML-style block diagram — Block Definition Diagram (BDD) showing block structure and composition, or Internal Block Diagram (IBD) showing ports, flows, and part interconnections.
+description: Use when drafting one SysML-style block diagram — Block Definition Diagram (BDD) showing block structure and composition, or Internal Block Diagram (IBD) showing ports, flows, and part interconnections. Typical ASPICE usage — SYS.2/SYS.3 for system-level architecture, and SWE.2 for software architecture on SysML-heavy projects. Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 handoffs: []
 ---
 
 # @pharaoh.block-diagram-draft
 
-Use when drafting one SysML-style block diagram — Block Definition Diagram (BDD) showing block structure and composition, or Internal Block Diagram (IBD) showing ports, flows, and part interconnections.
+Use when drafting one SysML-style block diagram — Block Definition Diagram (BDD) showing block structure and composition, or Internal Block Diagram (IBD) showing ports, flows, and part interconnections. Typical ASPICE usage — SYS.2/SYS.3 for system-level architecture, and SWE.2 for software architecture on SysML-heavy projects. Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 
 See [`skills/pharaoh-block-diagram-draft/SKILL.md`](../../skills/pharaoh-block-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.bootstrap.agent.md

@@ -1,5 +1,5 @@
 ---
-description: Inject minimum sphinx-needs configuration into an existing Sphinx project so sphinx-build produces a valid needs.json.
+description: Use when a Sphinx project has no sphinx-needs configured and you need minimum viable scaffolding — adding the extension and declaring need types — so that sphinx-build produces a valid needs.json for downstream Pharaoh skills.
 handoffs:
   - label: Detect and scaffold Pharaoh
     agent: pharaoh.setup
@@ -8,6 +8,6 @@ handoffs:
 
 # @pharaoh.bootstrap
 
-Inject the minimum sphinx-needs configuration — extension entry, need types, optional extra links — into an existing Sphinx project that does not yet have sphinx-needs configured. Does not seed RST content, does not build, does not write `pharaoh.toml`.
+Use when a Sphinx project has no sphinx-needs configured and you need minimum viable scaffolding — adding the extension and declaring need types — so that sphinx-build produces a valid needs.json for downstream Pharaoh skills.
 
 See [`skills/pharaoh-bootstrap/SKILL.md`](../../skills/pharaoh-bootstrap/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.change.agent.md

@@ -1,5 +1,5 @@
 ---
-description: Analyze the impact of changing a requirement, specification, or any sphinx-needs item. Traces through all link types and codelinks to produce a Change Document.
+description: Use when analyzing the impact of changing a requirement, specification, or any sphinx-needs item, including traceability to code via codelinks
 handoffs:
   - label: MECE Check
     agent: pharaoh.mece

.github/agents/pharaoh.class-diagram-draft.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Use when drafting one class diagram showing a bounded set of types/entities with their fields, methods, and relationships (inheritance, composition, aggregation, association).
+description: Use when drafting one class diagram showing a bounded set of types/entities with their fields, methods, and relationships (inheritance, composition, aggregation, association). Renderer tailored via `pharaoh.toml`. Does NOT emit component, sequence, or state diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 handoffs: []
 ---
 
 # @pharaoh.class-diagram-draft
 
-Use when drafting one class diagram showing a bounded set of types/entities with their fields, methods, and relationships (inheritance, composition, aggregation, association).
+Use when drafting one class diagram showing a bounded set of types/entities with their fields, methods, and relationships (inheritance, composition, aggregation, association). Renderer tailored via `pharaoh.toml`. Does NOT emit component, sequence, or state diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 
 See [`skills/pharaoh-class-diagram-draft/SKILL.md`](../../skills/pharaoh-class-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.component-diagram-draft.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Use when drafting one component-relationship diagram (nodes = sphinx-needs, edges = link relations) for a bounded scope — one feature, one module, one architectural view.
+description: Use when drafting one component-relationship diagram (nodes = sphinx-needs, edges = link relations) for a bounded scope — one feature, one module, one architectural view. Renderer tailored via `pharaoh.toml`. Does NOT emit sequence, class, or state diagrams — those are separate skills. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 handoffs: []
 ---
 
 # @pharaoh.component-diagram-draft
 
-Use when drafting one component-relationship diagram (nodes = sphinx-needs, edges = link relations) for a bounded scope — one feature, one module, one architectural view.
+Use when drafting one component-relationship diagram (nodes = sphinx-needs, edges = link relations) for a bounded scope — one feature, one module, one architectural view. Renderer tailored via `pharaoh.toml`. Does NOT emit sequence, class, or state diagrams — those are separate skills. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 
 See [`skills/pharaoh-component-diagram-draft/SKILL.md`](../../skills/pharaoh-component-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.context-gather.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Retrieve rationale memories from a Papyrus workspace before authoring or review.
+description: Use when retrieving rationale memories relevant to an authoring context from a Papyrus workspace, before invoking any draft or review skill. Returns a structured list of memories (memory_id, text, relevance_score). Does NOT draft, review, or modify artefacts.
 handoffs: []
 ---
 
 # @pharaoh.context-gather
 
-Retrieve rationale memories from a Papyrus workspace before authoring or review.
+Use when retrieving rationale memories relevant to an authoring context from a Papyrus workspace, before invoking any draft or review skill. Returns a structured list of memories (memory_id, text, relevance_score). Does NOT draft, review, or modify artefacts.
 
 See [`skills/pharaoh-context-gather/SKILL.md`](../../skills/pharaoh-context-gather/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.coverage-gap.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Detect one gap category (orphan / unverified / duplicate / contradictory / lifecycle) in a sphinx-needs corpus.
+description: Use when detecting one gap category (orphan / unverified / duplicate / contradictory / lifecycle / ...) in a sphinx-needs corpus. Returns ordered list of needs falling into that gap.
 handoffs: []
 ---
 
 # @pharaoh.coverage-gap
 
-Detect one gap category (orphan / unverified / duplicate / contradictory / lifecycle) in a sphinx-needs corpus.
+Use when detecting one gap category (orphan / unverified / duplicate / contradictory / lifecycle / ...) in a sphinx-needs corpus. Returns ordered list of needs falling into that gap.
 
 See [`skills/pharaoh-coverage-gap/SKILL.md`](../../skills/pharaoh-coverage-gap/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.decide.agent.md

@@ -1,5 +1,5 @@
 ---
-description: Record a design decision as a traceable sphinx-needs object with alternatives, rationale, and links to affected requirements.
+description: Use when recording a design decision as a traceable sphinx-needs object with alternatives, rationale, and links to affected requirements
 handoffs:
   - label: Trace Decision
     agent: pharaoh.trace

.github/agents/pharaoh.decision-record.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Record a canonical decision, fact, or preference in the shared Papyrus workspace with (type, canonical_name) dedup.
+description: Use when recording a canonical decision, fact, or preference in the shared Papyrus workspace with automatic dedup on (type, canonical_name). Returns {action: wrote|duplicate, papyrus_id}. Generalizes pharaoh-finding-record beyond audit findings.
 handoffs: []
 ---
 
 # @pharaoh.decision-record
 
-Record a canonical decision, fact, or preference in the shared Papyrus workspace with (type, canonical_name) dedup.
+Use when recording a canonical decision, fact, or preference in the shared Papyrus workspace with automatic dedup on (type, canonical_name). Returns {action: wrote|duplicate, papyrus_id}. Generalizes pharaoh-finding-record beyond audit findings.
 
 See [`skills/pharaoh-decision-record/SKILL.md`](../../skills/pharaoh-decision-record/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.decision-review.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Audit a single recorded decision against context/alternatives/consequences structure and traceability.
+description: Use when auditing a single recorded decision (DR / ADR / design note) against the generic decision review axes in `shared/checklists/decision.md`. Checks context/alternatives/consequences structure, traceability to affected artefacts, rationale completeness. Emits structured findings JSON.
 handoffs: []
 ---
 
 # @pharaoh.decision-review
 
-Audit a single recorded decision against context/alternatives/consequences structure and traceability.
+Use when auditing a single recorded decision (DR / ADR / design note) against the generic decision review axes in `shared/checklists/decision.md`. Checks context/alternatives/consequences structure, traceability to affected artefacts, rationale completeness. Emits structured findings JSON.
 
-See [`skills/pharaoh-decision-review/SKILL.md`](../../skills/pharaoh-decision-review/SKILL.md) for the full atomic specification.
+See [`skills/pharaoh-decision-review/SKILL.md`](../../skills/pharaoh-decision-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.deployment-diagram-draft.agent.md

@@ -1,10 +1,10 @@
 ---
-description: Use when drafting one deployment diagram showing physical nodes (ECUs, servers, boards), the software artefacts deployed on each, and communication channels (buses, networks).
+description: Use when drafting one deployment diagram showing physical nodes (ECUs, servers, boards), the software artefacts deployed on each, and communication channels (buses, networks). Typical ASPICE usage — SYS.3 System Architectural Design; essential for automotive HW/SW allocation per ISO 26262 Part 5 (HW) and Part 6 (SW). Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 handoffs: []
 ---
 
 # @pharaoh.deployment-diagram-draft
 
-Use when drafting one deployment diagram showing physical nodes (ECUs, servers, boards), the software artefacts deployed on each, and communication channels (buses, networks).
+Use when drafting one deployment diagram showing physical nodes (ECUs, servers, boards), the software artefacts deployed on each, and communication channels (buses, networks). Typical ASPICE usage — SYS.3 System Architectural Design; essential for automotive HW/SW allocation per ISO 26262 Part 5 (HW) and Part 6 (SW). Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented).
 
 See [`skills/pharaoh-deployment-diagram-draft/SKILL.md`](../../skills/pharaoh-deployment-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.

.github/agents/pharaoh.diagram-lint.agent.md

@@ -1,5 +1,5 @@
 ---
-description: Walk a directory of RST files and check every `.. mermaid::` / `.. uml::` block against the real renderer parser (mmdc, plantuml). Catches silent parse failures that sphinx-build misses.
+description: Use when running a terminal validation step over a directory of RST files to catch Mermaid / PlantUML parse failures that sphinx-build cannot detect. Extracts every `.. mermaid::` and `.. uml::` block and pipes it to the real renderer parser (mmdc / plantuml -checkonly). Returns structured findings. Does NOT modify the RST files.
 handoffs:
   - label: Aggregate into quality gate
     agent: pharaoh.quality-gate
@@ -8,6 +8,6 @@ handoffs:
 
 # @pharaoh.diagram-lint
 
-Walk a directory of RST files, extract every Mermaid / PlantUML block, and parse each block with the real renderer CLI (`mmdc -i tmp.mmd -o /dev/null`, `plantuml -checkonly`). Emits structured findings. Read-only — does not modify RST. When a renderer CLI is unavailable, degrades gracefully with a warning and install command.
+Use when running a terminal validation step over a directory of RST files to catch Mermaid / PlantUML parse failures that sphinx-build cannot detect. Extracts every `.. mermaid::` and `.. uml::` block and pipes it to the real renderer parser (mmdc / plantuml -checkonly). Returns structured findings. Does NOT modify the RST files.
 
 See [`skills/pharaoh-diagram-lint/SKILL.md`](../../skills/pharaoh-diagram-lint/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns.