@plures/praxis 1.2.12 → 1.2.41

package/dist/node/{reactive-engine.svelte-CRNqHlbv.d.ts → reactive-engine.svelte-CGe8SpVE.d.cts}

@@ -1,4 +1,4 @@
-import { P as PraxisState, a as PraxisEvent, b as PraxisFact, c as PraxisStepResult, d as PraxisStepConfig } from './protocol-Qek7ebBl.js';
+import { P as PraxisState, a as PraxisEvent, b as PraxisFact, c as PraxisStepResult, d as PraxisStepConfig, e as PraxisDiagnostics } from './protocol-BocKczNv.cjs';
 
 /**
  * Decision Ledger - Contract Types
@@ -209,6 +209,18 @@ interface RuleDescriptor<TContext = unknown> {
     description: string;
     /** Implementation function */
     impl: RuleFn<TContext>;
+    /**
+     * Optional event type filter — only evaluate this rule when at least one
+     * event in the batch has a matching `tag`. When omitted, the rule runs on
+     * every step (catch-all).
+     *
+     * Accepts a single tag string or an array of tags.
+     *
+     * @example
+     * { id: 'sprint-behind', eventTypes: ['sprint.update'], impl: ... }
+     * { id: 'note-check', eventTypes: 'note.update', impl: ... }
+     */
+    eventTypes?: string | string[];
     /** Optional contract for rule behavior */
     contract?: Contract;
     /** Optional metadata */
@@ -337,6 +349,20 @@ interface PraxisEngineOptions<TContext = unknown> {
     initialFacts?: PraxisFact[];
     /** Initial metadata (optional) */
     initialMeta?: Record<string, unknown>;
+    /**
+     * Fact deduplication strategy (default: 'last-write-wins').
+     *
+     * - 'none': facts accumulate without dedup (original behavior)
+     * - 'last-write-wins': only keep the latest fact per tag (most common)
+     * - 'append': keep all facts but cap at maxFacts
+     */
+    factDedup?: 'none' | 'last-write-wins' | 'append';
+    /**
+     * Maximum number of facts to retain (default: 1000).
+     * When exceeded, oldest facts are evicted (FIFO).
+     * Set to 0 for unlimited (not recommended).
+     */
+    maxFacts?: number;
 }
 /**
  * The Praxis Logic Engine
@@ -347,6 +373,8 @@ interface PraxisEngineOptions<TContext = unknown> {
 declare class LogicEngine<TContext = unknown> {
     private state;
     private readonly registry;
+    private readonly factDedup;
+    private readonly maxFacts;
     constructor(options: PraxisEngineOptions<TContext>);
     /**
      * Get the current state (immutable copy)
@@ -385,6 +413,23 @@ declare class LogicEngine<TContext = unknown> {
      * @param updater Function that produces new context from old context
      */
     updateContext(updater: (context: TContext) => TContext): void;
+    /**
+     * Atomically update context AND process events in a single call.
+     *
+     * This avoids the fragile pattern of calling updateContext() then step()
+     * separately, where rules could see stale context if the ordering is wrong.
+     *
+     * @param updater Function that produces new context from old context
+     * @param events Events to process after context is updated
+     * @returns Result with new state and diagnostics
+     *
+     * @example
+     * engine.stepWithContext(
+     *   ctx => ({ ...ctx, sprintName: sprint.name, items: sprint.items }),
+     *   [{ tag: 'sprint.update', payload: { name: sprint.name } }]
+     * );
+     */
+    stepWithContext(updater: (context: TContext) => TContext, events: PraxisEvent[]): PraxisStepResult;
     /**
      * Add facts directly (for exceptional cases).
      * Generally, facts should be added through rules.
@@ -392,6 +437,16 @@ declare class LogicEngine<TContext = unknown> {
      * @param facts Facts to add
      */
     addFacts(facts: PraxisFact[]): void;
+    /**
+     * Check all constraints without processing any events.
+     *
+     * Useful for validation-only scenarios (e.g., form validation,
+     * pre-save checks) where you want constraint diagnostics without
+     * triggering any rules.
+     *
+     * @returns Array of constraint violation diagnostics (empty = all passing)
+     */
+    checkConstraints(): PraxisDiagnostics[];
     /**
      * Clear all facts
      */
@@ -495,4 +550,4 @@ declare class ReactiveLogicEngine<TContext extends object> {
  */
 declare function createReactiveEngine<TContext extends object>(options: ReactiveEngineOptions<TContext>): ReactiveLogicEngine<TContext>;
 
-export { type Assumption as A, type ConstraintDescriptor as C, type DefineContractOptions as D, type Example as E, LogicEngine as L, type MissingArtifact as M, PraxisRegistry as P, ReactiveLogicEngine as R, type Severity as S, type ValidationReport as V, type ReactiveEngineOptions as a, type RuleDescriptor as b, createReactiveEngine as c, type RuleFn as d, type Contract as e, type ConstraintFn as f, type PraxisModule as g, type RuleId as h, type ConstraintId as i, type PraxisEngineOptions as j, createPraxisEngine as k, defineContract as l, getContract as m, isContract as n, type Reference as o, type ContractGap as p };
+export { type Assumption as A, type ConstraintDescriptor as C, type DefineContractOptions as D, type Example as E, LogicEngine as L, type MissingArtifact as M, PraxisRegistry as P, type ReactiveEngineOptions as R, type Severity as S, type ValidationReport as V, ReactiveLogicEngine as a, type RuleDescriptor as b, createReactiveEngine as c, type ConstraintFn as d, type Contract as e, type RuleFn as f, type PraxisModule as g, type ConstraintId as h, type ContractGap as i, type PraxisEngineOptions as j, type Reference as k, type RuleId as l, createPraxisEngine as m, defineContract as n, getContract as o, isContract as p };

package/dist/node/{reactive-engine.svelte-BFIZfawz.d.cts → reactive-engine.svelte-D-xTDxT5.d.ts}

@@ -1,4 +1,4 @@
-import { P as PraxisState, a as PraxisEvent, b as PraxisFact, c as PraxisStepResult, d as PraxisStepConfig } from './protocol-Qek7ebBl.cjs';
+import { P as PraxisState, a as PraxisEvent, b as PraxisFact, c as PraxisStepResult, d as PraxisStepConfig, e as PraxisDiagnostics } from './protocol-BocKczNv.js';
 
 /**
  * Decision Ledger - Contract Types
@@ -209,6 +209,18 @@ interface RuleDescriptor<TContext = unknown> {
     description: string;
     /** Implementation function */
     impl: RuleFn<TContext>;
+    /**
+     * Optional event type filter — only evaluate this rule when at least one
+     * event in the batch has a matching `tag`. When omitted, the rule runs on
+     * every step (catch-all).
+     *
+     * Accepts a single tag string or an array of tags.
+     *
+     * @example
+     * { id: 'sprint-behind', eventTypes: ['sprint.update'], impl: ... }
+     * { id: 'note-check', eventTypes: 'note.update', impl: ... }
+     */
+    eventTypes?: string | string[];
     /** Optional contract for rule behavior */
     contract?: Contract;
     /** Optional metadata */
@@ -337,6 +349,20 @@ interface PraxisEngineOptions<TContext = unknown> {
     initialFacts?: PraxisFact[];
     /** Initial metadata (optional) */
     initialMeta?: Record<string, unknown>;
+    /**
+     * Fact deduplication strategy (default: 'last-write-wins').
+     *
+     * - 'none': facts accumulate without dedup (original behavior)
+     * - 'last-write-wins': only keep the latest fact per tag (most common)
+     * - 'append': keep all facts but cap at maxFacts
+     */
+    factDedup?: 'none' | 'last-write-wins' | 'append';
+    /**
+     * Maximum number of facts to retain (default: 1000).
+     * When exceeded, oldest facts are evicted (FIFO).
+     * Set to 0 for unlimited (not recommended).
+     */
+    maxFacts?: number;
 }
 /**
  * The Praxis Logic Engine
@@ -347,6 +373,8 @@ interface PraxisEngineOptions<TContext = unknown> {
 declare class LogicEngine<TContext = unknown> {
     private state;
     private readonly registry;
+    private readonly factDedup;
+    private readonly maxFacts;
     constructor(options: PraxisEngineOptions<TContext>);
     /**
      * Get the current state (immutable copy)
@@ -385,6 +413,23 @@ declare class LogicEngine<TContext = unknown> {
      * @param updater Function that produces new context from old context
      */
     updateContext(updater: (context: TContext) => TContext): void;
+    /**
+     * Atomically update context AND process events in a single call.
+     *
+     * This avoids the fragile pattern of calling updateContext() then step()
+     * separately, where rules could see stale context if the ordering is wrong.
+     *
+     * @param updater Function that produces new context from old context
+     * @param events Events to process after context is updated
+     * @returns Result with new state and diagnostics
+     *
+     * @example
+     * engine.stepWithContext(
+     *   ctx => ({ ...ctx, sprintName: sprint.name, items: sprint.items }),
+     *   [{ tag: 'sprint.update', payload: { name: sprint.name } }]
+     * );
+     */
+    stepWithContext(updater: (context: TContext) => TContext, events: PraxisEvent[]): PraxisStepResult;
     /**
      * Add facts directly (for exceptional cases).
      * Generally, facts should be added through rules.
@@ -392,6 +437,16 @@ declare class LogicEngine<TContext = unknown> {
      * @param facts Facts to add
      */
     addFacts(facts: PraxisFact[]): void;
+    /**
+     * Check all constraints without processing any events.
+     *
+     * Useful for validation-only scenarios (e.g., form validation,
+     * pre-save checks) where you want constraint diagnostics without
+     * triggering any rules.
+     *
+     * @returns Array of constraint violation diagnostics (empty = all passing)
+     */
+    checkConstraints(): PraxisDiagnostics[];
     /**
      * Clear all facts
      */
@@ -495,4 +550,4 @@ declare class ReactiveLogicEngine<TContext extends object> {
  */
 declare function createReactiveEngine<TContext extends object>(options: ReactiveEngineOptions<TContext>): ReactiveLogicEngine<TContext>;
 
-export { type Assumption as A, type ConstraintDescriptor as C, type DefineContractOptions as D, type Example as E, LogicEngine as L, type MissingArtifact as M, PraxisRegistry as P, ReactiveLogicEngine as R, type Severity as S, type ValidationReport as V, type ReactiveEngineOptions as a, type RuleDescriptor as b, createReactiveEngine as c, type RuleFn as d, type Contract as e, type ConstraintFn as f, type PraxisModule as g, type RuleId as h, type ConstraintId as i, type PraxisEngineOptions as j, createPraxisEngine as k, defineContract as l, getContract as m, isContract as n, type Reference as o, type ContractGap as p };
+export { type Assumption as A, type ConstraintDescriptor as C, type DefineContractOptions as D, type Example as E, LogicEngine as L, type MissingArtifact as M, PraxisRegistry as P, type ReactiveEngineOptions as R, type Severity as S, type ValidationReport as V, ReactiveLogicEngine as a, type RuleDescriptor as b, createReactiveEngine as c, type ConstraintFn as d, type Contract as e, type RuleFn as f, type PraxisModule as g, type ConstraintId as h, type ContractGap as i, type PraxisEngineOptions as j, type Reference as k, type RuleId as l, createPraxisEngine as m, defineContract as n, getContract as o, isContract as p };

package/dist/node/{terminal-adapter-B-UK_Vdz.d.ts → terminal-adapter-CvIvgTo4.d.ts}

@@ -320,4 +320,4 @@ declare function createMockExecutor(responses: Record<string, {
     error?: string;
 }>): CommandExecutor;
 
-export { type CommandExecutor as C, InMemoryPraxisDB as I, type PraxisDB as P, TerminalAdapter as T, type UnsubscribeFn as U, type TerminalExecutionResult as a, type TerminalNodeState as b, createTerminalAdapter as c, type TerminalAdapterOptions as d, createMockExecutor as e, type PluresDBInstance as f, type PluresDBAdapterConfig as g, type PraxisLocalFirstOptions as h, createInMemoryDB as i, PluresDBPraxisAdapter as j, createPluresDB as k, createPraxisLocalFirst as l, runTerminalCommand as r };
+export { type CommandExecutor as C, InMemoryPraxisDB as I, type PraxisDB as P, TerminalAdapter as T, type UnsubscribeFn as U, type PluresDBAdapterConfig as a, type PluresDBInstance as b, createTerminalAdapter as c, PluresDBPraxisAdapter as d, type PraxisLocalFirstOptions as e, type TerminalAdapterOptions as f, type TerminalExecutionResult as g, type TerminalNodeState as h, createInMemoryDB as i, createMockExecutor as j, createPluresDB as k, createPraxisLocalFirst as l, runTerminalCommand as r };

package/dist/node/{terminal-adapter-BQSIF5bf.d.cts → terminal-adapter-Db-snPJ3.d.cts}

@@ -320,4 +320,4 @@ declare function createMockExecutor(responses: Record<string, {
     error?: string;
 }>): CommandExecutor;
 
-export { type CommandExecutor as C, InMemoryPraxisDB as I, type PraxisDB as P, TerminalAdapter as T, type UnsubscribeFn as U, type TerminalExecutionResult as a, type TerminalNodeState as b, createTerminalAdapter as c, type TerminalAdapterOptions as d, createMockExecutor as e, type PluresDBInstance as f, type PluresDBAdapterConfig as g, type PraxisLocalFirstOptions as h, createInMemoryDB as i, PluresDBPraxisAdapter as j, createPluresDB as k, createPraxisLocalFirst as l, runTerminalCommand as r };
+export { type CommandExecutor as C, InMemoryPraxisDB as I, type PraxisDB as P, TerminalAdapter as T, type UnsubscribeFn as U, type PluresDBAdapterConfig as a, type PluresDBInstance as b, createTerminalAdapter as c, PluresDBPraxisAdapter as d, type PraxisLocalFirstOptions as e, type TerminalAdapterOptions as f, type TerminalExecutionResult as g, type TerminalNodeState as h, createInMemoryDB as i, createMockExecutor as j, createPluresDB as k, createPraxisLocalFirst as l, runTerminalCommand as r };

package/dist/node/{validate-CNHUULQE.js → validate-EN3M4FUR.js}

@@ -4,7 +4,7 @@ import {
   formatValidationReportJSON,
   formatValidationReportSARIF,
   validateContracts
-} from "./chunk-5RH7UAQC.js";
+} from "./chunk-PTH6MD6P.js";
 import {
   writeLogicLedgerEntry
 } from "./chunk-WZ6B3LZ6.js";

package/dist/node/{verify-KLJRXVJS.js → verify-7VZRP2WS.js}

@@ -4,9 +4,9 @@ import {
   __toESM
 } from "./chunk-QGM4M3NI.js";
 
-// node_modules/typescript/lib/typescript.js
+// node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/typescript.js
 var require_typescript = __commonJS({
-  "node_modules/typescript/lib/typescript.js"(exports, module) {
+  "node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/typescript.js"(exports, module) {
     "use strict";
     var ts2 = {};
     ((module2) => {

package/docs/BOT_UPDATE_POLICY.md

@@ -0,0 +1,125 @@
+# Bot Update Policy
+
+## Overview
+
+This document describes how automated updates (dependency bumps, pin updates, etc.) are managed in the Praxis repository to reduce commit churn and improve reviewability.
+
+## Goals
+
+1. **Batch Updates**: Group related updates together instead of creating many small PRs
+2. **Improve Auditability**: Require summaries and upstream links for all bot PRs
+3. **Maintain Tracking**: Keep audit trail even without dedicated GitHub issues
+4. **Reduce Noise**: Weekly batching instead of continuous small updates
+
+## How It Works
+
+### Dependabot Configuration
+
+Dependabot is configured to:
+- Run weekly on Mondays at 09:00 UTC
+- Group updates by ecosystem (npm production, npm dev, github-actions)
+- Limit to 5 open PRs at a time
+- Use consistent labels: `dependencies`, `bot-update`
+- Follow standardized commit message format: `chore(deps): ...`
+
+See `.github/dependabot.yml` for full configuration.
+
+### Weekly Pin Bumps
+
+The `batch-pin-bumps.yml` workflow:
+- Runs every Monday at 08:00 UTC (before dependabot)
+- Checks for lockfile updates (pnpm-lock.yaml, package-lock.json)
+- Creates a single PR with all pin bumps for the week
+- Uses the standard bot PR template for consistency
+
+### Weekly Activity Log
+
+The `bot-weekly-log.yml` workflow:
+- Runs every Monday at 10:00 UTC (after updates run)
+- Collects all bot PRs merged in the past week
+- Creates a weekly activity log in `.github/bot-logs/`
+- Provides audit trail without requiring GitHub issues
+- Commits log directly to main branch
+
+### PR Template
+
+All bot PRs use `.github/BOT_PR_TEMPLATE.md` which requires:
+- Brief summary of changes
+- List of updated dependencies/files
+- Links to upstream changelogs or release notes
+- Impact assessment (breaking changes, security, testing)
+- Weekly batch identifier for tracking
+
+## For Repository Maintainers
+
+### Reviewing Bot PRs
+
+When reviewing automated PRs:
+
+1. **Check the Summary**: Understand what's being updated
+2. **Review Upstream Links**: Look for breaking changes or security fixes
+3. **Verify CI Passes**: Ensure all tests and checks pass
+4. **Check Impact Assessment**: Pay attention to flagged items
+5. **Merge Weekly Batches**: Approve and merge to reduce backlog
+
+### Customizing Pin Updates
+
+To add custom pin update checks in `batch-pin-bumps.yml`:
+
+1. Edit the "Check for pin updates" step
+2. Add logic to detect your specific pin files
+3. Update the summary to describe what changed
+4. Test with workflow_dispatch before scheduling
+
+### Adjusting Schedule
+
+To change update frequency:
+
+1. Edit cron schedules in workflow files
+2. Update dependabot.yml schedule.interval
+3. Coordinate timing (pin bumps → dependabot → weekly log)
+
+## For Other Repositories
+
+This bot update approach can be adopted by other repositories in the Plures organization:
+
+### Setup Steps
+
+1. Copy `.github/dependabot.yml` and adjust for your ecosystem
+2. Copy `.github/BOT_PR_TEMPLATE.md`
+3. Copy `.github/workflows/bot-weekly-log.yml`
+4. (Optional) Copy `.github/workflows/batch-pin-bumps.yml` and customize
+5. Create `.github/bot-logs/` directory structure
+6. Update your README to reference the new bot policy
+
+### Target Repositories
+
+As mentioned in the original issue, these repos should adopt this approach:
+- ✅ plures/praxis (this repo)
+- ⬜ plures/nix-openclaw (issues disabled; track here)
+- ⬜ plures/praxis-business
+- ⬜ plures/behavior-ledger-github-cicd
+
+## References
+
+- Original Issue: Practice: reduce bot churn (batch pin bumps; prefer PRs; add audit trail)
+- Dependabot Documentation: https://docs.github.com/en/code-security/dependabot
+- GitHub Actions Workflow Syntax: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
+
+## FAQ
+
+### Why weekly instead of daily?
+
+Weekly batching significantly reduces PR volume while still keeping dependencies reasonably up-to-date. Security updates can still be handled immediately through manual intervention.
+
+### What if I need an urgent update?
+
+You can always create a manual PR for urgent updates. The weekly batching is for routine maintenance only.
+
+### Where do I find the weekly logs?
+
+All weekly logs are stored in `.github/bot-logs/` with an index at `.github/bot-logs/INDEX.md`.
+
+### Can I trigger updates manually?
+
+Yes! All workflows support `workflow_dispatch` for manual triggering via the GitHub Actions UI.

package/docs/DOGFOODING_CHECKLIST.md

@@ -0,0 +1,254 @@
+# Dogfooding Checklist
+
+This document provides daily, weekly, and monthly checklists to ensure we're actively dogfooding Plures tools and filing issues when friction is discovered.
+
+## Philosophy
+
+**Dogfooding = Using + Observing + Reporting**
+
+We dogfood to:
+- Find friction before users do
+- Validate our tools work in real scenarios
+- Generate actionable improvements
+- Build empathy with users
+
+**Key Principle:** Prefer small, high-signal issues over comprehensive reports. File friction immediately when encountered.
+
+---
+
+## Daily Development Workflow
+
+### Before Starting Work
+
+- [ ] **Pull Latest**: Ensure you have the latest changes
+  ```bash
+  git pull origin main
+  ```
+
+- [ ] **Build & Validate**: Run the build and validation
+  ```bash
+  npm run build
+  npm run validate:contracts
+  ```
+
+- [ ] **Check for Failures**: Review any contract validation warnings
+  - If warnings exist, assess if they relate to your work
+  - File dogfooding issue if validation is unclear or unhelpful
+
+### During Development
+
+When adding or modifying rules/constraints:
+
+- [ ] **Define Contract**: Create contract via `defineContract()`
+  ```typescript
+  const myContract = defineContract({
+    behavior: "Clear description of what this does",
+    examples: [/* Given/When/Then scenarios */],
+    invariants: [/* Constraints that must hold */],
+    assumptions: [/* Explicit assumptions with confidence */],
+    references: [/* Links to docs, issues, discussions */]
+  });
+  ```
+
+- [ ] **Attach Contract**: Add to rule/constraint meta
+  ```typescript
+  const myRule = defineRule({
+    id: 'module.action',
+    meta: { contract: myContract },
+    // ...
+  });
+  ```
+
+- [ ] **Write Tests**: Cover every Given/When/Then example
+  - Name tests to include rule ID for validation tracking
+  - Test all invariants explicitly
+
+- [ ] **Use Praxis CLI**: Leverage CLI for generation when applicable
+  ```bash
+  npx praxis generate --schema src/schemas/my-schema.ts
+  ```
+
+- [ ] **File Friction Immediately**: When you encounter any friction
+  - Confusing error message? → File issue
+  - Unclear API? → File issue
+  - Manual step that should be automated? → File issue
+  - Use the dogfooding issue template (see below)
+
+### Before Committing
+
+- [ ] **Scan Rules**: Run the rule scanner
+  ```bash
+  npm run scan:rules
+  ```
+
+- [ ] **Validate Contracts**: Ensure all contracts are valid
+  ```bash
+  npm run validate:contracts
+  ```
+
+- [ ] **Run Tests**: Ensure tests pass
+  ```bash
+  npm test
+  ```
+
+- [ ] **TypeCheck**: Verify no type errors
+  ```bash
+  npm run typecheck
+  ```
+
+---
+
+## Weekly Review (Friday or End of Sprint)
+
+### Tool Usage Review
+
+- [ ] **Review Plures Tools Usage**: Check which tools were used this week
+  - Praxis CLI: What commands did you use?
+  - PluresDB: Did you use it in development or tests?
+  - State-Docs: Did you generate documentation?
+  - CodeCanvas: Did you visualize any schemas?
+  - Unum: Did you use distributed features?
+
+- [ ] **Identify Gaps**: What could you have used but didn't?
+  - File a note or issue about why you didn't use a tool
+  - Was it not obvious when to use it?
+  - Was it too difficult to set up?
+
+- [ ] **Review Filed Issues**: Check dogfooding issues from the week
+  - Are they tagged with `dogfood` label?
+  - Are they small and actionable?
+  - Do they have proper context?
+
+### Contract Coverage Review
+
+- [ ] **Run Coverage Check**: Validate contract coverage
+  ```bash
+  npm run validate:contracts
+  ```
+
+- [ ] **Review Contract Gaps**: Check for rules without contracts
+  - Prioritize high-impact rules
+  - File issues for contract gaps if needed
+
+- [ ] **Update Documentation**: If contracts changed behavior
+  - Update `docs/decision-ledger/BEHAVIOR_LEDGER.md`
+  - Update `docs/decision-ledger/LATEST.md`
+
+---
+
+## Monthly Assessment (First Week of Month)
+
+### Strategic Review
+
+- [ ] **Review Plures Tools Inventory**
+  - Update `docs/PLURES_TOOLS_INVENTORY.md`
+  - Reassess adoption status and priorities
+  - Update usage levels and integration status
+
+- [ ] **Analyze Dogfooding Issues**
+  - Group issues by tool/component
+  - Identify patterns and systemic problems
+  - Prioritize high-impact improvements
+
+- [ ] **Measure Adoption Progress**
+  - How many new tools were adopted this month?
+  - What percentage of development uses dogfooded tools?
+  - Are we using tools more effectively?
+
+### Contract Quality Review
+
+- [ ] **Contract Drift Analysis**
+  - Run ledger snapshot and compare to last month
+  - Identify rules with frequent contract changes
+  - Assess if changes indicate instability or evolution
+
+- [ ] **Test Coverage for Contracts**
+  - Ensure all contract examples have corresponding tests
+  - Verify invariants are tested
+  - Check for untested edge cases
+
+### Documentation Update
+
+- [ ] **Update Adoption Status**: Reflect changes in inventory
+- [ ] **Share Learnings**: Document what worked and what didn't
+- [ ] **Update Guidelines**: If new patterns emerge, update CONTRIBUTING.md
+
+---
+
+## Filing Dogfooding Issues
+
+### When to File
+
+File an issue **immediately** when you encounter:
+- Confusing error messages or validation output
+- Unclear or missing documentation
+- Manual steps that should be automated
+- Unexpected behavior from tools
+- Difficulty using a feature
+- Missing features that would help
+- Performance issues or slow commands
+
+### How to File
+
+1. **Use the Dogfooding Issue Template**: `.github/ISSUE_TEMPLATE/dogfooding.yml`
+2. **Be Specific**: Focus on one friction point per issue
+3. **Provide Context**: Include what you were trying to do
+4. **Suggest Solutions**: If you have ideas, share them
+5. **Link to Related Work**: Reference PRs, commits, or conversations
+
+### Example Good Issues
+
+✅ **Good**: "Praxis CLI `validate` command doesn't show which file has the missing contract"  
+❌ **Bad**: "Validation is confusing"
+
+✅ **Good**: "State-Docs generator requires manual configuration - should auto-detect schema files"  
+❌ **Bad**: "State-Docs is hard to use"
+
+✅ **Good**: "No example of using CodeCanvas to visualize a schema with nested objects"  
+❌ **Bad**: "CodeCanvas documentation is incomplete"
+
+---
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# Build and validate
+npm run build
+npm run validate:contracts
+
+# Scan and check
+npm run scan:rules
+npm test
+npm run typecheck
+
+# Generate docs
+npx praxis docs generate
+
+# Canvas export
+npx praxis canvas src/schemas/app.schema.ts
+```
+
+### Where to Find Things
+
+- **Tools Inventory**: `docs/PLURES_TOOLS_INVENTORY.md`
+- **Decision Ledger**: `docs/decision-ledger/DOGFOODING.md`
+- **Contributing**: `CONTRIBUTING.md`
+- **Examples**: `examples/` directory
+
+---
+
+## Meta-Dogfooding
+
+Even this checklist is dogfooding! If you find:
+- Missing items that should be checked
+- Steps that are unclear
+- Friction in following this checklist
+
+**File a dogfooding issue!** Tag it with `dogfood` and `documentation`.
+
+---
+
+Last Updated: 2026-02-01  
+Maintainer: Praxis Core Team