@iamnishankhan/opencode-kit-grok 1.0.0

package/kit/.opencode/skills/lint-and-validate/scripts/type_coverage.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""Pragmatic TypeScript and Python type-safety checker.
+
+The checker prefers real compiler output when a local TypeScript compiler is
+available. Its source fallback focuses on explicit escape hatches such as
+``any`` and ``@ts-ignore``; inferred TypeScript return types are not treated as
+coverage failures.
+"""
+from __future__ import annotations
+
+import ast
+import json
+import math
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+SKIP_DIRS = {
+    ".git",
+    ".next",
+    ".venv",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "out",
+    "venv",
+    "__pycache__",
+}
+
+
+def _source_files(project: Path, suffixes: set[str]) -> list[Path]:
+    files: list[Path] = []
+    for path in project.rglob("*"):
+        if not path.is_file() or path.suffix.lower() not in suffixes:
+            continue
+        if any(part in SKIP_DIRS for part in path.parts):
+            continue
+        if path.name.endswith(".d.ts"):
+            continue
+        files.append(path)
+    return sorted(files)
+
+
+def _local_tsc(tsconfig: Path) -> Path | None:
+    executable = "tsc.cmd" if sys.platform == "win32" else "tsc"
+    for parent in (tsconfig.parent, *tsconfig.parents):
+        candidate = parent / "node_modules" / ".bin" / executable
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _run_typescript_compilers(project: Path) -> list[dict[str, Any]]:
+    runs: list[dict[str, Any]] = []
+    tsconfigs = [
+        path
+        for path in project.rglob("tsconfig.json")
+        if not any(part in SKIP_DIRS for part in path.parts)
+    ]
+    for tsconfig in sorted(tsconfigs):
+        compiler = _local_tsc(tsconfig)
+        if compiler is None:
+            runs.append({"config": str(tsconfig), "status": "skipped", "reason": "local tsc not installed"})
+            continue
+        proc = subprocess.run(
+            [str(compiler), "--noEmit", "--pretty", "false", "-p", str(tsconfig)],
+            cwd=tsconfig.parent,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=180,
+        )
+        runs.append(
+            {
+                "config": str(tsconfig),
+                "status": "passed" if proc.returncode == 0 else "failed",
+                "returncode": proc.returncode,
+                "output": "\n".join(part.strip() for part in (proc.stdout, proc.stderr) if part.strip())[-4000:],
+            }
+        )
+    return runs
+
+
+def check_typescript_coverage(project_path: Path) -> dict[str, Any]:
+    issues: list[str] = []
+    passed: list[str] = []
+    files = _source_files(project_path, {".ts", ".tsx"})
+    stats: dict[str, Any] = {
+        "any_count": 0,
+        "suppression_count": 0,
+        "files_with_any": 0,
+        "compiler_runs": [],
+    }
+
+    if not files:
+        return {"type": "typescript", "files": 0, "passed": [], "issues": ["[!] No TypeScript files found"], "stats": stats}
+
+    any_pattern = re.compile(r"(?::\s*any\b|\bas\s+any\b|<any>)")
+    suppression_pattern = re.compile(r"@ts-(?:ignore|nocheck)")
+    for file_path in files:
+        content = file_path.read_text("utf-8", errors="ignore")
+        any_count = len(any_pattern.findall(content))
+        stats["any_count"] += any_count
+        stats["files_with_any"] += int(any_count > 0)
+        stats["suppression_count"] += len(suppression_pattern.findall(content))
+
+    any_fail_threshold = max(10, math.ceil(len(files) * 0.25))
+    suppression_fail_threshold = max(3, math.ceil(len(files) * 0.05))
+
+    if stats["any_count"] == 0:
+        passed.append("[OK] No explicit 'any' escape hatches found")
+    elif stats["any_count"] > any_fail_threshold:
+        issues.append(
+            f"[X] {stats['any_count']} explicit 'any' usages exceed the project threshold of {any_fail_threshold}"
+        )
+    else:
+        issues.append(
+            f"[!] {stats['any_count']} explicit 'any' usages across {stats['files_with_any']} file(s)"
+        )
+
+    if stats["suppression_count"] > suppression_fail_threshold:
+        issues.append(
+            f"[X] {stats['suppression_count']} TypeScript suppression comments exceed the threshold of {suppression_fail_threshold}"
+        )
+    elif stats["suppression_count"]:
+        issues.append(f"[!] {stats['suppression_count']} TypeScript suppression comment(s) found")
+    else:
+        passed.append("[OK] No @ts-ignore or @ts-nocheck suppressions found")
+
+    stats["compiler_runs"] = _run_typescript_compilers(project_path)
+    failed_runs = [run for run in stats["compiler_runs"] if run["status"] == "failed"]
+    completed_runs = [run for run in stats["compiler_runs"] if run["status"] == "passed"]
+    if failed_runs:
+        issues.append(f"[X] TypeScript compiler failed for {len(failed_runs)} project(s)")
+    elif completed_runs:
+        passed.append(f"[OK] TypeScript compiler passed for {len(completed_runs)} project(s)")
+    elif stats["compiler_runs"]:
+        passed.append("[OK] Compiler check skipped because project-local tsc is not installed")
+
+    passed.append(f"[OK] Analyzed {len(files)} TypeScript files")
+    return {"type": "typescript", "files": len(files), "passed": passed, "issues": issues, "stats": stats}
+
+
+def _annotation_complete(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    positional = [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs]
+    relevant = [arg for arg in positional if arg.arg not in {"self", "cls"}]
+    args_typed = all(arg.annotation is not None for arg in relevant)
+    varargs_typed = node.args.vararg is None or node.args.vararg.annotation is not None
+    kwargs_typed = node.args.kwarg is None or node.args.kwarg.annotation is not None
+    return args_typed and varargs_typed and kwargs_typed and node.returns is not None
+
+
+def check_python_coverage(project_path: Path) -> dict[str, Any]:
+    issues: list[str] = []
+    passed: list[str] = []
+    files = _source_files(project_path, {".py"})
+    stats = {"typed_functions": 0, "untyped_functions": 0, "any_count": 0, "parse_errors": 0}
+
+    if not files:
+        return {"type": "python", "files": 0, "passed": [], "issues": ["[!] No Python files found"], "stats": stats}
+
+    for file_path in files:
+        try:
+            tree = ast.parse(file_path.read_text("utf-8", errors="ignore"), filename=str(file_path))
+        except SyntaxError:
+            stats["parse_errors"] += 1
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                key = "typed_functions" if _annotation_complete(node) else "untyped_functions"
+                stats[key] += 1
+            elif isinstance(node, ast.Name) and node.id == "Any":
+                stats["any_count"] += 1
+
+    total = stats["typed_functions"] + stats["untyped_functions"]
+    typed_ratio = (stats["typed_functions"] / total * 100) if total else 100.0
+    stats["typed_ratio"] = round(typed_ratio, 2)
+
+    if stats["parse_errors"]:
+        issues.append(f"[X] {stats['parse_errors']} Python file(s) could not be parsed")
+    if typed_ratio >= 65:
+        passed.append(f"[OK] Fully annotated Python functions: {typed_ratio:.0f}%")
+    elif typed_ratio >= 40:
+        issues.append(f"[!] Fully annotated Python functions: {typed_ratio:.0f}%")
+    else:
+        issues.append(f"[X] Fully annotated Python functions: {typed_ratio:.0f}%")
+
+    any_fail_threshold = max(50, len(files) * 3)
+    if stats["any_count"] == 0:
+        passed.append("[OK] No Python Any references found")
+    elif stats["any_count"] > any_fail_threshold:
+        issues.append(
+            f"[X] {stats['any_count']} Python Any references exceed the project threshold of {any_fail_threshold}"
+        )
+    else:
+        issues.append(f"[!] {stats['any_count']} Python Any reference(s) found")
+
+    passed.append(f"[OK] Analyzed {len(files)} Python files")
+    return {"type": "python", "files": len(files), "passed": passed, "issues": issues, "stats": stats}
+
+
+def main() -> int:
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    if not project_path.is_dir():
+        print(json.dumps({"error": f"Directory not found: {project_path}"}))
+        return 2
+
+    print("\n" + "=" * 60)
+    print("  TYPE SAFETY CHECKER")
+    print("=" * 60 + "\n")
+
+    results = [
+        result
+        for result in (
+            check_typescript_coverage(project_path),
+            check_python_coverage(project_path),
+        )
+        if result["files"] > 0
+    ]
+    if not results:
+        print("[!] No TypeScript or Python files found.")
+        return 0
+
+    critical_issues = 0
+    for result in results:
+        print(f"\n[{result['type'].upper()}]\n" + "-" * 40)
+        for item in result["passed"]:
+            print(f"  {item}")
+        for item in result["issues"]:
+            print(f"  {item}")
+            critical_issues += int(item.startswith("[X]"))
+
+    print("\n" + "=" * 60)
+    if critical_issues:
+        print(f"[X] TYPE SAFETY: {critical_issues} blocking issue(s)")
+        return 1
+    print("[OK] TYPE SAFETY: ACCEPTABLE")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/kit/.opencode/skills/mcp-builder/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: mcp-builder
+description: MCP (Model Context Protocol) server and client engineering. Protocol design, schemas, transports, extensions, security, and migration.
+compatibility: opencode
+metadata:
+  when_to_use: "\"When building or reviewing MCP servers or clients, designing MCP tools/resources/prompts, migrating protocol versions, or validating MCP security and interoperability.\""
+  version: "1.0.0"
+---
+# MCP Builder
+
+> Build interoperable MCP implementations against the stable **2026-07-28** specification. Treat extensions as negotiated, opt-in capabilities rather than core protocol guarantees.
+
+---
+
+## 1. Stable baseline and compatibility
+
+- The authoritative stable baseline is MCP **2026-07-28**.
+- Core requests are stateless and self-contained. Do not infer protocol version, client capabilities, identity, conversation, or task state from a transport connection or process lifetime.
+- Put cross-request state behind explicit identifiers supplied on every relevant request.
+- Negotiate the protocol version and capabilities; do not assume that a client or server implements every optional feature.
+- Preserve compatibility with earlier peers where the specification requires it, including accepting legacy resource-not-found error code `-32002` while emitting `-32602` for invalid parameters in the current protocol.
+
+### Core versus extensions
+
+| Layer | Status | Engineering rule |
+| --- | --- | --- |
+| Base protocol, versioning, message patterns | Stable core | Required for every implementation |
+| Resources, prompts, tools, elicitation | Optional core features | Advertise and check capabilities before use |
+| Tasks, Skills over MCP, MCP Apps | Extensions | Opt-in; require explicit support from both peers |
+| Draft or vendor extensions | Experimental/vendor-specific | Isolate behind adapters and feature flags |
+
+Never label an extension as stable merely because one SDK or host supports it. Check the extension's own official status and version.
+
+---
+
+## 2. Architecture
+
+MCP uses JSON-RPC 2.0 between hosts, clients, and servers.
+
+```text
+host application
+  └─ MCP client / runtime adapter
+       ├─ stdio transport
+       └─ Streamable HTTP transport
+            └─ MCP server
+                 ├─ resources
+                 ├─ prompts
+                 └─ tools
+```
+
+### Stateless request model
+
+Every request must carry the protocol metadata required by the negotiated version. For 2026-07-28 this includes per-request protocol version and client capability metadata under reserved `_meta` keys.
+
+Servers must implement `server/discover` for protocol-version and capability discovery. Clients may call it before normal requests or use it as a backward-compatibility probe for stdio peers.
+
+Do not:
+
+- use a stdio process as a conversation or session boundary;
+- depend on request ordering to establish capabilities or identity;
+- keep hidden mutable state without an explicit handle;
+- use self-reported client/server information for authorization decisions.
+
+Do:
+
+- make task, thread, workspace, or subscription handles explicit;
+- validate every request independently;
+- tolerate interleaved requests from unrelated tasks;
+- document lifecycle, expiry, and cleanup for durable handles.
+
+---
+
+## 3. Transports and authentication
+
+| Transport | Typical use | Security baseline |
+| --- | --- | --- |
+| `stdio` | Local process integration | Read credentials from the environment; constrain process and filesystem access |
+| Streamable HTTP | Remote or shared service | Use the MCP HTTP authorization framework, validate origins where applicable, and enforce network boundaries |
+
+WebSocket is not a standard MCP transport unless defined by a separately negotiated extension or vendor adapter.
+
+Transport concerns must not leak into protocol semantics. Reconnection or process replacement must not destroy logical state that is represented by an explicit durable handle.
+
+---
+
+## 4. Schema design and validation
+
+MCP defaults to **JSON Schema 2020-12** when `$schema` is absent. Implementations must support that dialect and should document any additional dialects.
+
+### Tool input schemas
+
+- Use an object root for tool arguments.
+- Give every property a clear, action-oriented description.
+- Declare required fields explicitly.
+- Prefer narrow enums, bounds, formats, and `additionalProperties: false` where forward compatibility does not require open objects.
+- Validate both the schema and each invocation payload.
+
+### Tool output schemas
+
+Use structured content and `outputSchema` when consumers need typed, predictable results. Keep human-readable text concise and ensure structured output remains the source of truth for automation.
+
+### `$ref` and validator safety
+
+- Never dereference network `$ref` values automatically.
+- If remote dereferencing is explicitly enabled, use a host allowlist; reject loopback, link-local, and private addresses; apply timeouts and response-size limits; and log resolved URIs without secrets.
+- Reject schemas with unresolved external references instead of treating them as permissive.
+- Bound schema depth, total subschemas, and validation time to prevent denial-of-service through composition keywords or recursive references.
+
+---
+
+## 5. Tool, resource, and prompt design
+
+### Tools
+
+- Use clear action names and a single responsibility.
+- Mark read-only, destructive, idempotent, or open-world behavior with annotations when useful, but treat annotations as untrusted hints unless the server itself is trusted.
+- Require explicit user approval for consequential actions.
+- Return stable machine-readable errors without internal stack traces or secrets.
+
+### Resources
+
+- Use stable URIs and MIME types.
+- Separate discovery metadata from resource content.
+- Apply authorization per resource, not only per server connection.
+- Avoid silently forwarding resource data to another server or model without user consent.
+
+### Prompts
+
+- Treat prompts as user-visible templates, not hidden authority.
+- Keep tool permissions and policy enforcement outside prompt text.
+- Validate prompt arguments and clearly identify any data sources included in generated messages.
+
+---
+
+## 6. Security requirements
+
+1. **Consent and least privilege** — expose only required data and obtain explicit approval before tool execution or data sharing.
+2. **Untrusted metadata** — do not use tool descriptions, annotations, client info, server info, or model-produced arguments as authorization evidence.
+3. **Input and output validation** — validate schemas, arguments, structured results, URIs, and content types at trust boundaries.
+4. **Secret handling** — load credentials from environment or a secret manager; never place real keys in repository configuration, logs, traces, prompts, or error payloads.
+5. **Network controls** — defend remote schema/resource fetching against SSRF, redirect abuse, oversized responses, and slow responses.
+6. **Execution isolation** — sandbox subprocesses and filesystem access; use explicit path grants and reject archive or symlink escapes.
+7. **Auditability** — record security-relevant decisions, approvals, tool identity, and result status without storing sensitive payloads unnecessarily.
+
+---
+
+## 7. Extensions
+
+Extensions are negotiated independently from the core protocol.
+
+| Extension | Use | Guardrail |
+| --- | --- | --- |
+| Tasks | Long-running work, polling, durable handles, mid-flight input | Do not use the older experimental task API; negotiate the extension |
+| Skills over MCP | Discoverable structured agent instructions | Treat skill content as untrusted input and apply host policy |
+| MCP Apps | Interactive UI rendered in conversations | Constrain origins, content, data access, and action permissions |
+
+An adapter must fail gracefully when an extension is absent. Never silently downgrade a security requirement to preserve feature parity.
+
+---
+
+## 8. Deprecated features and migration
+
+The 2026-07-28 specification deprecates legacy roots, sampling, and logging shapes while keeping a compatibility window. Do not remove compatibility abruptly, but avoid designing new architecture around deprecated forms.
+
+### Migration checklist from 2025-era implementations
+
+- [ ] Replace connection-scoped sessions and the `initialize` handshake with stateless per-request metadata.
+- [ ] Implement or consume `server/discover` for version and capability selection.
+- [ ] Move durable state behind explicit task, thread, workspace, or application handles.
+- [ ] Send and validate negotiated protocol version and client capabilities on every request.
+- [ ] Upgrade schema validation to JSON Schema 2020-12 by default.
+- [ ] Disable network `$ref` resolution by default and add validation resource limits.
+- [ ] Move experimental Tasks usage to the negotiated Tasks extension.
+- [ ] Accept legacy `-32002` resource-not-found responses, but emit current error semantics.
+- [ ] Treat a missing `resultType` from older servers as `"complete"`; require it for current-version results.
+- [ ] Audit roots, sampling, and logging integrations for their documented replacements and deprecation timeline.
+- [ ] Add interoperability tests against at least one older peer and one 2026-07-28 peer.
+
+---
+
+## 9. Testing matrix
+
+| Test | Expected evidence |
+| --- | --- |
+| Contract | Invalid JSON-RPC, missing metadata, unsupported version/capability, schema dialect handling |
+| Statelessness | Interleaved requests, reconnects, process reuse, explicit-handle recovery |
+| Schema security | External `$ref`, recursive/composed schemas, depth/count/time limits |
+| Authorization | Denied resource/tool access, approval gates, credential isolation |
+| Extension negotiation | Extension absent, version mismatch, feature enabled, graceful fallback |
+| Compatibility | Current peer plus supported older protocol revision |
+| Failure handling | Timeouts, cancellation, partial results, structured errors, no secret leakage |
+
+---
+
+## 10. Review checklist
+
+- [ ] Stable protocol version and extension status are documented.
+- [ ] Requests are stateless; cross-request state uses explicit handles.
+- [ ] Capabilities are negotiated and checked before optional operations.
+- [ ] JSON Schema 2020-12 is supported and validator resource use is bounded.
+- [ ] Network `$ref` resolution is disabled by default.
+- [ ] Tool annotations are not trusted as authorization.
+- [ ] User approval, least privilege, secret handling, and execution isolation are enforced outside prompts.
+- [ ] Deprecated features have a compatibility and migration plan.
+- [ ] Contract, security, extension, and cross-version tests pass.

package/kit/.opencode/skills/memory-system/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: memory-system
+description: Persistent cross-session memory management. Enables agents to remember user preferences, project conventions, and past decisions across different sessions using a structured MEMORY.md index and topic files.
+compatibility: opencode
+metadata:
+  when_to_use: "\"When the user says 'remember this', 'save this for later', 'don't forget', or when starting a new session and needing to recall past context. Also when /remember workflow is invoked.\""
+  version: "1.0.0"
+---
+# Memory System — Persistent Cross-Session Memory
+
+> Enables agents to remember across sessions. Never re-discover what was already learned.
+
+## Overview
+
+The Memory System provides **persistent, searchable memory** that survives across sessions. Instead of re-explaining preferences, conventions, and past decisions every time, agents read a structured MEMORY.md index and topic files.
+
+**Token Impact:** +1,000 tokens to load index, but saves 3,000-10,000 tokens by eliminating re-discovery.
+
+---
+
+## Architecture
+
+```
+.opencode/memory/
+├── MEMORY.md              ← Lightweight index (max 200 lines)
+├── user-preferences.md    ← Topic file: user role, style, tools
+├── project-conventions.md ← Topic file: coding standards, patterns
+├── tech-decisions.md      ← Topic file: past architectural decisions
+├── feedback-history.md    ← Topic file: what user liked/disliked
+└── [topic-name].md        ← Additional topic files as needed
+```
+
+---
+
+## MEMORY.md Index Format
+
+The index is a **lightweight pointer file** — short entries that reference topic files for details.
+
+**Rules:**
+- Maximum **200 lines** total
+- Each entry: **~150 characters max**
+- Format: `- [type] summary → topic-file.md`
+- Types: `[user]` `[feedback]` `[project]` `[reference]`
+
+**Example:**
+```markdown
+# Memory Index
+
+## User
+- [user] Prefers dark mode, uses Windows 11, PowerShell → user-preferences.md
+- [user] Senior DevOps engineer, 8 years experience → user-preferences.md
+- [user] Primary language: English, sometimes Turkish → user-preferences.md
+
+## Project
+- [project] Always use bun instead of npm → project-conventions.md
+- [project] Tailwind v4 preferred, no v3 → tech-decisions.md
+- [project] No purple/violet colors in UI → project-conventions.md
+
+## Feedback
+- [feedback] User likes concise responses, no filler → feedback-history.md
+- [feedback] User dislikes verbose explanations → feedback-history.md
+- [feedback] User prefers tables over bullet lists → feedback-history.md
+
+## Reference
+- [reference] Squid proxy runs on port 3128 → infrastructure-notes.md
+- [reference] Git workflow: feature branches → main → project-conventions.md
+```
+
+---
+
+## Topic File Format
+
+Each topic file has **frontmatter** and **structured content**:
+
+```markdown
+---
+type: user | feedback | project | reference
+created: 2026-04-01
+updated: 2026-04-01
+---
+
+# User Preferences
+
+## Development Environment
+- OS: Windows 11
+- Shell: PowerShell
+- Editor: Cursor / Windsurf
+- Package Manager: bun (NOT npm)
+
+## Communication Style
+- Prefers concise responses
+- Likes tables for comparisons
+- Dislikes verbose explanations
+```
+
+---
+
+## Memory Taxonomy
+
+| Type | What to Store | Example |
+|------|--------------|---------|
+| **user** | Role, preferences, tools, communication style | "Senior DevOps, prefers dark mode" |
+| **feedback** | What user liked/disliked about agent output | "User said 'too verbose', prefers tables" |
+| **project** | Coding standards, tech choices, conventions | "Use bun not npm, Tailwind v4" |
+| **reference** | Non-sensitive infrastructure notes, public URLs, configs | "Prod API hostname and port" |
+
+---
+
+## What NOT to Save
+
+| Don't Save | Why |
+|---|---|
+| Secrets, credentials, tokens, passwords, private keys, or API keys | Memory is persistent and may be shared across sessions |
+| Information derivable from code | Read `package.json` instead of memorizing deps |
+| Temporary debug context | Clutters memory, not useful later |
+| Exact code snippets | Code changes — memory becomes stale |
+| File paths that may move | Use glob patterns or descriptions instead |
+| Entire conversation transcripts | Memory is for distilled insights only |
+
+---
+
+## Operations
+
+### Save (Trigger: user says "remember", "save", "don't forget")
+
+1. Identify the information type (user/feedback/project/reference)
+2. Check if relevant topic file exists
+3. If yes → append to existing topic file
+4. If no → create new topic file with frontmatter
+5. Update MEMORY.md index with one-line pointer
+6. Confirm to user: "Saved to memory: [summary]"
+
+### Recall (Trigger: session start, or "what do you remember about X")
+
+1. Read `.opencode/memory/MEMORY.md` index
+2. Scan for relevant entries matching the current task
+3. If match found → read the referenced topic file
+4. Apply recalled context silently (don't recite memories unless asked)
+
+### Search (Trigger: "do I have any notes about X")
+
+1. Grep across `.opencode/memory/*.md` for the search term
+2. Return matching entries with file references
+3. Offer to read full topic file if user wants details
+
+### Prune (Trigger: index exceeds 200 lines)
+
+1. Warn: "Memory index is getting large (X lines). Review recommended."
+2. Suggest merging related entries
+3. Suggest archiving old entries to `.opencode/memory/archive/`
+4. Never auto-delete — always ask user first
+
+---
+
+## Session Start Protocol
+
+At the start of every session:
+
+```
+1. Check: Does `.opencode/memory/MEMORY.md` exist?
+   → YES: Read index. Apply relevant context silently.
+   → NO: Continue without memory. Create on first "remember" trigger.
+
+2. Apply memory WITHOUT reciting it.
+   ❌ WRONG: "I remember you prefer dark mode and use bun..."
+   ✅ RIGHT: (silently apply preferences, use bun in commands)
+
+3. Exception: If user asks "what do you remember?" → recite relevant memories.
+```
+
+---
+
+## Memory vs. Plan vs. Task
+
+| Artifact | Purpose | Lifespan | Location |
+|----------|---------|----------|----------|
+| **Memory** | Cross-session knowledge | Permanent until pruned | `.opencode/memory/` |
+| **Plan** | Task breakdown for current project | Until project complete | Project root |
+| **Task** | Progress tracker for current session | Until session ends | Artifact directory |
+
+> Memory = what you KNOW. Plan = what you'll DO. Task = what you're DOING NOW.