@plures/praxis 1.2.13 → 1.3.0

package/docs/PLURES_TOOLS_INVENTORY.md

@@ -0,0 +1,170 @@
+# Plures Tools Inventory
+
+This document tracks the adoption and usage of Plures ecosystem tools in the Praxis repository.
+
+## Available Plures Tools
+
+### 1. **Praxis CLI** ✅ Adopted
+**Status:** Actively used  
+**Package:** `@plures/praxis`  
+**Purpose:** Command-line interface for scaffolding, code generation, and project management
+
+**Current Usage:**
+- Project scaffolding: `npx praxis create app <name>`
+- Component generation: `npx praxis generate --schema <file>`
+- Canvas export: `npx praxis canvas <schema>`
+- Contract validation: `npm run validate:contracts`
+- Rule scanning: `npm run scan:rules`
+
+**Adoption Opportunities:**
+- Use in CI/CD pipelines for validation
+- Integrate into pre-commit hooks for contract validation
+- Create custom commands for common workflows
+
+---
+
+### 2. **PluresDB** ✅ Adopted
+**Status:** Actively integrated  
+**Package:** `@plures/pluresdb` (peer dependency)  
+**Purpose:** Local-first, P2P-capable database with CRDT conflict resolution
+
+**Current Usage:**
+- Available via `createPluresDB()` adapter
+- Used in examples (offline-chat, cloud-sync, distributed-node)
+- Documented in README and integration guides
+
+**Adoption Opportunities:**
+- Use PluresDB for test fixtures and example data
+- Integrate into development server for live data persistence
+- Create PluresDB-backed test utilities
+
+---
+
+### 3. **Unum** ✅ Partially Adopted
+**Status:** Integrated, limited usage  
+**Package:** `@plures/unum` (future peer dependency)  
+**Purpose:** Distributed communication and P2P networking
+
+**Current Usage:**
+- Available via `createUnumAdapter()`
+- Used in distributed examples
+- Documented in README
+
+**Adoption Opportunities:**
+- Use Unum for development collaboration (live code sync)
+- Integrate into CI for distributed testing
+- Create Unum-based development tools
+
+---
+
+### 4. **State-Docs** ✅ Partially Adopted
+**Status:** Generator available, limited usage  
+**Package:** Built-in to Praxis  
+**Purpose:** Automated documentation generation from schemas and logic
+
+**Current Usage:**
+- `createStateDocsGenerator()` available
+- Basic usage documented in README
+
+**Adoption Opportunities:**
+- Generate documentation as part of build process
+- Auto-generate API docs from schemas
+- Create visual state machine diagrams
+- Generate contract documentation automatically
+
+---
+
+### 5. **CodeCanvas** ⚠️ Available, Not Adopted
+**Status:** API available but not actively used  
+**Package:** Built-in to Praxis  
+**Purpose:** Visual schema editing and diagram generation
+
+**Current Usage:**
+- `schemaToCanvas()` function available
+- Mentioned in README
+- Not actively used in development
+
+**Adoption Opportunities:**
+- **HIGH PRIORITY**: Use for visualizing complex schemas
+- Generate architecture diagrams from code
+- Create visual onboarding guides
+- Export to Mermaid/PlantUML for documentation
+
+---
+
+### 6. **OpenClaw** ❌ Not Adopted
+**Status:** Not yet integrated  
+**Purpose:** AI-powered code analysis and refactoring tool
+
+**Current Usage:**
+- Not currently used
+
+**Adoption Opportunities:**
+- **INVESTIGATE**: Determine if OpenClaw exists as standalone tool
+- Evaluate for automated code review
+- Consider for migration assistance
+- Explore for pattern detection in codebase
+
+---
+
+### 7. **Decision Ledger** ✅ Actively Dogfooding
+**Status:** Fully adopted and enforced  
+**Package:** Built-in to Praxis  
+**Purpose:** Behavior contracts for rules and constraints
+
+**Current Usage:**
+- Contract definitions via `defineContract()`
+- Validation via `npm run validate:contracts`
+- Scanning via `npm run scan:rules`
+- Full workflow documented in `docs/decision-ledger/DOGFOODING.md`
+
+**Adoption Status:**
+- ✅ Contracts for core rules
+- ✅ CI validation pipeline
+- ✅ Developer guidelines in CONTRIBUTING.md
+
+---
+
+## Adoption Priority Matrix
+
+### Immediate (This Week)
+1. **CodeCanvas** - Start visualizing key schemas and architecture
+2. **State-Docs** - Integrate into build process for auto-docs
+3. **Praxis CLI** - Add to pre-commit hooks for validation
+
+### Short-term (This Month)
+1. **PluresDB** - Use for test fixtures and development data
+2. **Unum** - Explore for development collaboration
+3. **OpenClaw** - Research availability and capabilities
+
+### Ongoing
+1. **Decision Ledger** - Continue expanding contract coverage
+2. **Praxis CLI** - Discover and document new use cases
+
+---
+
+## Integration Status Summary
+
+| Tool | Status | Usage Level | Priority |
+|------|--------|-------------|----------|
+| Praxis CLI | ✅ Adopted | High | Maintain |
+| PluresDB | ✅ Adopted | Medium | Expand |
+| Decision Ledger | ✅ Adopted | High | Maintain |
+| Unum | ⚠️ Partial | Low | Expand |
+| State-Docs | ⚠️ Partial | Low | **High** |
+| CodeCanvas | ⚠️ Available | None | **High** |
+| OpenClaw | ❌ Not Adopted | None | Research |
+
+---
+
+## Resources
+
+- [Praxis CLI Documentation](../README.md#cli-npx-friendly)
+- [PluresDB Integration](../README.md#pluresdb-integration)
+- [Decision Ledger Dogfooding](./decision-ledger/DOGFOODING.md)
+- [Contributing Guidelines](../CONTRIBUTING.md)
+
+---
+
+Last Updated: 2026-02-01  
+Maintainer: Praxis Core Team

package/docs/README.md

@@ -2,6 +2,16 @@
 
 Welcome to the official Praxis documentation! Praxis is the full-stack application framework for the Plures ecosystem, providing a complete solution for building modern, local-first, distributed applications.
 
+## 🐕 Dogfooding Plures Tools
+
+**Start here for dogfooding:** [Dogfooding Index](./DOGFOODING_INDEX.md)
+
+We actively dogfood all Plures tools during development. Key resources:
+- [Quick Start Guide](./DOGFOODING_QUICK_START.md) - Get started in 5 minutes
+- [Dogfooding Checklist](./DOGFOODING_CHECKLIST.md) - Daily/weekly/monthly workflows
+- [Plures Tools Inventory](./PLURES_TOOLS_INVENTORY.md) - All available tools
+- [Workflow Examples](./examples/DOGFOODING_WORKFLOW_EXAMPLE.md) - See it in action
+
 ## Quick Start
 
 ```bash
@@ -24,6 +34,8 @@ npm run dev
 | Document                                               | Description                                  |
 | ------------------------------------------------------ | -------------------------------------------- |
 | [What is Praxis](./core/what-is-praxis.md)             | Overview of Praxis and its core philosophy   |
+| [Praxis-Core API](./core/praxis-core-api.md)           | Stable API surface and guarantees            |
+| [Extending Praxis-Core](./core/extending-praxis-core.md) | Extension guidelines without breaking changes |
 | [Schema Model](./core/schema-model.md)                 | Understanding the Praxis Schema Format (PSF) |
 | [Logic Engine](./core/logic-engine.md)                 | Facts, events, rules, and constraints        |
 | [UI Generation](./core/ui-generation.md)               | Automatic component generation from schemas  |

package/docs/TESTING_BOT_WORKFLOWS.md

@@ -0,0 +1,154 @@
+# Testing Bot Update Workflows
+
+This guide explains how to test the new batched bot update workflows.
+
+## Prerequisites
+
+- GitHub CLI (`gh`) installed and authenticated
+- Appropriate repository permissions (write access)
+
+## Testing Individual Workflows
+
+### 1. Test Weekly Activity Log
+
+```bash
+# Trigger manually via GitHub Actions UI
+# Go to: Actions → Weekly Bot Activity Log → Run workflow
+
+# Or via GitHub CLI:
+gh workflow run bot-weekly-log.yml
+
+# Check the run:
+gh run list --workflow=bot-weekly-log.yml
+
+# View the output:
+gh run view --log
+```
+
+**Expected Result:**
+- A new markdown file created in `.github/bot-logs/` with format `YYYY-Wxx.md`
+- The INDEX.md file updated with a link to the new log
+- Commit pushed to main branch with message: `chore: update bot activity log for week YYYY-Wxx`
+
+### 2. Test Batch Pin Bumps
+
+```bash
+# Trigger manually via GitHub Actions UI with force_update option
+# Go to: Actions → Batch Pin Bumps (Weekly) → Run workflow → Set force_update to 'true'
+
+# Or via GitHub CLI:
+gh workflow run batch-pin-bumps.yml -f force_update=true
+
+# Check the run:
+gh run list --workflow=batch-pin-bumps.yml
+
+# Check for created PR:
+gh pr list --label bot-update
+```
+
+**Expected Result:**
+- A new branch created: `bot/weekly-pins-YYYY-Wxx`
+- A PR opened with title: `chore(deps): weekly pin bumps - YYYY-Wxx`
+- PR uses the BOT_PR_TEMPLATE.md format
+- PR labeled with: `dependencies`, `bot-update`, `automated-pins`
+
+### 3. Test Dependabot Grouping
+
+Dependabot runs automatically on schedule, but you can verify configuration:
+
+```bash
+# Check dependabot configuration
+cat .github/dependabot.yml
+
+# View existing dependabot PRs
+gh pr list --author "dependabot[bot]"
+
+# Check for grouped PRs (should see fewer, larger PRs)
+gh pr list --author "dependabot[bot]" --label dependencies
+```
+
+**Expected Result:**
+- Dependabot creates grouped PRs like:
+  - "Bump the npm-production group with X updates"
+  - "Bump the npm-dev-tools group with Y updates"
+  - "Bump the github-actions group with Z updates"
+
+## Integration Testing
+
+### Weekly Workflow Sequence
+
+The workflows run in this order:
+1. **08:00 UTC Monday**: `batch-pin-bumps.yml` (creates PR)
+2. **09:00 UTC Monday**: Dependabot runs (creates grouped PRs)
+3. **10:00 UTC Monday**: `bot-weekly-log.yml` (logs previous week's activity)
+
+To test the full sequence:
+
+1. Manually trigger batch-pin-bumps on a Monday
+2. Review and merge the created PR
+3. Let dependabot run naturally or configure it to run more frequently for testing
+4. Manually trigger bot-weekly-log
+5. Check `.github/bot-logs/` for the generated log
+
+## Validation Checklist
+
+After implementing the bot update approach, verify:
+
+- [ ] Dependabot creates grouped PRs (not individual dependency PRs)
+- [ ] Bot PRs use the standard template format
+- [ ] Weekly logs are generated in `.github/bot-logs/`
+- [ ] INDEX.md is updated automatically
+- [ ] All bot PRs have `bot-update` label
+- [ ] Commit messages follow pattern: `chore(deps): ...`
+- [ ] No direct commits to main (all updates via PR)
+
+## Troubleshooting
+
+### Workflow Fails with Permission Error
+
+Ensure the workflow has appropriate permissions in `.github/workflows/*.yml`:
+```yaml
+permissions:
+  contents: write
+  pull-requests: write
+```
+
+### Bot Logs Not Committing
+
+Check that:
+- Git user is configured in the workflow
+- GITHUB_TOKEN has write access to the repository
+- Branch protection rules allow bot commits
+
+### No PRs Created
+
+Verify:
+- Changes were actually detected (check step output)
+- Branch doesn't already exist
+- PR limit not reached (dependabot config: open-pull-requests-limit)
+
+### Dependabot Not Grouping
+
+Ensure:
+- Using Dependabot v2 configuration format
+- `groups:` section is properly configured
+- Updates match the group patterns
+
+## Manual Rollback
+
+If you need to revert the bot update approach:
+
+1. Restore original `.github/dependabot.yml`
+2. Disable or delete the new workflows:
+   - `.github/workflows/bot-weekly-log.yml`
+   - `.github/workflows/batch-pin-bumps.yml`
+3. Remove `.github/bot-logs/` directory
+4. Remove `.github/BOT_PR_TEMPLATE.md`
+
+## Next Steps
+
+Once testing is complete:
+1. Monitor for one full week to ensure all workflows run correctly
+2. Review the generated logs for completeness
+3. Adjust schedules or grouping as needed
+4. Share the approach with other Plures repositories