plcode-linux-arm64-musl 2.1.0

package/.plcode/context/core/context-system/guides/compact.md

@@ -0,0 +1,351 @@
+# Context Compaction (Minimization)
+
+**Purpose**: Compress verbose content into minimal viable information
+
+**Last Updated**: 2026-01-06
+
+---
+
+## The Compaction Process
+
+Transform verbose explanations → core concepts following MVI principle.
+
+**Formula**:
+
+```
+Verbose Content (100+ lines)
+  ↓ Extract Core
+Core Concept (1-3 sentences)
+  ↓ Extract Key Points
+Key Points (3-5 bullets)
+  ↓ Extract Example
+Minimal Example (<10 lines)
+  ↓ Add Reference
+Link to Full Docs
+  ↓ Result
+Compact File (<100 lines)
+```
+
+---
+
+## Compression Techniques
+
+### 1. Extract Core Concept
+
+**From**: Paragraphs of explanation
+**To**: 1-3 sentences capturing essence
+
+**Example**:
+
+```markdown
+BEFORE (verbose):
+"React Hooks are a new addition to React 16.8 that let you use state
+and other React features without writing a class. They're functions that
+let you "hook into" React state and lifecycle features from function
+components. Hooks don't work inside classes — they let you use React
+without classes. You can also create your own Hooks to reuse stateful
+behavior between different components..."
+
+AFTER (compact):
+"Hooks let you use state and lifecycle in function components without
+classes. They're functions that hook into React features (useState,
+useEffect, etc)."
+```
+
+**Rule**: If you can't explain it in 3 sentences, you don't understand it yet. Simplify further.
+
+---
+
+### 2. Bulletize Key Points
+
+**From**: Long paragraphs
+**To**: 3-5 bullet points
+
+**Example**:
+
+```markdown
+BEFORE:
+"When using hooks, there are several important rules to follow. First,
+only call hooks at the top level of your function, never inside loops,
+conditions, or nested functions. Second, only call hooks from React
+function components or custom hooks. Third, hooks should be called in
+the same order every render..."
+
+AFTER:
+**Key Points**:
+
+- Call hooks at top level only (not in loops/conditions)
+- Call from function components or custom hooks only
+- Must be called in same order every render
+- Names should start with "use" (convention)
+```
+
+**Rule**: Each bullet = one key fact. No sub-bullets.
+
+---
+
+### 3. Minimize Examples
+
+**From**: Full implementations
+**To**: Smallest working example (<10 lines)
+
+**Example**:
+
+````markdown
+BEFORE (50 lines):
+import React, { useState, useEffect } from 'react'
+import axios from 'axios'
+
+function UserProfile({ userId }) {
+const [user, setUser] = useState(null)
+const [loading, setLoading] = useState(true)
+const [error, setError] = useState(null)
+
+useEffect(() => {
+const fetchUser = async () => {
+try {
+setLoading(true)
+const response = await axios.get(`/api/users/${userId}`)
+setUser(response.data)
+setError(null)
+} catch (err) {
+setError(err.message)
+setUser(null)
+} finally {
+setLoading(false)
+}
+}
+
+    fetchUser()
+
+}, [userId])
+
+if (loading) return <div>Loading...</div>
+if (error) return <div>Error: {error}</div>
+if (!user) return <div>No user found</div>
+
+return (
+
+<div>
+<h1>{user.name}</h1>
+<p>{user.email}</p>
+</div>
+)
+}
+
+AFTER (8 lines):
+
+```js
+const [count, setCount] = useState(0)
+
+useEffect(() => {
+  document.title = `Count: ${count}`
+}, [count]) // Re-run when count changes
+
+return <button onClick={() => setCount(count + 1)}>Clicked {count} times</button>
+```
+````
+
+**Rule**: Show the simplest case that demonstrates the concept. Link to full examples.
+
+---
+
+### 4. Replace Repetition with References
+
+**From**: Same info repeated in multiple places
+**To**: Define once, reference with links
+
+**Example**:
+
+```markdown
+BEFORE:
+
+# File A
+
+Authentication uses JWT tokens. JWT tokens are JSON Web Tokens that...
+
+# File B
+
+For auth, we use JWT tokens. JWT tokens are JSON Web Tokens that...
+
+# File C
+
+The JWT token system (JSON Web Tokens) allows us to...
+
+AFTER:
+
+# concepts/jwt.md
+
+"JWT (JSON Web Token) is a stateless authentication method..."
+
+# Other files
+
+See concepts/jwt.md for details.
+```
+
+**Rule**: Say it once in concepts/, reference everywhere else.
+
+---
+
+### 5. Convert Prose to Tables
+
+**From**: Paragraphs listing things
+**To**: Scannable tables
+
+**Example**:
+
+```markdown
+BEFORE:
+"There are several important lifecycle methods. componentDidMount runs
+after mounting, componentDidUpdate runs after updates, componentWillUnmount
+runs before unmounting..."
+
+AFTER:
+| Method | When It Runs |
+|--------|--------------|
+| componentDidMount | After mount |
+| componentDidUpdate | After update |
+| componentWillUnmount | Before unmount |
+```
+
+**Rule**: If listing >3 items, use a table or bullets.
+
+---
+
+## Compaction Checklist
+
+Before finalizing a context file:
+
+- [ ] Core concept is 1-3 sentences?
+- [ ] Key points are 3-5 bullets (no sub-bullets)?
+- [ ] Example is <10 lines of code?
+- [ ] No repeated explanations?
+- [ ] Reference link added for deep dive?
+- [ ] File is <200 lines total?
+- [ ] Can be scanned in <30 seconds?
+
+If any "no", compress further.
+
+---
+
+## Common Bloat Patterns
+
+### Bloat: Over-Explaining
+
+```markdown
+❌ "This is important because it allows you to manage state in a more
+efficient way, which can lead to better performance and cleaner code..."
+
+✅ "Manages state efficiently"
+```
+
+### Bloat: Historical Context
+
+```markdown
+❌ "Before React 16.8, we used class components. Then hooks were
+introduced to solve several problems with classes..."
+
+✅ Skip history unless critical. Just explain current approach.
+```
+
+### Bloat: Multiple Examples
+
+```markdown
+❌ Example 1: useState with counter
+Example 2: useState with string
+Example 3: useState with object
+Example 4: useState with array...
+
+✅ Show ONE simple example. Link to more.
+```
+
+### Bloat: Implementation Details
+
+```markdown
+❌ "The internal implementation uses a fiber architecture with a
+reconciliation algorithm that diffs the virtual DOM..."
+
+✅ Skip internal details. Just show how to use it.
+```
+
+---
+
+## Target Line Counts
+
+| File Type | Target Lines | Max Lines |
+| --------- | ------------ | --------- |
+| Concept   | 40-60        | 100       |
+| Example   | 30-50        | 80        |
+| Guide     | 60-100       | 150       |
+| Lookup    | 20-40        | 100       |
+| Error     | 50-80        | 150       |
+| README    | 40-60        | 100       |
+
+**Philosophy**: If you hit max lines, split into multiple files or reference external docs.
+
+---
+
+## The 30-Second Rule
+
+<rule id="thirty_second_rule" enforcement="strict">
+  Every context file must be scannable in <30 seconds.
+  
+  If a developer can't grasp the core idea in 30 seconds:
+  - File is too verbose
+  - Concept is not well explained
+  - Needs more compression
+</rule>
+
+**Test**: Give file to someone unfamiliar. Can they explain it back in 30 seconds?
+
+---
+
+## Compression Examples
+
+### Before: 150 lines
+
+```markdown
+# Authentication System
+
+Our authentication system is built on JSON Web Tokens (JWT), which
+is a standard for securely transmitting information between parties...
+
+[100+ more lines of explanation, edge cases, examples, etc.]
+```
+
+### After: 45 lines
+
+````markdown
+# Concept: Authentication
+
+**Core Idea**: JWT-based stateless auth. Token in httpOnly cookie,
+verified on every request.
+
+**Key Points**:
+
+- Token has userId + role claims
+- Expires in 1 hour (refresh token for renewal)
+- Stored in httpOnly cookie (XSS protection)
+- Verified via middleware on protected routes
+
+**Quick Example**:
+
+```js
+const token = jwt.sign({ userId: 123 }, SECRET, { expiresIn: "1h" })
+res.cookie("auth", token, { httpOnly: true })
+```
+````
+
+**Reference**: https://docs.company.com/auth
+**Related**: examples/jwt-auth.md, errors/auth-errors.md
+
+```
+
+---
+
+## Related
+
+- mvi-principle.md - What MVI is
+- harvest.md - When to compact (during extraction)
+- templates.md - Standard formats
+```

package/.plcode/context/core/context-system/guides/creation.md

@@ -0,0 +1,363 @@
+# Context File Creation Standards
+
+**Purpose**: Ensure all context files follow the same format and structure
+
+**Last Updated**: 2026-01-06
+
+---
+
+## Critical Rules
+
+<critical_rules priority="absolute" enforcement="strict">
+<rule id="size_limit">
+Files MUST be <200 lines. No exceptions.
+</rule>
+
+  <rule id="mvi_required">
+    All files MUST follow MVI: 1-3 sentence core, 3-5 key points, minimal example, reference link.
+  </rule>
+  
+  <rule id="function_placement">
+    Files MUST be in correct function folder: concepts/, examples/, guides/, lookup/, or errors/.
+  </rule>
+  
+  <rule id="readme_update">
+    MUST update category README.md navigation when creating files.
+  </rule>
+</critical_rules>
+
+---
+
+## Creation Workflow
+
+<workflow id="create_context_file">
+  <stage id="1" name="Determine Function">
+    Ask: Is this a concept, example, guide, lookup, or error?
+    → Place in correct folder
+  </stage>
+  
+  <stage id="2" name="Apply Template">
+    Use standard template for file type (see templates.md)
+  </stage>
+  
+  <stage id="3" name="Apply MVI">
+    - Core: 1-3 sentences
+    - Key points: 3-5 bullets
+    - Example: <10 lines
+    - Reference: Link to docs
+  </stage>
+  
+  <stage id="4" name="Validate Size">
+    Ensure file <200 lines. If not, split or reference external.
+  </stage>
+  
+  <stage id="5" name="Add Cross-References">
+    Link to related concepts/, examples/, guides/, errors/
+  </stage>
+  
+  <stage id="6" name="Update README">
+    Add entry to category README.md navigation table
+  </stage>
+  
+  <stage id="7" name="Verify">
+    - [ ] <200 lines?
+    - [ ] MVI format?
+    - [ ] Correct folder?
+    - [ ] README updated?
+    - [ ] Cross-refs added?
+  </stage>
+</workflow>
+
+---
+
+## File Naming Conventions
+
+### Concepts
+
+**Format**: `{topic}.md`
+**Examples**:
+
+- `authentication.md`
+- `state-management.md`
+- `mvi-principle.md`
+
+**Rule**: Lowercase, hyphenated, describes the concept
+
+---
+
+### Examples
+
+**Format**: `{what-it-demonstrates}.md`
+**Examples**:
+
+- `jwt-auth-example.md`
+- `react-hooks-example.md`
+- `api-call-example.md`
+
+**Rule**: End with `-example.md`, describes what it shows
+
+---
+
+### Guides
+
+**Format**: `{action-being-done}.md`
+**Examples**:
+
+- `setting-up-auth.md`
+- `deploying-api.md`
+- `migrating-to-v2.md`
+
+**Rule**: Gerund form (verbs ending in -ing), describes the task
+
+---
+
+### Lookup
+
+**Format**: `{what-is-referenced}.md`
+**Examples**:
+
+- `cli-commands.md`
+- `file-locations.md`
+- `api-endpoints.md`
+
+**Rule**: Plural noun, describes the reference type
+
+---
+
+### Errors
+
+**Format**: `{framework-or-topic}-errors.md`
+**Examples**:
+
+- `react-errors.md`
+- `nextjs-build-errors.md`
+- `auth-errors.md`
+
+**Rule**: End with `-errors.md`, group by framework/topic (NOT one file per error)
+
+---
+
+## Standard Metadata
+
+Every context file MUST start with:
+
+```markdown
+# {Type}: {Name}
+
+**Purpose**: [1 sentence describing what this file contains]
+
+**Last Updated**: {YYYY-MM-DD}
+
+---
+```
+
+**Example**:
+
+```markdown
+# Concept: JWT Authentication
+
+**Purpose**: Stateless authentication using signed JSON Web Tokens
+
+**Last Updated**: 2026-01-06
+
+---
+```
+
+---
+
+## Priority Assignment
+
+When adding files to README.md, assign priority:
+
+| Priority     | When to Use                                        |
+| ------------ | -------------------------------------------------- |
+| **critical** | Must understand to work on project. Core concepts. |
+| **high**     | Commonly used. Important patterns.                 |
+| **medium**   | Occasionally needed. Reference material.           |
+| **low**      | Rarely used. Edge cases.                           |
+
+**Example**:
+
+```markdown
+### Concepts
+
+| File                              | Description           | Priority |
+| --------------------------------- | --------------------- | -------- |
+| [auth.md](concepts/auth.md)       | Authentication system | critical |
+| [caching.md](concepts/caching.md) | Cache strategy        | high     |
+| [logging.md](concepts/logging.md) | Logging patterns      | medium   |
+```
+
+---
+
+## Cross-Reference Guidelines
+
+### When to Link
+
+Link to related files when:
+
+- Concept uses another concept
+- Example demonstrates a concept
+- Guide references concepts/examples
+- Error relates to specific concept
+
+### How to Link
+
+**Format**: `**Related**: type/file.md`
+
+**Example**:
+
+```markdown
+**Related**:
+
+- concepts/authentication.md
+- examples/jwt-auth-example.md
+- errors/auth-errors.md
+```
+
+**Rule**: Use relative paths from current location
+
+---
+
+## README.md Update Process
+
+When creating a new file:
+
+1. **Open category README.md**
+2. **Find correct section** (Concepts/Examples/Guides/Lookup/Errors)
+3. **Add table row**:
+   ```markdown
+   | [file.md](folder/file.md) | Description | priority |
+   ```
+4. **Sort by priority** (critical → high → medium → low)
+5. **Update "Last Updated"** date at top
+
+---
+
+## Validation Before Commit
+
+<validation>
+  <checklist>
+    - [ ] File is <200 lines?
+    - [ ] Follows MVI format (1-3 sentences, 3-5 points, example, reference)?
+    - [ ] In correct function folder (concepts/examples/guides/lookup/errors)?
+    - [ ] Has standard metadata (Purpose, Last Updated)?
+    - [ ] Added to README.md navigation?
+    - [ ] Priority assigned (critical/high/medium/low)?
+    - [ ] Cross-references added?
+    - [ ] Scannable in <30 seconds?
+    - [ ] No duplication of existing content?
+  </checklist>
+</validation>
+
+**If any checkbox is unchecked, fix before committing.**
+
+---
+
+## Common Creation Mistakes
+
+### ❌ Mistake 1: Wrong Folder
+
+```
+development/authentication.md  ❌ (flat structure)
+
+development/concepts/authentication.md  ✅ (function-based)
+```
+
+### ❌ Mistake 2: Too Verbose
+
+```markdown
+# Concept: JWT
+
+[500 lines of explanation, examples, edge cases...] ❌
+
+# Concept: JWT
+
+**Core Idea**: Stateless auth with signed tokens (1-3 sentences) ✅
+```
+
+### ❌ Mistake 3: Missing README Update
+
+```
+Created: concepts/new-topic.md
+README.md: Not updated  ❌
+
+Created: concepts/new-topic.md
+README.md: Updated with navigation entry  ✅
+```
+
+### ❌ Mistake 4: One Error Per File
+
+```
+errors/jwt-expired-error.md
+errors/jwt-invalid-error.md
+errors/jwt-missing-error.md  ❌ (too granular)
+
+errors/auth-errors.md  ✅ (grouped by topic)
+```
+
+---
+
+## File Size Enforcement
+
+<rule id="size_enforcement" enforcement="strict">
+  If file exceeds line limit:
+  
+  1. First: Apply more compression (see compact.md)
+  2. If still too large: Split into multiple files
+  3. If logically can't split: Move details to external docs, keep summary
+  
+  DO NOT exceed 200 lines under any circumstance.
+</rule>
+
+**Example**:
+
+```markdown
+If concepts/authentication.md hits 250 lines:
+
+Option 1: Compress (apply MVI more strictly)
+Option 2: Split:
+
+- concepts/authentication.md (core)
+- concepts/jwt-tokens.md (specific type)
+- concepts/oauth.md (another type)
+  Option 3: Reference external:
+- Keep 100-line summary in concepts/authentication.md
+- Link to https://docs.company.com/auth (full details)
+```
+
+---
+
+## Template Selection
+
+| File Type | Template                        | Max Lines |
+| --------- | ------------------------------- | --------- |
+| Concept   | templates.md → Concept Template | 100       |
+| Example   | templates.md → Example Template | 80        |
+| Guide     | templates.md → Guide Template   | 150       |
+| Lookup    | templates.md → Lookup Template  | 100       |
+| Error     | templates.md → Error Template   | 150       |
+| README    | templates.md → README Template  | 100       |
+
+---
+
+## Quality Standards
+
+Every context file must be:
+
+1. **Minimal** - <200 lines, no bloat
+2. **Scannable** - Can grasp in <30 seconds
+3. **Functional** - In correct function folder
+4. **Referenced** - Cross-links to related files
+5. **Discoverable** - Listed in README.md
+6. **Accurate** - Facts only, no speculation
+7. **Current** - Last Updated date maintained
+
+---
+
+## Related
+
+- templates.md - Standard file formats
+- mvi-principle.md - What to include
+- compact.md - How to minimize
+- structure.md - Where files go