@geraldmaron/construct 1.0.0 → 1.0.2

package/skills/ai/prompt-optimizer.md

@@ -1,12 +1,12 @@
 <!--
 skills/ai/prompt-optimizer.md — Closed-loop prompt auto-optimization guide.
 
-Uses Langfuse traces and quality scores as the feedback signal, Claude as the optimizer,
+Uses telemetry traces and quality scores as the feedback signal, Claude as the optimizer,
 and the agent registry + construct sync as the deployment layer.
 -->
 # Prompt Auto-Optimization Loop
 
-Construct's prompt improvement system uses Langfuse traces and quality scores as the feedback signal, Claude as the optimizer, and the agent registry (`agents/registry.json`) as the deployment layer. This is a closed loop: production data → failure analysis → improved prompt → staging → promotion.
+Construct's prompt improvement system uses telemetry traces and quality scores as the feedback signal, Claude as the optimizer, and the agent registry (`agents/registry.json`) as the deployment layer. This is a closed loop: production data → failure analysis → improved prompt → staging → promotion.
 
 ## Running the optimizer
 
@@ -36,16 +36,16 @@ The optimizer requires Python 3.12+ (`pip3` must be available). It will auto-ins
 
 Retrieve the current production prompt for the target agent from `agents/registry.json` (or the corresponding `promptFile` if using extracted prompts).
 
-Then retrieve recent traces via the Langfuse REST API:
+Then retrieve recent traces via the telemetry backend REST API:
 
 ```
-GET {LANGFUSE_BASEURL}/api/public/traces?tags={agentName}&limit=50
-# Auth: Basic base64(LANGFUSE_PUBLIC_KEY:LANGFUSE_SECRET_KEY)
+GET {CONSTRUCT_TELEMETRY_URL}/api/public/traces?tags={agentName}&limit=50
+# Auth: Basic base64(CONSTRUCT_TELEMETRY_PUBLIC_KEY:CONSTRUCT_TELEMETRY_SECRET_KEY)
 ```
 
 To fetch quality scores for traces:
 ```
-GET {LANGFUSE_BASEURL}/api/public/scores?traceId={id}&name=quality
+GET {CONSTRUCT_TELEMETRY_URL}/api/public/scores?traceId={id}&name=quality
 ```
 
 Filter to scores where `value < 0.7`. For each low-scoring trace, extract: the prompt used, the user input, the model output, the quality score, and any human comments.
@@ -110,5 +110,5 @@ Run `cx-trace-reviewer` after every promotion. If the newly promoted prompt show
 
 ## What this does not replace
 
-- **DSPy**: If you need algorithmic optimization over large datasets with measurable metrics (classification, structured output), DSPy is the right tool and integrates with Langfuse for tracing. This skill is for natural-language agent prompts where the metric is quality score.
+- **DSPy**: If you need algorithmic optimization over large datasets with measurable metrics (classification, structured output), DSPy is the right tool and integrates with telemetry backend for tracing. This skill is for natural-language agent prompts where the metric is quality score.
 - **Human review**: Always read the generated prompt before pushing to staging. The LLM optimizer can introduce subtle regressions. Automated promotion should only happen after confirming the diff makes sense.

package/skills/compliance/ai-disclosure.md

@@ -0,0 +1,58 @@
+<!--
+skills/compliance/ai-disclosure.md — AI Disclosure — AI transparency, disclosure, and regulatory compliance.
+
+Use this skill when reviewing AI features for disclosure requirements, transparency obligations, or emerging AI regulation compliance.
+-->
+# AI Disclosure
+
+Use this skill when reviewing AI features for disclosure requirements, transparency obligations, or emerging AI regulation compliance.
+
+## Disclosure Requirements
+
+### When AI generates or modifies content
+
+- Disclose that content was AI-generated or AI-assisted
+- Label AI outputs clearly in the UI (e.g., "Generated by AI", "AI-assisted")
+- Do not present AI-generated content as human-authored without disclosure
+
+### When AI makes or influences decisions
+
+- Document the decision criteria and model inputs
+- Provide a mechanism for human review of consequential decisions
+- Log the model version, prompt template, and confidence score for audit
+
+### When AI processes personal data
+
+- Include AI processing in the privacy notice
+- Obtain specific consent for automated decision-making under GDPR Art. 22
+- Provide the right to obtain human intervention, express a point of view, and contest the decision
+
+## Regulatory Landscape
+
+| Regulation | Scope | Key Requirement |
+|------------|-------|-----------------|
+| EU AI Act | EU market | Risk classification, transparency obligations, conformity assessment for high-risk |
+| GDPR Art. 22 | EU residents | Right not to be subject to solely automated decisions with legal effects |
+| NYC Local Law 144 | NYC employers | Bias audit for automated employment decision tools |
+| Colorado AI Act | Colorado consumers | Disclosure of high-risk AI decisions, impact assessments |
+| Canada AIDA (proposed) | Canada | Transparency, bias mitigation, human oversight for high-impact systems |
+
+## Code Review Triggers
+
+- AI features that influence hiring, lending, insurance, or housing decisions (high-risk under EU AI Act)
+- Chatbots or virtual agents without clear "you are talking to AI" disclosure
+- AI-generated recommendations presented without provenance markers
+- Model outputs stored without version tracking or audit trail
+- Automated content moderation without human appeal mechanism
+- Training on user data without explicit consent or opt-out
+
+## Risk Assessment Template
+
+For each AI feature, document:
+1. **Purpose**: what the AI does and why
+2. **Data inputs**: what data the model receives
+3. **Risk tier**: minimal, limited, high, unacceptable (per EU AI Act)
+4. **Disclosure mechanism**: how users are informed
+5. **Human oversight**: who reviews AI decisions and how
+6. **Bias mitigation**: what testing was done for fairness
+7. **Audit trail**: what is logged for post-hoc review

package/skills/compliance/data-privacy.md

@@ -0,0 +1,46 @@
+<!--
+skills/compliance/data-privacy.md — Data Privacy — GDPR, CCPA, and data protection compliance patterns.
+
+Use this skill when reviewing data collection, storage, processing, or retention for privacy regulation compliance.
+-->
+# Data Privacy
+
+Use this skill when reviewing data collection, storage, processing, or retention for privacy regulation compliance.
+
+## Data Classification
+
+| Category | Examples | Handling |
+|----------|----------|----------|
+| PII | Name, email, phone, address, IP | Encrypt at rest, minimize collection |
+| Sensitive PII | SSN, financial data, health data, biometrics | Encrypt + access control + audit log |
+| Pseudonymous | Hashed identifiers, device IDs, session tokens | Still personal data under GDPR |
+| Anonymous | Aggregated statistics with k-anonymity | Generally exempt |
+
+## Privacy by Design Checklist
+
+- [ ] Data minimization: collect only what is necessary for the stated purpose
+- [ ] Purpose limitation: document why each data field is collected
+- [ ] Storage limitation: define retention periods and auto-deletion schedules
+- [ ] Lawful basis: identify legal basis for each processing activity (consent, contract, legitimate interest)
+- [ ] Data subject rights: implement access, rectification, erasure, portability, and objection endpoints
+- [ ] Cross-border transfers: verify adequacy decisions or standard contractual clauses for international data flows
+- [ ] Breach notification: document the process for 72-hour supervisory authority notification
+
+## Code Review Triggers
+
+Flag these patterns in code:
+
+- Logging PII to stdout, application logs, or third-party analytics
+- Storing PII in plain text without encryption
+- Passing PII in URL query parameters
+- Retaining data beyond the documented retention period
+- Third-party SDK calls that transmit user data without documented DPA
+- Cookie or tracking pixel placement without consent management
+- Email addresses used as primary keys (makes deletion cascades hard)
+
+## Regulation Quick Reference
+
+- **GDPR**: EU residents. Consent must be freely given, specific, informed, unambiguous. Right to erasure is absolute for consent-based processing.
+- **CCPA/CPRA**: California residents. Right to know, delete, opt-out of sale/sharing. 12-month lookback on data collection.
+- **LGPD**: Brazil. Similar to GDPR. Requires a DPO and legal basis for processing.
+- **PIPEDA**: Canada. Consent required for collection, use, and disclosure. Reasonable purpose test applies.

package/skills/compliance/license-audit.md

@@ -0,0 +1,40 @@
+<!--
+skills/compliance/license-audit.md — License Audit — Dependency license review and open-source compliance.
+
+Use this skill when auditing dependency licenses, evaluating OSS compliance risk, or preparing license inventories for legal review.
+-->
+# License Audit
+
+Use this skill when auditing dependency licenses, evaluating OSS compliance risk, or preparing license inventories for legal review.
+
+## License Classification
+
+| Risk Tier | Licenses | Action |
+|-----------|----------|--------|
+| Permissive | MIT, BSD-2, BSD-3, ISC, Apache-2.0, Unlicense | Safe for most uses |
+| Weak copyleft | LGPL-2.1, LGPL-3.0, MPL-2.0, EPL-2.0 | Review linking model |
+| Strong copyleft | GPL-2.0, GPL-3.0, AGPL-3.0 | Legal review required |
+| Non-commercial | CC-BY-NC, SSPL, BSL, Elastic-2.0 | Block for commercial use |
+| Unknown/Custom | No SPDX identifier, custom terms | Manual review required |
+
+## Audit Process
+
+1. Generate SBOM: use `npm list --all --json`, `pip licenses`, `cargo license`, or equivalent
+2. Identify every direct and transitive dependency
+3. Map each dependency to its SPDX license identifier
+4. Flag any dependency without a clear license file as unknown-risk
+5. Check for license changes between pinned versions and latest
+6. Look past layer one — transitive copyleft taints the whole tree
+
+## Red Flags
+
+- AGPL-3.0 in any network-exposed service dependency
+- GPL in a library linked into proprietary code without a linking exception
+- Mixed licensing where copyleft and proprietary code share a compilation unit
+- Dependencies that changed from permissive to restrictive between versions
+- "License: SEE LICENSE IN ..." with no actual license file present
+- Dual-licensed packages where the free option is copyleft
+
+## Deliverable
+
+Produce a license inventory table: dependency name, version, license SPDX, risk tier, notes. Flag every non-permissive entry with a recommended action (accept, replace, seek exception, or block).

package/skills/compliance/regulatory-review.md

@@ -0,0 +1,61 @@
+<!--
+skills/compliance/regulatory-review.md — Regulatory Review — Pre-ship compliance review checklist and process.
+
+Use this skill when conducting a compliance review before shipping features that handle user data, financial transactions, AI decisions, or regulated content.
+-->
+# Regulatory Review
+
+Use this skill when conducting a compliance review before shipping features that handle user data, financial transactions, AI decisions, or regulated content.
+
+## Pre-Ship Compliance Checklist
+
+### Data handling
+
+- [ ] All personal data fields documented with purpose and legal basis
+- [ ] Retention periods defined and enforced
+- [ ] Encryption at rest and in transit for sensitive data
+- [ ] Data subject rights endpoints implemented and tested
+- [ ] Cross-border data transfer mechanisms in place
+
+### Licensing
+
+- [ ] Dependency license audit completed (no copyleft surprises)
+- [ ] Third-party SDK terms reviewed for data sharing obligations
+- [ ] Attribution requirements satisfied for open-source dependencies
+
+### AI features
+
+- [ ] AI disclosure in place for all AI-generated content
+- [ ] High-risk AI decisions have human oversight mechanism
+- [ ] Model version and prompt tracked for audit
+- [ ] Bias testing completed for consequential decisions
+
+### Security
+
+- [ ] Authentication and authorization tested
+- [ ] Input validation on all user-facing endpoints
+- [ ] No hardcoded secrets in source code
+- [ ] Security headers configured (CSP, HSTS, etc.)
+
+### Accessibility
+
+- [ ] WCAG 2.1 AA compliance for public-facing surfaces
+- [ ] Screen reader and keyboard navigation tested
+
+## Review Process
+
+1. **Inventory**: list all data types collected, stored, or processed by the feature
+2. **Classify**: map each data type to a regulation (GDPR, CCPA, HIPAA, PCI-DSS, etc.)
+3. **Gap analysis**: compare current implementation against regulatory requirements
+4. **Remediation**: fix gaps before shipping, document accepted risks
+5. **Evidence**: collect audit evidence (test results, screenshots, config exports)
+6. **Sign-off**: document the reviewer, date, and scope of the review
+
+## Common Compliance Gaps
+
+- Terms of service not updated to reflect new data processing
+- Cookie consent banner missing for new tracking mechanisms
+- Data processing agreement not in place for new third-party vendor
+- Privacy policy silent on AI processing activities
+- Deletion endpoint that soft-deletes but never hard-deletes
+- Backup retention that exceeds the documented data retention period

package/skills/docs/document-ingest-workflow.md

@@ -0,0 +1,52 @@
+<!--
+skills/docs/document-ingest-workflow.md — Convert source documents into retrieval-ready markdown artifacts.
+-->
+# Document Ingest Workflow
+
+Use when: the user points at a PDF, Word doc, spreadsheet, slide deck, export, or mixed document folder and wants a markdown version that Construct can search efficiently later.
+
+## Preferred tools
+
+1. `construct ingest <path>` for CLI-driven conversion.
+2. `ingest_document` over Construct MCP when the host supports MCP tools.
+3. `extract_document_text` only when the user wants raw extracted text without writing a markdown artifact.
+
+## Default destination
+
+Write outputs to `.cx/knowledge/internal/` unless the user explicitly wants a typed `knowledge/<subdir>`, sibling markdown file, or another output path.
+
+Why:
+
+- files under `.cx/knowledge/` are part of Construct's file-state retrieval path
+- they can be picked up by hybrid search immediately
+- `construct ingest --sync` can then push them into shared SQL/vector storage when configured
+
+## Supported source types
+
+- PDF
+- DOC and DOCX
+- XLS, XLSX, CSV, TSV, ODS, Numbers
+- PPT, PPTX, Keynote
+- ODT, RTF
+- text, markdown, HTML, XML, JSON, YAML, and other plain-text project artifacts
+
+## Workflow
+
+1. Ingest the source into markdown.
+2. Preserve source metadata: original path, extension, extraction method, timestamp, truncation state.
+3. Keep the markdown normalized and readable; do not invent structure beyond headings and metadata.
+4. If the document informs product decisions, promote the result into an evidence brief or PRD input using the evidence-ingest workflow.
+5. If shared storage is configured and the material should be semantically retrievable across sessions, run with `--sync`.
+
+## Examples
+
+```bash
+construct ingest ./docs/vendor/quarterly-review.pdf
+construct ingest ./research-drop --sync
+construct ingest ./deck.pptx --target=sibling
+construct ingest ./data/export.xlsx --out=./notes/export.md
+```
+
+## Rules
+
+Do not overwrite an existing markdown artifact unless the user explicitly asks for replacement. Prefer creating a suffixed filename instead. Keep original source files untouched.

package/skills/docs/evidence-ingest-workflow.md

@@ -5,6 +5,8 @@ skills/docs/evidence-ingest-workflow.md — Normalize raw product evidence into
 
 Use when: the user pastes customer notes, Slack threads, support tickets, sales notes, research snippets, RFCs, analytics summaries, or competitor signals.
 
+Follow [rules/common/research.md](../../rules/common/research.md) for source metadata, evidence handling, and confidence labeling.
+
 ## Steps
 
 1. Identify the source type and date.
@@ -18,6 +20,13 @@ Use when: the user pastes customer notes, Slack threads, support tickets, sales
 
 Do not invent customer quotes, names, or issue links. Preserve ambiguity. If source evidence contains personal data, record only the minimum needed for product decisions.
 
+Always preserve:
+
+- source path or source system
+- source date or access date
+- whether the source is direct evidence or secondhand summary
+- what is observed directly vs inferred by the author
+
 ## Storage
 
 Files in `.cx/product-intel/` are indexed by Construct's hybrid retrieval path. Postgres stores them as `product-intel` documents during sync, and the vector layer makes them semantically retrievable for future PRDs and Meta PRDs.

package/skills/docs/init-docs.md

@@ -1,5 +1,5 @@
 <!--
-skills/docs/init-docs.md — Skill: init-docs — Initialize Project Documentation Structure — `init docs`, `create docs structure`, `set up documentation`, `docs scaffold`, `
+skills/docs/init-docs.md — Skill: init-docs — Initialize Project Documentation Structure — `init docs`, `create docs structure`, `set up documentation`, `docs scaffold`, `documentation init`
 
 ## Trigger keywords `init docs`, `create docs structure`, `set up documentation`, `docs scaffold`, `documentation init`
 -->
@@ -19,16 +19,16 @@ When invoked, gather the user's intent and create a tailored documentation direc
 Ask the user **all at once** (single message, not one at a time):
 
 1. **What is this project?** A brief description (one sentence is fine)
-2. **What doc types will you have?** Examples: architecture decisions, API reference, runbooks, user guides, changelogs, onboarding guides, RFCs, design docs, data models, deployment guides
+2. **What doc types will you have?** See the lane table below for options
 3. **Who is the audience?** Engineers, external users, both, or internal team only
-4. **Tech stack?** (affects whether API reference sections are needed)
+4. **Tech stack?** (affects whether API reference or RFC sections are needed)
 5. **Monorepo or single-service?** Affects directory depth
 
 ---
 
 ## Step 2 — Generate the structure
 
-Based on answers, create the `docs/` directory and appropriate subdirectories. Use this as a base — add or remove sections based on the user's answers:
+Based on answers, create the `docs/` directory and appropriate subdirectories. Use this as a base — add or remove sections based on the user's answers.
 
 ### Core structure (always include)
 
@@ -43,19 +43,50 @@ docs/
 └── workflow.json              # Canonical workflow/task state
 ```
 
-### Add based on doc types mentioned
+## Interactive UX (TTY)
 
-| Doc type mentioned | Create |
-|-------------------|--------|
-| Architecture / design | `docs/architecture/` with `overview.md` skeleton |
-| API reference | `docs/api/` with `README.md` skeleton |
-| Runbooks / ops | `docs/runbooks/` with `README.md` + `incident-response.md` skeleton |
-| Onboarding | `docs/onboarding/` with `README.md` + `local-setup.md` skeleton |
-| Changelog / releases | `docs/releases/` with `README.md` if the user explicitly wants public release history |
-| RFCs | `docs/rfcs/` with `README.md` + `0001-template.md` |
-| Data models | `docs/data-models/` with `README.md` skeleton |
-| User guides | `docs/guides/` with `README.md` skeleton |
-| Deployment | `docs/deployment/` with `README.md` + `environments.md` |
+When run interactively, `construct init-docs` renders a keyboard-driven **full-screen checkbox picker** — all available lanes listed with the default set pre-checked and context-suggested lanes highlighted in the UI. No typing required.
+
+- **↑ / ↓** — move cursor (details shown in a dedicated panel)
+- **Space** — toggle lane on/off
+- **a** — toggle all on/off
+- **Enter** — confirm and scaffold
+- Follow-up choices use the same menu pattern instead of free-text answers
+
+If the user selects the `intake` lane, `construct init-docs` should also create `.cx/inbox/`. Both `.cx/inbox/` and `docs/intake/` act as drop zones for ingestable files, while `docs/intake/` also serves as the durable paper trail lane.
+
+When run non-interactively (`--yes` or piped stdin), the lean default set is used unless `--docs=` is supplied. `--docs=lean|product|full` or `--docs=adrs,prds,rfcs` both work.
+
+---
+
+### Available lanes
+
+| Lane         | Directory       | What goes here |
+|--------------|-----------------|----------------|
+| adrs         | `docs/adr/`         | Architecture decisions that have already been made |
+| briefs       | `docs/briefs/`      | Research, evidence, signals, one-pagers, customer profiles |
+| changelogs   | `docs/changelogs/`  | User-facing release notes and version history entries |
+| intake       | `docs/intake/`      | Intake batch records that explain what arrived, why it matters, and how it should be ingested |
+| memos        | `docs/memos/`       | Decision memos and internal arguments for alignment |
+| meetings     | `docs/meetings/`    | Meeting notes, minutes, standups, retros, agendas, and session summaries |
+| notes        | `docs/notes/`       | Working notes and lightweight durable context outside formal docs or meetings |
+| onboarding   | `docs/onboarding/`  | Runnable setup guides and first-day workflows |
+| postmortems  | `docs/postmortems/` | Blameless incident reports with root cause and corrective actions |
+| prds         | `docs/prds/`        | Product and capability requirement documents |
+| rfcs         | `docs/rfcs/`        | Architecture and implementation proposals needing review |
+| runbooks     | `docs/runbooks/`    | Operational procedures, diagnostics, escalation paths |
+
+### Guidance: which lanes to suggest
+
+| Signal in the project | Suggest |
+|-----------------------|---------|
+| Has `Dockerfile`, `.github/`, `deploy/`, or `infra/` | runbooks, postmortems |
+| Has `CHANGELOG.md` or release tagging | changelogs |
+| Has `onboarding/`, `setup/`, or `getting-started/` | onboarding |
+| Has meeting minutes, agendas, retros, or standups | meetings |
+| Has `src/`, `lib/`, `api/`, or `services/` | rfcs |
+| Has research, customer, or market files | briefs |
+| Any project with decisions and requirements | adrs, prds (always lean default) |
 
 ---
 
@@ -120,7 +151,7 @@ Last updated: [date]
 
 ## Key decisions
 
-Link to `.cx/decisions/` or the canonical project decision log used in this repo.
+Link to `docs/adr/` or the canonical project decision log used in this repo.
 ```
 
 ---
@@ -156,5 +187,7 @@ Stack: [stack]
 
 After completing the docs init:
 - If the user has architecture questions → `@cx-explorer` or `@cx-docs-keeper` to explore and update `docs/architecture/`
-- If the user wants to document a decision → record it in `.cx/decisions/` or the repo's canonical decision log
+- If the user wants to document a decision → record it in `docs/adr/` using the ADR template
 - If the user wants to add API docs → `@cx-docs-keeper` to generate stubs from code
+- If the user wants to file an incident report → use `docs/postmortems/` with the incident-report template
+- If the user wants to document a release → use `docs/changelogs/` with the changelog-entry template

package/skills/docs/product-intelligence-workflow.md

@@ -8,6 +8,8 @@ customer profiles, and backlog proposals without creating a separate sidecar sys
 
 Use when: the request involves customer evidence, PM synthesis, product requirements, PRDs, PRFAQs, customer profiles, product signals, or backlog proposals.
 
+Follow [rules/common/research.md](../../rules/common/research.md) for source order, verification, confidence, and reproducibility.
+
 ## Operating model
 
 Product Intelligence is a Construct-native loop:
@@ -20,6 +22,14 @@ Product Intelligence is a Construct-native loop:
 6. Gate external writes and approved-doc status through the primary persona.
 7. Sync searchable artifacts through the hybrid file/Postgres/vector storage path.
 
+## Source order
+
+1. Existing internal evidence: customer profiles, evidence briefs, signal briefs, prior PRDs, prior research, ingested docs
+2. Raw source material: notes, transcripts, tickets, exported docs, spreadsheets, decks
+3. External corroboration when needed: official product docs, vendor docs, public changelogs, source code, standards
+
+Do not skip prior internal evidence when drafting a new product artifact.
+
 ## PM flavor selection
 
 - **product**: user workflow, adoption, JTBD, UX surface, success metrics.
@@ -60,3 +70,5 @@ Stop and ask the primary persona before:
 ## Quality bar
 
 Product Intelligence output must cite evidence, distinguish observation from inference, name confidence, and avoid a wall of bullets. Keep em dashes rare. Use paragraphs for reasoning, tables for comparisons, and bullets for scanability.
+
+For time-sensitive or externally sourced claims, include the date basis. For load-bearing claims, prefer two independent sources unless one authoritative primary source is enough.

package/skills/docs/product-signal-workflow.md

@@ -5,6 +5,8 @@ skills/docs/product-signal-workflow.md — Synthesize product signals from evide
 
 Use when: the user asks what customers are asking for, what themes are emerging, whether evidence is strong enough, or what should become a PRD.
 
+Follow [rules/common/research.md](../../rules/common/research.md) for confidence, contradictions, and source handling.
+
 ## Steps
 
 1. Gather relevant evidence briefs, customer profiles, notes, tickets, research, and product docs.
@@ -25,3 +27,5 @@ Default threshold for PRD-ready evidence: at least two independent customers, th
 ## Quality bar
 
 Separate asks from requirements. Separate observation from inference. Name what evidence would change the recommendation.
+
+When a claim depends on time-sensitive or external information, include the date or version basis. If evidence conflicts, state the counter-signal explicitly instead of averaging it away.

package/skills/docs/research-workflow.md

@@ -7,19 +7,34 @@ Use when: the user asks to research a topic, investigate a question, or gather e
 
 Use when: the user asks to research a topic, investigate a question, or gather evidence for a decision.
 
+Follow [rules/common/research.md](../../rules/common/research.md) as the default policy.
+
 ## Steps
 
-1. **Clarify the question** — one specific question the research must answer
-2. **Run cx-researcher or cx-docs-researcher** — use the appropriate agent:
-   - Library/API/framework questions → cx-docs-researcher
-   - Market, competitive, general evidence → cx-researcher
-3. **Structure findings** using the template from `get_template("research-brief")` — resolves `.cx/templates/docs/research-brief.md` (override) then `templates/docs/research-brief.md` (shipped)
-4. **Write to `.cx/research/{topic-slug}.md`** — cx-docs-keeper owns this
-5. **Reference the research doc** in the requesting agent's output (link by path)
+1. **Clarify the question** — one specific, falsifiable question the research must answer.
+2. **Check internal evidence first** — search `.cx/research/`, `.cx/product-intel/`, `docs/prd/`, `docs/meta-prd/`, ADRs, runbooks, and ingested artifacts before going external.
+3. **Choose the research path**:
+   - Library/API/framework/version questions → primary vendor docs, source code, changelogs, exact-version references
+   - Market, competitive, policy, or general evidence → cx-researcher using primary sources first
+4. **Use a source hierarchy**:
+   - Primary: official docs, exact-version API references, standards, source code
+   - Secondary: changelogs, migration guides, maintainer issue comments
+   - Tertiary: blogs/forums/Q&A only to locate primaries
+5. **Structure findings** using the template from `get_template("research-brief")` — resolves `.cx/templates/docs/research-brief.md` (override) then `templates/docs/research-brief.md` (shipped)
+6. **Write to `.cx/research/{topic-slug}.md`** — cx-docs-keeper owns this
+7. **Reference the research doc** in the requesting agent's output (link by path)
+
+## Verification bar
+
+- Every load-bearing claim must cite a source path, URL, or document reference.
+- Record publication date, version, or access date for each source.
+- Separate observation from inference.
+- Name contradictions and unresolved gaps.
+- Prefer two independent sources per load-bearing claim unless one authoritative primary source is sufficient.
 
 ## File naming
 - Topic slug: lowercase, hyphens, no spaces — e.g., `firebase-auth-v9-migration.md`
-- Date prefix for time-sensitive research: `2026-04-langfuse-v2-vs-v3.md`
+- Date prefix for time-sensitive research: `2026-04-release-comparison.md`
 
 ## When research feeds a decision
 → Also create `.cx/decisions/ADR-{NNN}-{slug}.md` referencing the research doc

package/skills/docs/runbook-workflow.md

@@ -15,7 +15,7 @@ Use when: creating operational procedures for services, alerts, or recurring ope
 4. **cx-docs-keeper** adds to `.cx/context.md` if it's a critical path runbook
 
 ## File naming
-- `docs/runbooks/langfuse-restart.md`
+- `docs/runbooks/telemetry-restart.md`
 - `docs/runbooks/db-migration.md`
 - `docs/runbooks/incident-response.md`