@suwujs/codex-vault 0.1.0

package/vault/.codex-vault/hooks/session-start.sh

@@ -0,0 +1,176 @@
+#!/bin/bash
+set -eo pipefail
+
+# Codex-Vault session-start hook
+# Injects vault context into the agent's prompt at session start.
+# Works with any agent that supports SessionStart hooks (Claude Code, Codex CLI).
+#
+# Dynamic context: adapts git log window, reads full North Star,
+# shows all active work, and includes uncommitted changes.
+
+VAULT_DIR="${CLAUDE_PROJECT_DIR:-${CODEX_PROJECT_DIR:-$(pwd)}}"
+cd "$VAULT_DIR"
+
+# Find vault root (look for Home.md or brain/ directory)
+if [ ! -f "Home.md" ] && [ ! -d "brain/" ]; then
+  # Try vault/ subdirectory (integrated layout)
+  if [ -d "vault/" ]; then
+    VAULT_DIR="$VAULT_DIR/vault"
+    cd "$VAULT_DIR"
+  fi
+fi
+
+echo "## Session Context"
+echo ""
+echo "### Date"
+echo "$(date +%Y-%m-%d) ($(date +%A))"
+echo ""
+
+# North Star — full file (should be concise by design)
+echo "### North Star"
+if [ -f "brain/North Star.md" ]; then
+  cat "brain/North Star.md"
+else
+  echo "(No North Star found — create brain/North Star.md to set goals)"
+fi
+echo ""
+
+# Recent changes — adaptive window
+echo "### Recent Changes"
+COMMITS_48H=$(git log --oneline --since="48 hours ago" --no-merges 2>/dev/null | wc -l | tr -d ' ')
+if [ "$COMMITS_48H" -gt 0 ]; then
+  echo "(last 48 hours)"
+  git log --oneline --since="48 hours ago" --no-merges 2>/dev/null | head -15
+else
+  COMMITS_7D=$(git log --oneline --since="7 days ago" --no-merges 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$COMMITS_7D" -gt 0 ]; then
+    echo "(nothing in 48h — showing last 7 days)"
+    git log --oneline --since="7 days ago" --no-merges 2>/dev/null | head -15
+  else
+    echo "(nothing recent — showing last 5 commits)"
+    git log --oneline -5 --no-merges 2>/dev/null || echo "(no git history)"
+  fi
+fi
+echo ""
+
+# Recent operations from log — adaptive
+echo "### Recent Operations"
+if [ -f "log.md" ]; then
+  ENTRY_COUNT=$(grep -c "^## \[" "log.md" 2>/dev/null || echo "0")
+  if [ "$ENTRY_COUNT" -gt 0 ]; then
+    # Show last 5 entries with full header line (includes date + type)
+    grep "^## \[" "log.md" | tail -5
+  else
+    echo "(no entries in log.md)"
+  fi
+else
+  echo "(no log.md)"
+fi
+echo ""
+
+# Active work — show all (this is the current focus, no truncation)
+echo "### Active Work"
+if [ -d "work/active" ]; then
+  WORK_FILES=$(ls work/active/*.md 2>/dev/null || true)
+  if [ -n "$WORK_FILES" ]; then
+    echo "$WORK_FILES" | sed 's|work/active/||;s|\.md$||'
+  else
+    echo "(none)"
+  fi
+else
+  echo "(no work/active/ directory)"
+fi
+echo ""
+
+# Uncommitted changes — shows agent what's in-flight
+echo "### Uncommitted Changes"
+CHANGES=$(git status --short -- . 2>/dev/null | head -20)
+if [ -n "$CHANGES" ]; then
+  echo "$CHANGES"
+else
+  echo "(working tree clean)"
+fi
+echo ""
+
+# Recently modified brain files — highlights memory that may need review
+echo "### Recently Modified Brain Files"
+if [ -d "brain" ]; then
+  GIT_DIR=$(git rev-parse --git-dir 2>/dev/null || echo "")
+  if [ -n "$GIT_DIR" ] && [ -f "$GIT_DIR/index" ]; then
+    RECENT_BRAIN=$(find brain/ -name "*.md" -newer "$GIT_DIR/index" 2>/dev/null || true)
+  else
+    RECENT_BRAIN=""
+  fi
+  if [ -n "$RECENT_BRAIN" ]; then
+    echo "$RECENT_BRAIN" | sed 's|brain/||;s|\.md$||'
+  else
+    # Fallback: show brain files modified in last 7 days
+    RECENT_BRAIN=$(find brain/ -name "*.md" -mtime -7 2>/dev/null || true)
+    if [ -n "$RECENT_BRAIN" ]; then
+      echo "(modified in last 7 days)"
+      echo "$RECENT_BRAIN" | sed 's|brain/||;s|\.md$||'
+    else
+      echo "(no recent changes)"
+    fi
+  fi
+fi
+echo ""
+
+# Vault file listing — tiered to avoid flooding context in large vaults
+echo "### Vault Files"
+ALL_FILES=$(find . -name "*.md" -not -path "./.git/*" -not -path "./.obsidian/*" -not -path "./thinking/*" -not -path "./.claude/*" -not -path "./.codex/*" -not -path "./.codex-vault/*" -not -path "./node_modules/*" 2>/dev/null | sort)
+FILE_COUNT=$(echo "$ALL_FILES" | grep -c . 2>/dev/null || echo "0")
+
+_folder_summary() {
+  echo "$ALL_FILES" | sed 's|^\./||' | cut -d/ -f1 | sort | uniq -c | sort -rn | while read count dir; do
+    echo "  $dir/ ($count files)"
+  done
+}
+
+_key_files() {
+  echo "$ALL_FILES" | grep -E "(Home|Index|North Star|Memories|Key Decisions|Patterns|log)\\.md$" || true
+}
+
+if [ "$FILE_COUNT" -le 20 ]; then
+  # Tier 1: small vault — list everything
+  echo "$ALL_FILES"
+
+elif [ "$FILE_COUNT" -le 50 ]; then
+  # Tier 2: medium vault — list hot folders, summarize cold storage
+  HOT_FILES=$(echo "$ALL_FILES" | grep -v -E "^\./sources/|^\./work/archive/" || true)
+  COLD_COUNT=$(echo "$ALL_FILES" | grep -E "^\./sources/|^\./work/archive/" | grep -c . 2>/dev/null || echo "0")
+
+  if [ -n "$HOT_FILES" ]; then
+    echo "$HOT_FILES"
+  fi
+  if [ "$COLD_COUNT" -gt 0 ]; then
+    echo ""
+    echo "(+ $COLD_COUNT files in sources/ and work/archive/ — use /recall to search)"
+  fi
+
+elif [ "$FILE_COUNT" -le 150 ]; then
+  # Tier 3: large vault — folder summary + recent + key files
+  echo "($FILE_COUNT files — showing summary)"
+  echo ""
+  _folder_summary
+  echo ""
+  echo "Recently modified (7 days):"
+  find . -name "*.md" -mtime -7 -not -path "./.git/*" -not -path "./.obsidian/*" -not -path "./thinking/*" -not -path "./.claude/*" -not -path "./.codex/*" -not -path "./.codex-vault/*" -not -path "./node_modules/*" 2>/dev/null | sort || echo "  (none)"
+  echo ""
+  echo "Key files:"
+  _key_files
+
+else
+  # Tier 4: very large vault — minimal footprint
+  echo "($FILE_COUNT files — showing summary)"
+  echo ""
+  _folder_summary
+  echo ""
+  echo "Recently modified (3 days):"
+  find . -name "*.md" -mtime -3 -not -path "./.git/*" -not -path "./.obsidian/*" -not -path "./thinking/*" -not -path "./.claude/*" -not -path "./.codex/*" -not -path "./.codex-vault/*" -not -path "./node_modules/*" 2>/dev/null | sort || echo "  (none)"
+  echo ""
+  echo "Key files:"
+  _key_files
+  echo ""
+  echo "Use /recall <topic> to search the vault."
+fi

package/vault/.codex-vault/hooks/validate-write.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Post-write validation for vault notes.
+
+Checks frontmatter and wikilinks on any .md file written to the vault.
+Agent-agnostic — outputs hookSpecificOutput compatible with both
+Claude Code and Codex CLI.
+"""
+import json
+import re
+import sys
+import os
+from pathlib import Path
+
+
+def _check_log_format(content):
+    """Validate log.md entry format: ## [YYYY-MM-DD] <type> | <title>"""
+    warnings = []
+    for i, line in enumerate(content.splitlines(), 1):
+        if line.startswith("## ") and not line.startswith("## ["):
+            # Heading that looks like a log entry but missing date brackets
+            if any(t in line.lower() for t in ["ingest", "session", "query", "maintenance", "decision", "archive"]):
+                warnings.append(f"Line {i}: log entry missing date format — expected `## [YYYY-MM-DD] <type> | <title>`")
+        elif line.startswith("## ["):
+            if not re.match(r"^## \[\d{4}-\d{2}-\d{2}\] \w+", line):
+                warnings.append(f"Line {i}: malformed log entry — expected `## [YYYY-MM-DD] <type> | <title>`")
+    return warnings
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (ValueError, EOFError, OSError):
+        sys.exit(0)
+
+    tool_input = input_data.get("tool_input")
+    if not isinstance(tool_input, dict):
+        sys.exit(0)
+
+    file_path = tool_input.get("file_path", "")
+    if not isinstance(file_path, str) or not file_path:
+        sys.exit(0)
+
+    if not file_path.endswith(".md"):
+        sys.exit(0)
+
+    normalized = file_path.replace("\\", "/")
+    basename = os.path.basename(normalized)
+
+    # Skip non-vault files
+    skip_names = {"README.md", "CHANGELOG.md", "CONTRIBUTING.md", "CLAUDE.md", "AGENTS.md", "LICENSE"}
+    if basename in skip_names:
+        sys.exit(0)
+    if basename.startswith("README.") and basename.endswith(".md"):
+        sys.exit(0)
+
+    skip_paths = [".claude/", ".codex/", ".codex-vault/", ".mind/", "templates/", "thinking/", "node_modules/", "plugin/", "docs/"]
+    if any(skip in normalized for skip in skip_paths):
+        sys.exit(0)
+
+    warnings = []
+
+    try:
+        content = Path(file_path).read_text(encoding="utf-8")
+
+        if not content.startswith("---"):
+            warnings.append("Missing YAML frontmatter")
+        else:
+            parts = content.split("---", 2)
+            if len(parts) >= 3:
+                fm = parts[1]
+                if "date:" not in fm and basename != "log.md":
+                    warnings.append("Missing `date` in frontmatter")
+                if "tags:" not in fm:
+                    warnings.append("Missing `tags` in frontmatter")
+                if "description:" not in fm:
+                    warnings.append("Missing `description` in frontmatter (~150 chars)")
+
+        if len(content) > 300 and "[[" not in content:
+            warnings.append("No [[wikilinks]] found — every note should link to at least one other note")
+
+        # Check for unfilled template placeholders
+        placeholders = re.findall(r"\{\{[^}]+\}\}", content)
+        if placeholders:
+            examples = ", ".join(placeholders[:3])
+            warnings.append(f"Unfilled template placeholders found: {examples}")
+
+        # Validate log.md format
+        if basename == "log.md":
+            log_warnings = _check_log_format(content)
+            warnings.extend(log_warnings)
+
+    except Exception:
+        sys.exit(0)
+
+    if warnings:
+        hint_list = "\n".join(f"  - {w}" for w in warnings)
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": f"Vault warnings for `{basename}`:\n{hint_list}\nFix these before moving on."
+            }
+        }
+        json.dump(output, sys.stdout)
+        sys.stdout.flush()
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        sys.exit(0)

package/vault/AGENTS.md

@@ -0,0 +1,118 @@
+# Codex-Vault — Core Instructions
+
+A structured knowledge vault maintained by an LLM agent. You write notes, maintain links, and keep indexes current. The human curates sources, directs analysis, and asks questions.
+
+## Vault Structure
+
+| Folder | Purpose |
+|--------|---------|
+| `Home.md` | Vault entry point — quick links, current focus |
+| `brain/` | Persistent memory — goals, decisions, patterns |
+| `work/` | Work notes index (`Index.md`) |
+| `work/active/` | Current projects (move to archive when done) |
+| `work/archive/` | Completed work |
+| `templates/` | Note templates with YAML frontmatter |
+| `sources/` | Raw source documents — immutable, LLM reads only |
+| `thinking/` | Scratchpad — promote findings, then delete |
+| `reference/` | Saved answers and analyses from query writeback |
+
+## Session Lifecycle
+
+### Start
+
+The SessionStart hook injects: North Star goals, recent git changes, active work, vault file listing. You start with context, not a blank slate.
+
+### Work
+
+1. The classify hook detects intent and suggests skills — **do not auto-execute**. Suggest the skill to the user and let them decide.
+2. Available skills: `/dump`, `/recall`, `/ingest`, `/wrap-up`
+3. Search before creating — check if a related note exists (use `/recall <topic>` for targeted vault search)
+4. Update `work/Index.md` if a new note was created
+
+### End
+
+When the user says "wrap up" or similar:
+1. Verify new notes have frontmatter and wikilinks
+2. Update `work/Index.md` with any new or completed notes
+3. Archive completed projects: move from `work/active/` to `work/archive/`
+4. Check if `brain/` notes need updating with new decisions or patterns
+
+## Creating Notes
+
+1. **Always use YAML frontmatter**: `date`, `description` (~150 chars), `tags`
+2. **Use templates** from `templates/`
+3. **Place files correctly**: active work in `work/active/`, completed in `work/archive/`, source summaries in `work/active/` (tag: `source-summary`), drafts in `thinking/`
+4. **Name files descriptively** — use the note title as filename
+
+## Linking — Critical
+
+**Graph-first.** Folders group by purpose, links group by meaning. A note lives in one folder but links to many notes.
+
+**A note without links is a bug.** Every new note must link to at least one existing note via `[[wikilinks]]`.
+
+Link syntax:
+- `[[Note Title]]` — standard wikilink
+- `[[Note Title|display text]]` — aliased
+- `[[Note Title#Heading]]` — deep link
+
+### When to Link
+
+- Work note ↔ Decision Record (bidirectional)
+- Index → all work notes
+- North Star → active projects
+- Memories → source notes
+
+## Memory System
+
+All persistent memory lives in `brain/`:
+
+| File | Stores |
+|------|--------|
+| `North Star.md` | Goals and focus areas — read every session |
+| `Memories.md` | Index of memory topics |
+| `Key Decisions.md` | Decisions worth recalling across sessions |
+| `Patterns.md` | Recurring patterns discovered across work |
+
+When asked to "remember" something: write to the appropriate `brain/` file with a wikilink to context.
+
+## Sources & Ingest
+
+`sources/` holds raw source documents (articles, papers, web clips). This is the immutable layer — the agent reads from it but never modifies source files.
+
+- Drop raw files into `sources/` (markdown preferred) or use `/ingest` with a URL
+- `/ingest` reads the source, discusses key takeaways, then creates a **Source Summary** in `work/active/` with tag `source-summary`
+- The summary uses the Source Summary template: Key Takeaways, Summary, Connections, Quotes/Data Points
+- Every ingest updates `work/Index.md` (Sources section) and checks for cross-links to existing notes
+- If the source contains decisions or patterns, update the relevant `brain/` notes too
+- Source summaries link back to the raw source via the `source` frontmatter field
+
+## Operation Log
+
+Append to `log.md` after significant operations: ingests, decisions, project archives, maintenance passes.
+
+- Format: `## [YYYY-MM-DD] <type> | <title>` followed by bullet points
+- Types: `ingest`, `session`, `query`, `maintenance`, `decision`, `archive`
+- Don't log every small edit — only operations that change the vault's knowledge state
+- Entries are append-only; never edit or delete previous entries
+
+## Query Writeback
+
+When answering a substantial question that synthesizes multiple vault notes:
+
+1. Offer: "This answer could be useful later — want me to save it as a reference note?"
+2. If yes, create a Reference Note in `reference/` using the template
+3. Link the reference note from related work notes in `## Related`
+4. Add the reference note to `work/Index.md` under `## Reference`
+5. Don't prompt for trivial questions — only for answers that synthesize, compare, or analyze
+
+## Vault Location
+
+The vault may live at the project root or in a `vault/` subdirectory. Use the SessionStart context to determine the actual path. All folder references above (e.g. `brain/`, `work/active/`) are relative to the vault root.
+
+## Rules
+
+- Preserve existing frontmatter when editing notes
+- Always check for and suggest connections between notes
+- Every note must have a `description` field (~150 chars)
+- When reorganizing, never delete without user confirmation
+- Use `[[wikilinks]]` not markdown links

package/vault/CLAUDE.md

@@ -0,0 +1,118 @@
+# Codex-Vault — Core Instructions
+
+A structured knowledge vault maintained by an LLM agent. You write notes, maintain links, and keep indexes current. The human curates sources, directs analysis, and asks questions.
+
+## Vault Structure
+
+| Folder | Purpose |
+|--------|---------|
+| `Home.md` | Vault entry point — quick links, current focus |
+| `brain/` | Persistent memory — goals, decisions, patterns |
+| `work/` | Work notes index (`Index.md`) |
+| `work/active/` | Current projects (move to archive when done) |
+| `work/archive/` | Completed work |
+| `templates/` | Note templates with YAML frontmatter |
+| `sources/` | Raw source documents — immutable, LLM reads only |
+| `thinking/` | Scratchpad — promote findings, then delete |
+| `reference/` | Saved answers and analyses from query writeback |
+
+## Session Lifecycle
+
+### Start
+
+The SessionStart hook injects: North Star goals, recent git changes, active work, vault file listing. You start with context, not a blank slate.
+
+### Work
+
+1. The classify hook detects intent and suggests skills — **do not auto-execute**. Suggest the skill to the user and let them decide.
+2. Available skills: `/dump`, `/recall`, `/ingest`, `/wrap-up`
+3. Search before creating — check if a related note exists (use `/recall <topic>` for targeted vault search)
+4. Update `work/Index.md` if a new note was created
+
+### End
+
+When the user says "wrap up" or similar:
+1. Verify new notes have frontmatter and wikilinks
+2. Update `work/Index.md` with any new or completed notes
+3. Archive completed projects: move from `work/active/` to `work/archive/`
+4. Check if `brain/` notes need updating with new decisions or patterns
+
+## Creating Notes
+
+1. **Always use YAML frontmatter**: `date`, `description` (~150 chars), `tags`
+2. **Use templates** from `templates/`
+3. **Place files correctly**: active work in `work/active/`, completed in `work/archive/`, source summaries in `work/active/` (tag: `source-summary`), drafts in `thinking/`
+4. **Name files descriptively** — use the note title as filename
+
+## Linking — Critical
+
+**Graph-first.** Folders group by purpose, links group by meaning. A note lives in one folder but links to many notes.
+
+**A note without links is a bug.** Every new note must link to at least one existing note via `[[wikilinks]]`.
+
+Link syntax:
+- `[[Note Title]]` — standard wikilink
+- `[[Note Title|display text]]` — aliased
+- `[[Note Title#Heading]]` — deep link
+
+### When to Link
+
+- Work note ↔ Decision Record (bidirectional)
+- Index → all work notes
+- North Star → active projects
+- Memories → source notes
+
+## Memory System
+
+All persistent memory lives in `brain/`:
+
+| File | Stores |
+|------|--------|
+| `North Star.md` | Goals and focus areas — read every session |
+| `Memories.md` | Index of memory topics |
+| `Key Decisions.md` | Decisions worth recalling across sessions |
+| `Patterns.md` | Recurring patterns discovered across work |
+
+When asked to "remember" something: write to the appropriate `brain/` file with a wikilink to context.
+
+## Sources & Ingest
+
+`sources/` holds raw source documents (articles, papers, web clips). This is the immutable layer — the agent reads from it but never modifies source files.
+
+- Drop raw files into `sources/` (markdown preferred) or use `/ingest` with a URL
+- `/ingest` reads the source, discusses key takeaways, then creates a **Source Summary** in `work/active/` with tag `source-summary`
+- The summary uses the Source Summary template: Key Takeaways, Summary, Connections, Quotes/Data Points
+- Every ingest updates `work/Index.md` (Sources section) and checks for cross-links to existing notes
+- If the source contains decisions or patterns, update the relevant `brain/` notes too
+- Source summaries link back to the raw source via the `source` frontmatter field
+
+## Operation Log
+
+Append to `log.md` after significant operations: ingests, decisions, project archives, maintenance passes.
+
+- Format: `## [YYYY-MM-DD] <type> | <title>` followed by bullet points
+- Types: `ingest`, `session`, `query`, `maintenance`, `decision`, `archive`
+- Don't log every small edit — only operations that change the vault's knowledge state
+- Entries are append-only; never edit or delete previous entries
+
+## Query Writeback
+
+When answering a substantial question that synthesizes multiple vault notes:
+
+1. Offer: "This answer could be useful later — want me to save it as a reference note?"
+2. If yes, create a Reference Note in `reference/` using the template
+3. Link the reference note from related work notes in `## Related`
+4. Add the reference note to `work/Index.md` under `## Reference`
+5. Don't prompt for trivial questions — only for answers that synthesize, compare, or analyze
+
+## Vault Location
+
+The vault may live at the project root or in a `vault/` subdirectory. Use the SessionStart context to determine the actual path. All folder references above (e.g. `brain/`, `work/active/`) are relative to the vault root.
+
+## Rules
+
+- Preserve existing frontmatter when editing notes
+- Always check for and suggest connections between notes
+- Every note must have a `description` field (~150 chars)
+- When reorganizing, never delete without user confirmation
+- Use `[[wikilinks]]` not markdown links

package/vault/Home.md

@@ -0,0 +1,21 @@
+---
+description: "Vault entry point — current focus and quick navigation"
+tags:
+  - index
+---
+
+# Home
+
+## Current Focus
+
+![[North Star#Current Focus]]
+
+## Quick Links
+
+- [[Index|Work Notes]] — all projects and decisions
+- [[North Star]] — goals and direction
+- [[Memories]] — persistent context
+- [[Key Decisions]] — architectural and workflow decisions
+- [[Patterns]] — recurring patterns
+- [[Index#Reference|Reference Notes]] — saved answers and analyses
+- [[Log]] — operation history

package/vault/brain/Key Decisions.md

@@ -0,0 +1,11 @@
+---
+description: "Decisions worth recalling across sessions — each links to its source work note"
+tags:
+  - brain
+---
+
+# Key Decisions
+
+Decisions worth recalling. Link to the full work note or Decision Record when one exists.
+
+-

package/vault/brain/Memories.md

@@ -0,0 +1,19 @@
+---
+description: "Index of memory topics — decisions, patterns, context retained across sessions"
+tags:
+  - brain
+  - index
+---
+
+# Memories
+
+Persistent context retained across sessions. Each topic lives in its own note — follow the links.
+
+- [[Key Decisions]] — decisions worth recalling
+- [[Patterns]] — recurring patterns discovered across work
+- [[North Star]] — living goals document
+- [[Log]] — chronological record of vault operations
+
+## Recent Context
+
+-

package/vault/brain/North Star.md

@@ -0,0 +1,29 @@
+---
+description: "Living document of goals, focus areas, and aspirations — read at session start"
+tags:
+  - brain
+---
+
+# North Star
+
+A living document of goals and focus areas. Both you and your LLM agent write to this. The agent reads it at the start of every session and references it when making suggestions.
+
+## Current Focus
+
+_What am I working toward right now?_
+
+-
+
+## Goals
+
+### Short-term (This Quarter)
+
+-
+
+### Medium-term (This Half)
+
+-
+
+### Long-term
+
+-

package/vault/brain/Patterns.md

@@ -0,0 +1,11 @@
+---
+description: "Recurring patterns discovered across work — conventions, architecture, tooling"
+tags:
+  - brain
+---
+
+# Patterns
+
+Recurring patterns discovered across work.
+
+-

package/vault/log.md

@@ -0,0 +1,15 @@
+---
+description: "Chronological log of vault operations — ingests, queries, session starts, maintenance"
+tags:
+  - index
+---
+
+# Log
+
+Append-only record of vault operations. Each entry starts with `## [YYYY-MM-DD] <type> | <title>` for easy parsing with grep.
+
+Entry types: `ingest`, `session`, `query`, `maintenance`, `decision`, `archive`.
+
+## [2026-04-06] session | Initial vault setup
+- Created vault structure
+- Configured hooks for Claude Code and Codex CLI

package/vault/sources/README.md

@@ -0,0 +1,19 @@
+# Sources
+
+Drop raw source files here — articles, papers, web clips saved as markdown.
+
+## How It Works
+
+- The LLM agent **reads** from this directory but **never modifies** source files.
+- Sources are immutable reference material. The agent creates summaries in `work/active/` instead.
+- Use `/ingest` (Claude Code) or say "ingest this source" (Codex CLI) to process a new source into a wiki page with cross-links.
+
+## Supported Formats
+
+- Markdown files (`.md`) — preferred
+- Plain text (`.txt`)
+- Web clips saved via `defuddle parse <url> --md > sources/filename.md`
+
+## Naming
+
+Use descriptive filenames: `karpathy-llm-wiki.md`, `react-server-components-rfc.md`, etc.