plcode-linux-arm64-musl 2.1.0

package/.plcode/context/core/context-system/operations/update.md

@@ -0,0 +1,260 @@
+# Update Operation
+
+**Purpose**: Update context when APIs, frameworks, or contracts change
+
+**Last Updated**: 2026-01-06
+
+---
+
+## When to Use
+
+- Framework version updates (Next.js 14 → 15)
+- API changes (breaking changes, deprecations)
+- New features added to existing topics
+- Migration guides needed
+
+---
+
+## 8-Stage Workflow
+
+### Stage 1: Identify Changes (APPROVAL REQUIRED)
+
+**Action**: User describes what changed
+
+**Format**:
+
+```
+What changed in {topic}?
+  [A] API changes
+  [B] Deprecations
+  [C] New features
+  [D] Breaking changes
+  [E] Other (describe)
+
+Select all that apply (A B C D or describe):
+```
+
+**Follow-up**: Get specific details for each selected type
+
+**Validation**: MUST get user input before proceeding
+
+---
+
+### Stage 2: Find Affected Files
+
+**Action**: Search for files referencing the topic
+
+**Process**:
+
+1. Grep for topic references across all context
+2. Count references per file
+3. Show impact analysis
+
+**Format**:
+
+```
+Found 5 files referencing {topic}:
+  📄 concepts/routing.md (3 references, 145 lines)
+  📄 examples/app-router-example.md (7 references, 78 lines)
+  📄 guides/setting-up-nextjs.md (2 references, 132 lines)
+  📄 errors/nextjs-errors.md (1 reference, 98 lines)
+  📄 lookup/nextjs-commands.md (4 references, 54 lines)
+
+Total impact: 17 references across 5 files
+```
+
+---
+
+### Stage 3: Preview Changes (APPROVAL REQUIRED)
+
+**Action**: Show line-by-line diff for each file
+
+**Format**:
+
+```
+Proposed updates:
+
+━━━ concepts/routing.md ━━━
+
+Line 15:
+  - App router is optional (use pages/ or app/)
+  + App router is now default in Next.js 15 (pages/ still supported)
+
+Line 42:
+  + ## Metadata API (New in v15)
+  + Next.js 15 introduces new metadata API...
+
+━━━ examples/app-router-example.md ━━━
+
+Line 8:
+  - // Optional: use app router
+  + // Default in Next.js 15+
+
+Preview next file? (yes/no/show-all)
+Approve changes? (yes/no/edit):
+```
+
+**Edit mode**: Line-by-line approval for each change
+
+**Validation**: MUST get approval before proceeding
+
+---
+
+### Stage 4: Backup
+
+**Action**: Create backup before updating
+
+**Location**: `.tmp/backup/update-{topic}-{timestamp}/`
+
+**Purpose**: Enable rollback if updates cause issues
+
+---
+
+### Stage 5: Update Files
+
+**Action**: Apply approved changes
+
+**Process**:
+
+1. Update concepts, examples, guides, lookups
+2. Maintain MVI format (<200 lines)
+3. Update "Last Updated" dates
+4. Preserve file structure
+
+**Enforcement**: `@critical_rules.mvi_strict`
+
+---
+
+### Stage 6: Add Migration Notes
+
+**Action**: Add migration guide to errors/
+
+**Format**:
+
+```markdown
+## Migration: {Old Version} → {New Version}
+
+**Breaking Changes**:
+
+- Change 1
+- Change 2
+
+**Migration Steps**:
+
+1. Step 1
+2. Step 2
+
+**Reference**: [Link to changelog]
+```
+
+**Location**: `{category}/errors/{topic}-errors.md`
+
+---
+
+### Stage 7: Validate
+
+**Action**: Check all references and links
+
+**Checks**:
+
+- All internal references still work
+- No broken links
+- All files still <200 lines
+- MVI format maintained
+
+---
+
+### Stage 8: Report
+
+**Action**: Show comprehensive results
+
+**Format**:
+
+```
+✅ Updated X files
+📝 Modified Y references
+🔄 Added migration notes to errors/
+💾 Backup: .tmp/backup/update-{topic}-{timestamp}/
+
+Summary of changes:
+  - concepts/routing.md: 2 updates (145 → 162 lines)
+  - examples/app-router-example.md: 4 updates (78 → 89 lines)
+  - guides/setting-up-nextjs.md: 1 update (132 → 133 lines)
+
+All files still under 200 line limit ✓
+
+Rollback available if needed.
+```
+
+---
+
+## Change Types
+
+### API Changes
+
+- Method signatures changed
+- Parameters added/removed
+- Return types changed
+
+### Deprecations
+
+- Features marked deprecated
+- Replacement APIs available
+- Timeline for removal
+
+### New Features
+
+- New capabilities added
+- New APIs introduced
+- New patterns available
+
+### Breaking Changes
+
+- Incompatible changes
+- Migration required
+- Old code won't work
+
+---
+
+## Examples
+
+### Framework Update
+
+```bash
+/context update for Next.js 15
+/context update for React 19
+```
+
+### API Changes
+
+```bash
+/context update for Stripe API v2024
+/context update for OpenAI API breaking changes
+```
+
+### Library Update
+
+```bash
+/context update for Tailwind CSS v4
+```
+
+---
+
+## Success Criteria
+
+- [ ] User described changes?
+- [ ] All affected files found?
+- [ ] Diff preview shown?
+- [ ] User approved changes?
+- [ ] Backup created?
+- [ ] Migration notes added?
+- [ ] All references validated?
+- [ ] All files still <200 lines?
+
+---
+
+## Related
+
+- guides/workflows.md - Interactive diff examples
+- standards/mvi.md - Maintain MVI format
+- operations/error.md - Adding migration notes

package/.plcode/context/core/context-system/standards/mvi.md

@@ -0,0 +1,154 @@
+# MVI Principle (Minimal Viable Information)
+
+**Purpose**: Extract only core concepts, not verbose explanations
+
+**Last Updated**: 2026-01-06
+
+---
+
+## Core Idea
+
+Extract the **minimum information** needed for an AI agent to understand and use a concept:
+
+- Core concept (1-3 sentences)
+- Key points (3-5 bullets)
+- Minimal working example
+- Reference link to full docs
+
+**Goal**: Scannable in <30 seconds. Reference full docs, don't duplicate them.
+
+---
+
+## The Formula
+
+```
+Core Concept (1-3 sentences)
+  ↓
+Key Points (3-5 bullets)
+  ↓
+Quick Example (5-10 lines)
+  ↓
+Reference Link (full docs)
+  ↓
+Related Files (cross-refs)
+```
+
+---
+
+## What to Extract ✅
+
+- **Core definitions** - What it is (1-3 sentences)
+- **Key properties** - Essential characteristics (3-5 bullets)
+- **Minimal example** - Simplest working code (5-10 lines)
+- **Common patterns** - How it's typically used (2-3 bullets)
+- **Critical gotchas** - Must-know issues (1-2 bullets)
+- **Reference links** - Where to learn more
+
+---
+
+## What to Skip ❌
+
+- **Verbose explanations** - Link to docs instead
+- **Complete API docs** - Summarize + reference
+- **Implementation details** - Show minimal example + reference
+- **Historical context** - Unless critical to understanding
+- **Marketing content** - Just the facts
+- **Duplicate information** - Say it once, reference elsewhere
+
+---
+
+## Example: JWT Authentication
+
+### ❌ Too Verbose (400+ lines)
+
+```markdown
+# JWT Authentication
+
+JSON Web Tokens (JWT) are an open standard (RFC 7519) that defines
+a compact and self-contained way for securely transmitting information
+between parties as a JSON object. This information can be verified and
+trusted because it is digitally signed. JWTs can be signed using a
+secret (with the HMAC algorithm) or a public/private key pair using RSA
+or ECDSA.
+
+[... 400 more lines of explanation, examples, edge cases ...]
+```
+
+### ✅ MVI Compliant (~50 lines)
+
+````markdown
+# Concept: JWT Authentication
+
+**Core Idea**: Stateless authentication using JSON Web Tokens signed
+with a secret key. Token contains user data (payload) that server can
+trust because signature is verified.
+
+**Key Points**:
+
+- Token has 3 parts: header.payload.signature (Base64 encoded)
+- Server verifies signature to trust payload without database lookup
+- No session storage needed (stateless)
+- Tokens expire (include `exp` claim)
+- Store in httpOnly cookie or Authorization header
+
+**Quick Example**:
+
+```js
+// Sign token
+const token = jwt.sign({ userId: 123, role: "admin" }, SECRET_KEY, { expiresIn: "1h" })
+
+// Verify token
+const decoded = jwt.verify(token, SECRET_KEY)
+console.log(decoded.userId) // 123
+```
+````
+
+**Reference**: https://jwt.io/introduction
+
+**Related**:
+
+- examples/jwt-auth-example.md
+- guides/implementing-jwt.md
+- errors/auth-errors.md
+
+```
+
+---
+
+## File Size Limits
+
+<rule id="size_limits" enforcement="strict">
+  - Concept files: max 100 lines
+  - Example files: max 80 lines
+  - Guide files: max 150 lines
+  - Lookup files: max 100 lines
+  - Error files: max 150 lines
+  - README files: max 100 lines
+</rule>
+
+**Why**: Forces brevity. If you need more, split into multiple files or reference external docs.
+
+---
+
+## Validation Checklist
+
+Before creating a context file, verify:
+
+- [ ] Core concept is 1-3 sentences?
+- [ ] Key points are 3-5 bullets?
+- [ ] Example is <10 lines of code?
+- [ ] Reference link is included?
+- [ ] File is <200 lines total?
+- [ ] Can be scanned in <30 seconds?
+
+If any answer is "no", apply more compression.
+
+---
+
+## Related
+
+- structure.md - Where files go
+- compact.md - How to minimize
+- templates.md - Standard formats
+- creation.md - File creation rules
+```

package/.plcode/context/core/context-system/standards/structure.md

@@ -0,0 +1,262 @@
+# Context Structure
+
+**Purpose**: Function-based folder organization for easy discovery
+
+**Last Updated**: 2026-01-06
+
+---
+
+## Core Structure
+
+<rule id="function_structure" enforcement="strict">
+  ALWAYS organize by function (what info does), not just by topic.
+  
+  Required folders:
+  - concepts/  - Core ideas, definitions, "what is it?"
+  - examples/  - Minimal working code
+  - guides/    - Step-by-step workflows
+  - lookup/    - Quick reference tables, commands, paths
+  - errors/    - Common issues, gotchas, fixes
+</rule>
+
+```
+.plcode/context/{category}/
+├── navigation.md              # Navigation map (REQUIRED)
+├── concepts/              # What it is
+│   └── {topic}.md
+├── examples/              # Working code
+│   └── {example}.md
+├── guides/                # How to do it
+│   └── {guide}.md
+├── lookup/                # Quick reference
+│   └── {reference}.md
+└── errors/                # Common issues
+    └── {framework}.md
+```
+
+---
+
+## Folder Purposes
+
+### concepts/
+
+**Purpose**: Core ideas, definitions, "what is it?"
+
+**Contains**:
+
+- Fundamental concepts
+- Design patterns
+- Architecture decisions
+- System principles
+
+**Examples**:
+
+- `concepts/authentication.md`
+- `concepts/state-management.md`
+- `concepts/mvi-principle.md`
+
+---
+
+### examples/
+
+**Purpose**: Minimal working code examples
+
+**Contains**:
+
+- Code snippets that work as-is
+- Minimal reproductions
+- Common patterns in action
+
+**Examples**:
+
+- `examples/jwt-auth-example.md`
+- `examples/react-hooks-example.md`
+- `examples/api-call-example.md`
+
+**Rule**: Examples should be <30 lines of code, fully functional
+
+---
+
+### guides/
+
+**Purpose**: Step-by-step workflows, "how to do X"
+
+**Contains**:
+
+- Numbered procedures
+- Setup instructions
+- Implementation workflows
+- Migration guides
+
+**Examples**:
+
+- `guides/setting-up-auth.md`
+- `guides/deploying-api.md`
+- `guides/migrating-to-v2.md`
+
+**Rule**: Steps should be actionable (not theoretical)
+
+---
+
+### lookup/
+
+**Purpose**: Quick reference tables, commands, paths
+
+**Contains**:
+
+- Command lists
+- File locations
+- API endpoints
+- Configuration options
+- Keyboard shortcuts
+
+**Examples**:
+
+- `lookup/cli-commands.md`
+- `lookup/file-locations.md`
+- `lookup/api-endpoints.md`
+
+**Rule**: Must be in table/list format (scannable)
+
+---
+
+### errors/
+
+**Purpose**: Common errors, gotchas, edge cases
+
+**Contains**:
+
+- Error messages + fixes
+- Common pitfalls
+- Edge cases
+- Troubleshooting
+
+**Examples**:
+
+- `errors/react-errors.md`
+- `errors/nextjs-build-errors.md`
+- `errors/auth-errors.md`
+
+**Rule**: Group by framework/topic, not one file per error
+
+---
+
+## navigation.md Requirement
+
+<rule id="readme_required" enforcement="strict">
+  Every context category MUST have navigation.md at its root with:
+  1. Purpose (1-2 sentences)
+  2. Navigation tables for each function folder
+  3. Priority levels (critical/high/medium/low)
+  4. Loading strategy (what to load for common tasks)
+</rule>
+
+**Example**:
+
+```markdown
+# Development Context
+
+**Purpose**: Core development patterns, errors, and examples
+
+---
+
+## Quick Navigation
+
+### Concepts
+
+| File                        | Description             | Priority |
+| --------------------------- | ----------------------- | -------- |
+| [auth.md](concepts/auth.md) | Authentication patterns | critical |
+
+### Examples
+
+| File                      | Description      | Priority |
+| ------------------------- | ---------------- | -------- |
+| [jwt.md](examples/jwt.md) | JWT auth example | high     |
+
+### Errors
+
+| File                        | Description         | Priority |
+| --------------------------- | ------------------- | -------- |
+| [react.md](errors/react.md) | Common React errors | high     |
+
+---
+
+## Loading Strategy
+
+**For auth work**:
+
+1. Load concepts/auth.md
+2. Load examples/jwt.md
+3. Reference guides/setup-auth.md if needed
+```
+
+---
+
+## Categorization Rules
+
+When organizing a file, ask:
+
+| Question                                 | Folder      |
+| ---------------------------------------- | ----------- |
+| Does it explain **what** something is?   | `concepts/` |
+| Does it show **working code**?           | `examples/` |
+| Does it explain **how to do** something? | `guides/`   |
+| Is it **quick reference** data?          | `lookup/`   |
+| Does it document an **error/issue**?     | `errors/`   |
+
+---
+
+## Anti-Patterns ❌
+
+### ❌ Flat Structure
+
+```
+development/
+├── authentication.md
+├── jwt-example.md
+├── setting-up-auth.md
+├── auth-errors.md
+└── api-endpoints.md
+```
+
+**Problem**: Hard to discover. Is authentication.md a concept or guide?
+
+### ✅ Function-Based
+
+```
+development/
+├── navigation.md
+├── concepts/
+│   └── authentication.md
+├── examples/
+│   └── jwt-example.md
+├── guides/
+│   └── setting-up-auth.md
+├── lookup/
+│   └── api-endpoints.md
+└── errors/
+    └── auth-errors.md
+```
+
+**Benefit**: Instantly know file purpose by location
+
+---
+
+## Validation
+
+Before committing context structure:
+
+- [ ] All categories have navigation.md?
+- [ ] Files are in function folders (not flat)?
+- [ ] README has navigation tables?
+- [ ] Priority levels assigned?
+- [ ] Loading strategy documented?
+
+---
+
+## Related
+
+- mvi-principle.md - What to extract
+- templates.md - File formats
+- creation.md - How to create files