local-cal/.opencode/context/core/context-system/standards/mvi.md

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)

# 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)

# 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