From f8841fe01571c8e6b382b5c0c556cdc6bb1178db Mon Sep 17 00:00:00 2001
From: "jiashuai.shi@qq.com" <shijiashuai@bgi.com>
Date: Tue, 26 May 2026 02:52:30 +0800
Subject: [PATCH] refactor: remove AI governance scaffolding

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .claude/commands/opsx/apply.md                | 152 ----
 .claude/commands/opsx/archive.md              | 157 ----
 .claude/commands/opsx/explore.md              | 173 -----
 .claude/commands/opsx/propose.md              | 106 ---
 .claude/skills/openspec-apply-change/SKILL.md | 156 ----
 .../skills/openspec-archive-change/SKILL.md   | 114 ---
 .claude/skills/openspec-explore/SKILL.md      | 288 --------
 .claude/skills/openspec-propose/SKILL.md      | 110 ---
 .claude/skills/verify/SKILL.md                |  32 -
 .github/copilot-instructions.md               |  18 +-
 .omc/project-memory.json                      | 487 -------------
 AGENTS.md                                     | 139 ----
 CHANGELOG.md                                  |  23 +-
 CLAUDE.md                                     |  67 --
 CONTRIBUTING.md                               |  70 +-
 README.md                                     |  79 +-
 README.zh-CN.md                               |  77 +-
 docs/.vitepress/config.mts                    |  26 +-
 docs/.vitepress/theme/custom.css              |   8 +-
 docs/en/api/index.md                          |  91 +--
 docs/en/api/inference-engine.md               | 660 ++---------------
 docs/en/api/result.md                         | 197 +----
 docs/en/architecture/index.md                 | 332 +--------
 docs/en/architecture/inference-engine.md      | 182 +----
 docs/en/changelog/index.md                    |  27 -
 docs/en/changelog/v2.0.0.md                   | 148 ----
 docs/en/changelog/v2.0.1.md                   |  47 --
 docs/en/changelog/v2.0.2.md                   |  49 --
 docs/en/guide/quickstart.md                   |  82 +--
 docs/en/guide/troubleshooting.md              |   4 +-
 docs/en/index.md                              | 120 ++--
 docs/index.md                                 |  55 +-
 docs/zh/api/index.md                          |  91 +--
 docs/zh/api/inference-engine.md               | 680 ++----------------
 docs/zh/api/result.md                         | 197 +----
 docs/zh/architecture/index.md                 | 334 +--------
 docs/zh/architecture/inference-engine.md      | 182 +----
 docs/zh/changelog/index.md                    |  27 -
 docs/zh/changelog/v2.0.0.md                   | 148 ----
 docs/zh/changelog/v2.0.1.md                   |  47 --
 docs/zh/changelog/v2.0.2.md                   |  49 --
 docs/zh/guide/quickstart.md                   |  82 +--
 docs/zh/guide/troubleshooting.md              |   2 +-
 docs/zh/index.md                              | 118 ++-
 openspec/MIGRATION.md                         | 113 ---
 .../archive/core-architecture/design.md       | 148 ----
 .../archive/core-architecture/proposal.md     |  22 -
 .../initial-implementation/proposal.md        |  22 -
 .../archive/initial-implementation/tasks.md   | 106 ---
 .../.openspec.yaml                            |   2 -
 .../normalize-archive-readiness/design.md     | 127 ----
 .../normalize-archive-readiness/proposal.md   |  30 -
 .../specs/ai-assisted-development/spec.md     |  34 -
 .../specs/project-presentation/spec.md        |  34 -
 .../specs/repository-governance/spec.md       |  45 --
 .../normalize-archive-readiness/tasks.md      |  36 -
 .../changes/harden-gguf-contracts/design.md   |  63 --
 .../changes/harden-gguf-contracts/proposal.md |  22 -
 .../specs/inference-engine/spec.md            |  28 -
 .../changes/harden-gguf-contracts/tasks.md    |  17 -
 openspec/config.yaml                          |  25 -
 openspec/schemas/api/inference-engine.yaml    |  77 --
 openspec/schemas/db/schema-v1.dbml            | 178 -----
 openspec/specs/inference-engine/spec.md       | 245 -------
 tests/test_model_loader.cpp                   |   2 +-
 65 files changed, 642 insertions(+), 6967 deletions(-)
 delete mode 100644 .claude/commands/opsx/apply.md
 delete mode 100644 .claude/commands/opsx/archive.md
 delete mode 100644 .claude/commands/opsx/explore.md
 delete mode 100644 .claude/commands/opsx/propose.md
 delete mode 100644 .claude/skills/openspec-apply-change/SKILL.md
 delete mode 100644 .claude/skills/openspec-archive-change/SKILL.md
 delete mode 100644 .claude/skills/openspec-explore/SKILL.md
 delete mode 100644 .claude/skills/openspec-propose/SKILL.md
 delete mode 100644 .claude/skills/verify/SKILL.md
 delete mode 100644 .omc/project-memory.json
 delete mode 100644 AGENTS.md
 delete mode 100644 CLAUDE.md
 delete mode 100644 docs/en/changelog/index.md
 delete mode 100644 docs/en/changelog/v2.0.0.md
 delete mode 100644 docs/en/changelog/v2.0.1.md
 delete mode 100644 docs/en/changelog/v2.0.2.md
 delete mode 100644 docs/zh/changelog/index.md
 delete mode 100644 docs/zh/changelog/v2.0.0.md
 delete mode 100644 docs/zh/changelog/v2.0.1.md
 delete mode 100644 docs/zh/changelog/v2.0.2.md
 delete mode 100644 openspec/MIGRATION.md
 delete mode 100644 openspec/changes/archive/core-architecture/design.md
 delete mode 100644 openspec/changes/archive/core-architecture/proposal.md
 delete mode 100644 openspec/changes/archive/initial-implementation/proposal.md
 delete mode 100644 openspec/changes/archive/initial-implementation/tasks.md
 delete mode 100644 openspec/changes/archive/normalize-archive-readiness/.openspec.yaml
 delete mode 100644 openspec/changes/archive/normalize-archive-readiness/design.md
 delete mode 100644 openspec/changes/archive/normalize-archive-readiness/proposal.md
 delete mode 100644 openspec/changes/archive/normalize-archive-readiness/specs/ai-assisted-development/spec.md
 delete mode 100644 openspec/changes/archive/normalize-archive-readiness/specs/project-presentation/spec.md
 delete mode 100644 openspec/changes/archive/normalize-archive-readiness/specs/repository-governance/spec.md
 delete mode 100644 openspec/changes/archive/normalize-archive-readiness/tasks.md
 delete mode 100644 openspec/changes/harden-gguf-contracts/design.md
 delete mode 100644 openspec/changes/harden-gguf-contracts/proposal.md
 delete mode 100644 openspec/changes/harden-gguf-contracts/specs/inference-engine/spec.md
 delete mode 100644 openspec/changes/harden-gguf-contracts/tasks.md
 delete mode 100644 openspec/config.yaml
 delete mode 100644 openspec/schemas/api/inference-engine.yaml
 delete mode 100644 openspec/schemas/db/schema-v1.dbml
 delete mode 100644 openspec/specs/inference-engine/spec.md

diff --git a/.claude/commands/opsx/apply.md b/.claude/commands/opsx/apply.md
deleted file mode 100644
index ae14f0f..0000000
--- a/.claude/commands/opsx/apply.md
+++ /dev/null
@@ -1,152 +0,0 @@
----
-name: "OPSX: Apply"
-description: Implement tasks from an OpenSpec change (Experimental)
-category: Workflow
-tags: [workflow, artifacts, experimental]
----
-
-Implement tasks from an OpenSpec change.
-
-**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **Select the change**
-
-   If a name is provided, use it. Otherwise:
-   - Infer from conversation context if the user mentioned a change
-   - Auto-select if only one active change exists
-   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
-
-   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
-
-2. **Check status to understand the schema**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used (e.g., "spec-driven")
-   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
-
-3. **Get apply instructions**
-
-   ```bash
-   openspec instructions apply --change "<name>" --json
-   ```
-
-   This returns:
-   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema)
-   - Progress (total, complete, remaining)
-   - Task list with status
-   - Dynamic instruction based on current state
-
-   **Handle states:**
-   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
-   - If `state: "all_done"`: congratulate, suggest archive
-   - Otherwise: proceed to implementation
-
-4. **Read context files**
-
-   Read every file path listed under `contextFiles` from the apply instructions output.
-   The files depend on the schema being used:
-   - **spec-driven**: proposal, specs, design, tasks
-   - Other schemas: follow the contextFiles from CLI output
-
-5. **Show current progress**
-
-   Display:
-   - Schema being used
-   - Progress: "N/M tasks complete"
-   - Remaining tasks overview
-   - Dynamic instruction from CLI
-
-6. **Implement tasks (loop until done or blocked)**
-
-   For each pending task:
-   - Show which task is being worked on
-   - Make the code changes required
-   - Keep changes minimal and focused
-   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
-   - Continue to next task
-
-   **Pause if:**
-   - Task is unclear → ask for clarification
-   - Implementation reveals a design issue → suggest updating artifacts
-   - Error or blocker encountered → report and wait for guidance
-   - User interrupts
-
-7. **On completion or pause, show status**
-
-   Display:
-   - Tasks completed this session
-   - Overall progress: "N/M tasks complete"
-   - If all done: suggest archive
-   - If paused: explain why and wait for guidance
-
-**Output During Implementation**
-
-```
-## Implementing: <change-name> (schema: <schema-name>)
-
-Working on task 3/7: <task description>
-[...implementation happening...]
-✓ Task complete
-
-Working on task 4/7: <task description>
-[...implementation happening...]
-✓ Task complete
-```
-
-**Output On Completion**
-
-```
-## Implementation Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Progress:** 7/7 tasks complete ✓
-
-### Completed This Session
-- [x] Task 1
-- [x] Task 2
-...
-
-All tasks complete! You can archive this change with `/opsx:archive`.
-```
-
-**Output On Pause (Issue Encountered)**
-
-```
-## Implementation Paused
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Progress:** 4/7 tasks complete
-
-### Issue Encountered
-<description of the issue>
-
-**Options:**
-1. <option 1>
-2. <option 2>
-3. Other approach
-
-What would you like to do?
-```
-
-**Guardrails**
-- Keep going through tasks until done or blocked
-- Always read context files before starting (from the apply instructions output)
-- If task is ambiguous, pause and ask before implementing
-- If implementation reveals issues, pause and suggest artifact updates
-- Keep code changes minimal and scoped to each task
-- Update task checkbox immediately after completing each task
-- Pause on errors, blockers, or unclear requirements - don't guess
-- Use contextFiles from CLI output, don't assume specific file names
-
-**Fluid Workflow Integration**
-
-This skill supports the "actions on a change" model:
-
-- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
-- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.claude/commands/opsx/archive.md b/.claude/commands/opsx/archive.md
deleted file mode 100644
index 5e91608..0000000
--- a/.claude/commands/opsx/archive.md
+++ /dev/null
@@ -1,157 +0,0 @@
----
-name: "OPSX: Archive"
-description: Archive a completed change in the experimental workflow
-category: Workflow
-tags: [workflow, archive, experimental]
----
-
-Archive a completed change in the experimental workflow.
-
-**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **If no change name provided, prompt for selection**
-
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show only active changes (not already archived).
-   Include the schema used for each change if available.
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Check artifact completion status**
-
-   Run `openspec status --change "<name>" --json` to check artifact completion.
-
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used
-   - `artifacts`: List of artifacts with their status (`done` or other)
-
-   **If any artifacts are not `done`:**
-   - Display warning listing incomplete artifacts
-   - Prompt user for confirmation to continue
-   - Proceed if user confirms
-
-3. **Check task completion status**
-
-   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
-
-   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
-
-   **If incomplete tasks found:**
-   - Display warning showing count of incomplete tasks
-   - Prompt user for confirmation to continue
-   - Proceed if user confirms
-
-   **If no tasks file exists:** Proceed without task-related warning.
-
-4. **Assess delta spec sync state**
-
-   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
-
-   **If delta specs exist:**
-   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
-   - Determine what changes would be applied (adds, modifications, removals, renames)
-   - Show a combined summary before prompting
-
-   **Prompt options:**
-   - If changes needed: "Sync now (recommended)", "Archive without syncing"
-   - If already synced: "Archive now", "Sync anyway", "Cancel"
-
-   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
-
-5. **Perform the archive**
-
-   Create the archive directory if it doesn't exist:
-   ```bash
-   mkdir -p openspec/changes/archive
-   ```
-
-   Generate target name using current date: `YYYY-MM-DD-<change-name>`
-
-   **Check if target already exists:**
-   - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move the change directory to archive
-
-   ```bash
-   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
-   ```
-
-6. **Display summary**
-
-   Show archive completion summary including:
-   - Change name
-   - Schema that was used
-   - Archive location
-   - Spec sync status (synced / sync skipped / no delta specs)
-   - Note about any warnings (incomplete artifacts/tasks)
-
-**Output On Success**
-
-```
-## Archive Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
-**Specs:** ✓ Synced to main specs
-
-All artifacts complete. All tasks complete.
-```
-
-**Output On Success (No Delta Specs)**
-
-```
-## Archive Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
-**Specs:** No delta specs
-
-All artifacts complete. All tasks complete.
-```
-
-**Output On Success With Warnings**
-
-```
-## Archive Complete (with warnings)
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
-**Specs:** Sync skipped (user chose to skip)
-
-**Warnings:**
-- Archived with 2 incomplete artifacts
-- Archived with 3 incomplete tasks
-- Delta spec sync was skipped (user chose to skip)
-
-Review the archive if this was not intentional.
-```
-
-**Output On Error (Archive Exists)**
-
-```
-## Archive Failed
-
-**Change:** <change-name>
-**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
-
-Target archive directory already exists.
-
-**Options:**
-1. Rename the existing archive
-2. Delete the existing archive if it's a duplicate
-3. Wait until a different date to archive
-```
-
-**Guardrails**
-- Always prompt for change selection if not provided
-- Use artifact graph (openspec status --json) for completion checking
-- Don't block archive on warnings - just inform and confirm
-- Preserve .openspec.yaml when moving to archive (it moves with the directory)
-- Show clear summary of what happened
-- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
-- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.claude/commands/opsx/explore.md b/.claude/commands/opsx/explore.md
deleted file mode 100644
index 4561073..0000000
--- a/.claude/commands/opsx/explore.md
+++ /dev/null
@@ -1,173 +0,0 @@
----
-name: "OPSX: Explore"
-description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
-category: Workflow
-tags: [workflow, explore, experimental, thinking]
----
-
-Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
-
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
-
-**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
-
-**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
-- A vague idea: "real-time collaboration"
-- A specific problem: "the auth system is getting unwieldy"
-- A change name: "add-dark-mode" (to explore in context of that change)
-- A comparison: "postgres vs sqlite for this"
-- Nothing (just enter explore mode)
-
----
-
-## The Stance
-
-- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
-- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
-- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
-- **Adaptive** - Follow interesting threads, pivot when new information emerges
-- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
-- **Grounded** - Explore the actual codebase when relevant, don't just theorize
-
----
-
-## What You Might Do
-
-Depending on what the user brings, you might:
-
-**Explore the problem space**
-- Ask clarifying questions that emerge from what they said
-- Challenge assumptions
-- Reframe the problem
-- Find analogies
-
-**Investigate the codebase**
-- Map existing architecture relevant to the discussion
-- Find integration points
-- Identify patterns already in use
-- Surface hidden complexity
-
-**Compare options**
-- Brainstorm multiple approaches
-- Build comparison tables
-- Sketch tradeoffs
-- Recommend a path (if asked)
-
-**Visualize**
-```
-┌─────────────────────────────────────────┐
-│     Use ASCII diagrams liberally        │
-├─────────────────────────────────────────┤
-│                                         │
-│      ┌────────┐         ┌────────┐      │
-│      │ State  │────────▶│ State  │      │
-│      │   A    │         │   B    │      │
-│      └────────┘         └────────┘      │
-│                                         │
-│   System diagrams, state machines,      │
-│   data flows, architecture sketches,    │
-│   dependency graphs, comparison tables  │
-│                                         │
-└─────────────────────────────────────────┘
-```
-
-**Surface risks and unknowns**
-- Identify what could go wrong
-- Find gaps in understanding
-- Suggest spikes or investigations
-
----
-
-## OpenSpec Awareness
-
-You have full context of the OpenSpec system. Use it naturally, don't force it.
-
-### Check for context
-
-At the start, quickly check what exists:
-```bash
-openspec list --json
-```
-
-This tells you:
-- If there are active changes
-- Their names, schemas, and status
-- What the user might be working on
-
-If the user mentioned a specific change name, read its artifacts for context.
-
-### When no change exists
-
-Think freely. When insights crystallize, you might offer:
-
-- "This feels solid enough to start a change. Want me to create a proposal?"
-- Or keep exploring - no pressure to formalize
-
-### When a change exists
-
-If the user mentions a change or you detect one is relevant:
-
-1. **Read existing artifacts for context**
-   - `openspec/changes/<name>/proposal.md`
-   - `openspec/changes/<name>/design.md`
-   - `openspec/changes/<name>/tasks.md`
-   - etc.
-
-2. **Reference them naturally in conversation**
-   - "Your design mentions using Redis, but we just realized SQLite fits better..."
-   - "The proposal scopes this to premium users, but we're now thinking everyone..."
-
-3. **Offer to capture when decisions are made**
-
-    | Insight Type               | Where to Capture               |
-    |----------------------------|--------------------------------|
-    | New requirement discovered | `openspec/specs/<capability>/spec.md` |
-    | Requirement changed        | `openspec/specs/<capability>/spec.md` |
-    | Design decision made       | `design.md`                  |
-    | Scope changed              | `proposal.md`                |
-    | New work identified        | `tasks.md`                   |
-    | Assumption invalidated     | Relevant artifact              |
-
-   Example offers:
-   - "That's a design decision. Capture it in design.md?"
-   - "This is a new requirement. Add it to specs?"
-   - "This changes scope. Update the proposal?"
-
-4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
-
----
-
-## What You Don't Have To Do
-
-- Follow a script
-- Ask the same questions every time
-- Produce a specific artifact
-- Reach a conclusion
-- Stay on topic if a tangent is valuable
-- Be brief (this is thinking time)
-
----
-
-## Ending Discovery
-
-There's no required ending. Discovery might:
-
-- **Flow into a proposal**: "Ready to start? I can create a change proposal."
-- **Result in artifact updates**: "Updated design.md with these decisions"
-- **Just provide clarity**: User has what they need, moves on
-- **Continue later**: "We can pick this up anytime"
-
-When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
-
----
-
-## Guardrails
-
-- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
-- **Don't fake understanding** - If something is unclear, dig deeper
-- **Don't rush** - Discovery is thinking time, not task time
-- **Don't force structure** - Let patterns emerge naturally
-- **Don't auto-capture** - Offer to save insights, don't just do it
-- **Do visualize** - A good diagram is worth many paragraphs
-- **Do explore the codebase** - Ground discussions in reality
-- **Do question assumptions** - Including the user's and your own
diff --git a/.claude/commands/opsx/propose.md b/.claude/commands/opsx/propose.md
deleted file mode 100644
index 05276f4..0000000
--- a/.claude/commands/opsx/propose.md
+++ /dev/null
@@ -1,106 +0,0 @@
----
-name: "OPSX: Propose"
-description: Propose a new change - create it and generate all artifacts in one step
-category: Workflow
-tags: [workflow, artifacts, experimental]
----
-
-Propose a new change - create the change and generate all artifacts in one step.
-
-I'll create a change with artifacts:
-- proposal.md (what & why)
-- design.md (how)
-- tasks.md (implementation steps)
-
-When ready to implement, run /opsx:apply
-
----
-
-**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
-
-**Steps**
-
-1. **If no input provided, ask what they want to build**
-
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
-   > "What change do you want to work on? Describe what you want to build or fix."
-
-   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
-
-   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
-
-2. **Create the change directory**
-   ```bash
-   openspec new change "<name>"
-   ```
-   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
-
-3. **Get the artifact build order**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to get:
-   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
-   - `artifacts`: list of all artifacts with their status and dependencies
-
-4. **Create artifacts in sequence until apply-ready**
-
-   Use the **TodoWrite tool** to track progress through the artifacts.
-
-   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
-
-   a. **For each artifact that is `ready` (dependencies satisfied)**:
-      - Get instructions:
-        ```bash
-        openspec instructions <artifact-id> --change "<name>" --json
-        ```
-      - The instructions JSON includes:
-        - `context`: Project background (constraints for you - do NOT include in output)
-        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
-        - `template`: The structure to use for your output file
-        - `instruction`: Schema-specific guidance for this artifact type
-        - `outputPath`: Where to write the artifact
-        - `dependencies`: Completed artifacts to read for context
-      - Read any completed dependency files for context
-      - Create the artifact file using `template` as the structure
-      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
-      - Show brief progress: "Created <artifact-id>"
-
-   b. **Continue until all `applyRequires` artifacts are complete**
-      - After creating each artifact, re-run `openspec status --change "<name>" --json`
-      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
-      - Stop when all `applyRequires` artifacts are done
-
-   c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
-      - Then continue with creation
-
-5. **Show final status**
-   ```bash
-   openspec status --change "<name>"
-   ```
-
-**Output**
-
-After completing all artifacts, summarize:
-- Change name and location
-- List of artifacts created with brief descriptions
-- What's ready: "All artifacts created! Ready for implementation."
-- Prompt: "Run `/opsx:apply` to start implementing."
-
-**Artifact Creation Guidelines**
-
-- Follow the `instruction` field from `openspec instructions` for each artifact type
-- The schema defines what each artifact should contain - follow it
-- Read dependency artifacts for context before creating new ones
-- Use `template` as the structure for your output file - fill in its sections
-- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
-  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
-  - These guide what you write, but should never appear in the output
-
-**Guardrails**
-- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
-- Always read dependency artifacts before creating a new one
-- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
-- If a change with that name already exists, ask if user wants to continue it or create a new one
-- Verify each artifact file exists after writing before proceeding to next
diff --git a/.claude/skills/openspec-apply-change/SKILL.md b/.claude/skills/openspec-apply-change/SKILL.md
deleted file mode 100644
index 70fbdb8..0000000
--- a/.claude/skills/openspec-apply-change/SKILL.md
+++ /dev/null
@@ -1,156 +0,0 @@
----
-name: openspec-apply-change
-description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.3.1"
----
-
-Implement tasks from an OpenSpec change.
-
-**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **Select the change**
-
-   If a name is provided, use it. Otherwise:
-   - Infer from conversation context if the user mentioned a change
-   - Auto-select if only one active change exists
-   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
-
-   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
-
-2. **Check status to understand the schema**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used (e.g., "spec-driven")
-   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
-
-3. **Get apply instructions**
-
-   ```bash
-   openspec instructions apply --change "<name>" --json
-   ```
-
-   This returns:
-   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
-   - Progress (total, complete, remaining)
-   - Task list with status
-   - Dynamic instruction based on current state
-
-   **Handle states:**
-   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
-   - If `state: "all_done"`: congratulate, suggest archive
-   - Otherwise: proceed to implementation
-
-4. **Read context files**
-
-   Read every file path listed under `contextFiles` from the apply instructions output.
-   The files depend on the schema being used:
-   - **spec-driven**: proposal, specs, design, tasks
-   - Other schemas: follow the contextFiles from CLI output
-
-5. **Show current progress**
-
-   Display:
-   - Schema being used
-   - Progress: "N/M tasks complete"
-   - Remaining tasks overview
-   - Dynamic instruction from CLI
-
-6. **Implement tasks (loop until done or blocked)**
-
-   For each pending task:
-   - Show which task is being worked on
-   - Make the code changes required
-   - Keep changes minimal and focused
-   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
-   - Continue to next task
-
-   **Pause if:**
-   - Task is unclear → ask for clarification
-   - Implementation reveals a design issue → suggest updating artifacts
-   - Error or blocker encountered → report and wait for guidance
-   - User interrupts
-
-7. **On completion or pause, show status**
-
-   Display:
-   - Tasks completed this session
-   - Overall progress: "N/M tasks complete"
-   - If all done: suggest archive
-   - If paused: explain why and wait for guidance
-
-**Output During Implementation**
-
-```
-## Implementing: <change-name> (schema: <schema-name>)
-
-Working on task 3/7: <task description>
-[...implementation happening...]
-✓ Task complete
-
-Working on task 4/7: <task description>
-[...implementation happening...]
-✓ Task complete
-```
-
-**Output On Completion**
-
-```
-## Implementation Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Progress:** 7/7 tasks complete ✓
-
-### Completed This Session
-- [x] Task 1
-- [x] Task 2
-...
-
-All tasks complete! Ready to archive this change.
-```
-
-**Output On Pause (Issue Encountered)**
-
-```
-## Implementation Paused
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Progress:** 4/7 tasks complete
-
-### Issue Encountered
-<description of the issue>
-
-**Options:**
-1. <option 1>
-2. <option 2>
-3. Other approach
-
-What would you like to do?
-```
-
-**Guardrails**
-- Keep going through tasks until done or blocked
-- Always read context files before starting (from the apply instructions output)
-- If task is ambiguous, pause and ask before implementing
-- If implementation reveals issues, pause and suggest artifact updates
-- Keep code changes minimal and scoped to each task
-- Update task checkbox immediately after completing each task
-- Pause on errors, blockers, or unclear requirements - don't guess
-- Use contextFiles from CLI output, don't assume specific file names
-
-**Fluid Workflow Integration**
-
-This skill supports the "actions on a change" model:
-
-- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
-- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.claude/skills/openspec-archive-change/SKILL.md b/.claude/skills/openspec-archive-change/SKILL.md
deleted file mode 100644
index 12e2f70..0000000
--- a/.claude/skills/openspec-archive-change/SKILL.md
+++ /dev/null
@@ -1,114 +0,0 @@
----
-name: openspec-archive-change
-description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.3.1"
----
-
-Archive a completed change in the experimental workflow.
-
-**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **If no change name provided, prompt for selection**
-
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show only active changes (not already archived).
-   Include the schema used for each change if available.
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Check artifact completion status**
-
-   Run `openspec status --change "<name>" --json` to check artifact completion.
-
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used
-   - `artifacts`: List of artifacts with their status (`done` or other)
-
-   **If any artifacts are not `done`:**
-   - Display warning listing incomplete artifacts
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
-   - Proceed if user confirms
-
-3. **Check task completion status**
-
-   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
-
-   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
-
-   **If incomplete tasks found:**
-   - Display warning showing count of incomplete tasks
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
-   - Proceed if user confirms
-
-   **If no tasks file exists:** Proceed without task-related warning.
-
-4. **Assess delta spec sync state**
-
-   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
-
-   **If delta specs exist:**
-   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
-   - Determine what changes would be applied (adds, modifications, removals, renames)
-   - Show a combined summary before prompting
-
-   **Prompt options:**
-   - If changes needed: "Sync now (recommended)", "Archive without syncing"
-   - If already synced: "Archive now", "Sync anyway", "Cancel"
-
-   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
-
-5. **Perform the archive**
-
-   Create the archive directory if it doesn't exist:
-   ```bash
-   mkdir -p openspec/changes/archive
-   ```
-
-   Generate target name using current date: `YYYY-MM-DD-<change-name>`
-
-   **Check if target already exists:**
-   - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move the change directory to archive
-
-   ```bash
-   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
-   ```
-
-6. **Display summary**
-
-   Show archive completion summary including:
-   - Change name
-   - Schema that was used
-   - Archive location
-   - Whether specs were synced (if applicable)
-   - Note about any warnings (incomplete artifacts/tasks)
-
-**Output On Success**
-
-```
-## Archive Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
-**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
-
-All artifacts complete. All tasks complete.
-```
-
-**Guardrails**
-- Always prompt for change selection if not provided
-- Use artifact graph (openspec status --json) for completion checking
-- Don't block archive on warnings - just inform and confirm
-- Preserve .openspec.yaml when moving to archive (it moves with the directory)
-- Show clear summary of what happened
-- If sync is requested, use openspec-sync-specs approach (agent-driven)
-- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.claude/skills/openspec-explore/SKILL.md b/.claude/skills/openspec-explore/SKILL.md
deleted file mode 100644
index 836820e..0000000
--- a/.claude/skills/openspec-explore/SKILL.md
+++ /dev/null
@@ -1,288 +0,0 @@
----
-name: openspec-explore
-description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.3.1"
----
-
-Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
-
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
-
-**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
-
----
-
-## The Stance
-
-- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
-- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
-- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
-- **Adaptive** - Follow interesting threads, pivot when new information emerges
-- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
-- **Grounded** - Explore the actual codebase when relevant, don't just theorize
-
----
-
-## What You Might Do
-
-Depending on what the user brings, you might:
-
-**Explore the problem space**
-- Ask clarifying questions that emerge from what they said
-- Challenge assumptions
-- Reframe the problem
-- Find analogies
-
-**Investigate the codebase**
-- Map existing architecture relevant to the discussion
-- Find integration points
-- Identify patterns already in use
-- Surface hidden complexity
-
-**Compare options**
-- Brainstorm multiple approaches
-- Build comparison tables
-- Sketch tradeoffs
-- Recommend a path (if asked)
-
-**Visualize**
-```
-┌─────────────────────────────────────────┐
-│     Use ASCII diagrams liberally        │
-├─────────────────────────────────────────┤
-│                                         │
-│      ┌────────┐         ┌────────┐      │
-│      │ State  │────────▶│ State  │      │
-│      │   A    │         │   B    │      │
-│      └────────┘         └────────┘      │
-│                                         │
-│   System diagrams, state machines,      │
-│   data flows, architecture sketches,    │
-│   dependency graphs, comparison tables  │
-│                                         │
-└─────────────────────────────────────────┘
-```
-
-**Surface risks and unknowns**
-- Identify what could go wrong
-- Find gaps in understanding
-- Suggest spikes or investigations
-
----
-
-## OpenSpec Awareness
-
-You have full context of the OpenSpec system. Use it naturally, don't force it.
-
-### Check for context
-
-At the start, quickly check what exists:
-```bash
-openspec list --json
-```
-
-This tells you:
-- If there are active changes
-- Their names, schemas, and status
-- What the user might be working on
-
-### When no change exists
-
-Think freely. When insights crystallize, you might offer:
-
-- "This feels solid enough to start a change. Want me to create a proposal?"
-- Or keep exploring - no pressure to formalize
-
-### When a change exists
-
-If the user mentions a change or you detect one is relevant:
-
-1. **Read existing artifacts for context**
-   - `openspec/changes/<name>/proposal.md`
-   - `openspec/changes/<name>/design.md`
-   - `openspec/changes/<name>/tasks.md`
-   - etc.
-
-2. **Reference them naturally in conversation**
-   - "Your design mentions using Redis, but we just realized SQLite fits better..."
-   - "The proposal scopes this to premium users, but we're now thinking everyone..."
-
-3. **Offer to capture when decisions are made**
-
-    | Insight Type               | Where to Capture               |
-    |----------------------------|--------------------------------|
-    | New requirement discovered | `openspec/specs/<capability>/spec.md` |
-    | Requirement changed        | `openspec/specs/<capability>/spec.md` |
-    | Design decision made       | `design.md`                  |
-    | Scope changed              | `proposal.md`                |
-    | New work identified        | `tasks.md`                   |
-    | Assumption invalidated     | Relevant artifact              |
-
-   Example offers:
-   - "That's a design decision. Capture it in design.md?"
-   - "This is a new requirement. Add it to specs?"
-   - "This changes scope. Update the proposal?"
-
-4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
-
----
-
-## What You Don't Have To Do
-
-- Follow a script
-- Ask the same questions every time
-- Produce a specific artifact
-- Reach a conclusion
-- Stay on topic if a tangent is valuable
-- Be brief (this is thinking time)
-
----
-
-## Handling Different Entry Points
-
-**User brings a vague idea:**
-```
-User: I'm thinking about adding real-time collaboration
-
-You: Real-time collab is a big space. Let me think about this...
-
-      COLLABORATION SPECTRUM
-      ════════════════════════════════════════════
-
-      Awareness          Coordination         Sync
-          │                   │                 │
-          ▼                   ▼                 ▼
-      ┌────────┐         ┌────────┐        ┌────────┐
-      │Presence│         │Cursors │        │  CRDT  │
-      │  "3    │         │ Multi  │        │Conflict│
-      │online" │         │ select │        │  free  │
-      └────────┘         └────────┘        └────────┘
-          │                   │                 │
-       trivial            moderate           complex
-
-      Where's your head at?
-```
-
-**User brings a specific problem:**
-```
-User: The auth system is a mess
-
-You: [reads codebase]
-
-     ┌─────────────────────────────────────────────┐
-     │              CURRENT AUTH FLOW              │
-     └─────────────────────────────────────────────┘
-                        │
-          ┌─────────────┼─────────────┐
-          ▼             ▼             ▼
-     ┌─────────┐  ┌─────────┐  ┌─────────┐
-     │ Google  │  │  GitHub │  │  Email  │
-     │  OAuth  │  │  OAuth  │  │  Magic  │
-     └────┬────┘  └────┬────┘  └────┬────┘
-          │             │             │
-          └─────────────┼─────────────┘
-                        ▼
-                  ┌───────────┐
-                  │  Session  │
-                  └─────┬─────┘
-                        │
-                        ▼
-                  ┌───────────┐
-                  │   Perms   │
-                  └───────────┘
-
-     I see three tangles. Which one's burning?
-```
-
-**User is stuck mid-implementation:**
-```
-User: /opsx:explore add-auth-system
-      The OAuth integration is more complex than expected
-
-You: [reads change artifacts]
-
-     You're on task 4: "Implement OAuth flow"
-
-     Let me trace what's involved...
-
-     [draws diagram, explores options, suggests paths]
-
-     Want to update the design to reflect this?
-     Or add a spike task to investigate?
-```
-
-**User wants to compare options:**
-```
-User: Should we use Postgres or SQLite?
-
-You: Generic answer is boring. What's the context?
-
-User: A CLI tool that tracks local dev environments
-
-You: That changes everything.
-
-     ┌─────────────────────────────────────────────────┐
-     │          CLI TOOL DATA STORAGE                  │
-     └─────────────────────────────────────────────────┘
-
-     Key constraints:
-     • No daemon running
-     • Must work offline
-     • Single user
-
-                  SQLite          Postgres
-     Deployment   embedded ✓      needs server ✗
-     Offline      yes ✓           no ✗
-     Single file  yes ✓           no ✗
-
-     SQLite. Not even close.
-
-     Unless... is there a sync component?
-```
-
----
-
-## Ending Discovery
-
-There's no required ending. Discovery might:
-
-- **Flow into a proposal**: "Ready to start? I can create a change proposal."
-- **Result in artifact updates**: "Updated design.md with these decisions"
-- **Just provide clarity**: User has what they need, moves on
-- **Continue later**: "We can pick this up anytime"
-
-When it feels like things are crystallizing, you might summarize:
-
-```
-## What We Figured Out
-
-**The problem**: [crystallized understanding]
-
-**The approach**: [if one emerged]
-
-**Open questions**: [if any remain]
-
-**Next steps** (if ready):
-- Create a change proposal
-- Keep exploring: just keep talking
-```
-
-But this summary is optional. Sometimes the thinking IS the value.
-
----
-
-## Guardrails
-
-- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
-- **Don't fake understanding** - If something is unclear, dig deeper
-- **Don't rush** - Discovery is thinking time, not task time
-- **Don't force structure** - Let patterns emerge naturally
-- **Don't auto-capture** - Offer to save insights, don't just do it
-- **Do visualize** - A good diagram is worth many paragraphs
-- **Do explore the codebase** - Ground discussions in reality
-- **Do question assumptions** - Including the user's and your own
diff --git a/.claude/skills/openspec-propose/SKILL.md b/.claude/skills/openspec-propose/SKILL.md
deleted file mode 100644
index 4b7e204..0000000
--- a/.claude/skills/openspec-propose/SKILL.md
+++ /dev/null
@@ -1,110 +0,0 @@
----
-name: openspec-propose
-description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: openspec
-  version: "1.0"
-  generatedBy: "1.3.1"
----
-
-Propose a new change - create the change and generate all artifacts in one step.
-
-I'll create a change with artifacts:
-- proposal.md (what & why)
-- design.md (how)
-- tasks.md (implementation steps)
-
-When ready to implement, run /opsx:apply
-
----
-
-**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
-
-**Steps**
-
-1. **If no clear input provided, ask what they want to build**
-
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
-   > "What change do you want to work on? Describe what you want to build or fix."
-
-   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
-
-   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
-
-2. **Create the change directory**
-   ```bash
-   openspec new change "<name>"
-   ```
-   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
-
-3. **Get the artifact build order**
-   ```bash
-   openspec status --change "<name>" --json
-   ```
-   Parse the JSON to get:
-   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
-   - `artifacts`: list of all artifacts with their status and dependencies
-
-4. **Create artifacts in sequence until apply-ready**
-
-   Use the **TodoWrite tool** to track progress through the artifacts.
-
-   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
-
-   a. **For each artifact that is `ready` (dependencies satisfied)**:
-      - Get instructions:
-        ```bash
-        openspec instructions <artifact-id> --change "<name>" --json
-        ```
-      - The instructions JSON includes:
-        - `context`: Project background (constraints for you - do NOT include in output)
-        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
-        - `template`: The structure to use for your output file
-        - `instruction`: Schema-specific guidance for this artifact type
-        - `outputPath`: Where to write the artifact
-        - `dependencies`: Completed artifacts to read for context
-      - Read any completed dependency files for context
-      - Create the artifact file using `template` as the structure
-      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
-      - Show brief progress: "Created <artifact-id>"
-
-   b. **Continue until all `applyRequires` artifacts are complete**
-      - After creating each artifact, re-run `openspec status --change "<name>" --json`
-      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
-      - Stop when all `applyRequires` artifacts are done
-
-   c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
-      - Then continue with creation
-
-5. **Show final status**
-   ```bash
-   openspec status --change "<name>"
-   ```
-
-**Output**
-
-After completing all artifacts, summarize:
-- Change name and location
-- List of artifacts created with brief descriptions
-- What's ready: "All artifacts created! Ready for implementation."
-- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
-
-**Artifact Creation Guidelines**
-
-- Follow the `instruction` field from `openspec instructions` for each artifact type
-- The schema defines what each artifact should contain - follow it
-- Read dependency artifacts for context before creating new ones
-- Use `template` as the structure for your output file - fill in its sections
-- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
-  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
-  - These guide what you write, but should never appear in the output
-
-**Guardrails**
-- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
-- Always read dependency artifacts before creating a new one
-- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
-- If a change with that name already exists, ask if user wants to continue it or create a new one
-- Verify each artifact file exists after writing before proceeding to next
diff --git a/.claude/skills/verify/SKILL.md b/.claude/skills/verify/SKILL.md
deleted file mode 100644
index a7b3db4..0000000
--- a/.claude/skills/verify/SKILL.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-name: verify
-description: Run format check, build, and tests to verify changes are correct. Use before committing or after significant edits.
----
-
-Run full verification for Tiny-LLM:
-
-## Steps
-
-1. **Format check** — Verify C++/CUDA formatting:
-   ```bash
-   find . -type f \( -name '*.cpp' -o -name '*.h' -o -name '*.cu' -o -name '*.cuh' \) \
-     ! -path './build/*' | xargs clang-format-18 --dry-run --Werror
-   ```
-
-2. **Build** — Compile in release mode:
-   ```bash
-   mkdir -p build && cd build && \
-   cmake .. -DCMAKE_BUILD_TYPE=Release -DCUDAHOSTCXX=/usr/bin/g++-10 && \
-   make -j$(nproc)
-   ```
-
-3. **Test** — Run all tests:
-   ```bash
-   cd build && ctest --output-on-failure --timeout 300
-   ```
-
-## On Failure
-
-- If format check fails: run `clang-format-18 -i <files>` to fix
-- If build fails: check GCC version (must be GCC 10 for CUDA)
-- If tests fail: run specific test with `./tiny_llm_tests --gtest_filter="TestSuite.TestName"`
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 9975495..5f2d073 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -2,22 +2,14 @@
 
 ## Project mode
 
-Tiny-LLM is in a final hardening phase. Prefer cleanup, alignment, and reliability work over new roadmap expansion.
+Tiny-LLM is in a final hardening phase. Prefer cleanup, consolidation, and reliability work over roadmap expansion.
 
-## Required workflow
+## Repository priorities
 
-- Use OpenSpec for non-trivial work.
-- Read the active change in `openspec/changes/<name>/` before editing.
-- Treat `openspec/specs/` as the current behavior contract.
-- Keep changes scoped to the active task instead of mixing unrelated cleanup.
-
-## Repository-specific rules
-
-- Do not reintroduce legacy `/specs` guidance.
-- Prefer deleting or merging stale docs over adding parallel explanations.
-- Keep README, Pages, changelog surfaces, and GitHub metadata aligned.
+- Keep the repository free of AI-specific governance scaffolding and duplicate instruction surfaces.
+- Keep README, GitHub Pages, and the root `CHANGELOG.md` aligned with the actual project.
+- Prefer deleting or rewriting stale docs over preserving parallel explanations.
 - Do not assume CI will auto-format or auto-commit fixes.
-- Use `gh` for repository metadata updates.
 
 ## Engineering constraints
 
diff --git a/.omc/project-memory.json b/.omc/project-memory.json
deleted file mode 100644
index eed5c51..0000000
--- a/.omc/project-memory.json
+++ /dev/null
@@ -1,487 +0,0 @@
-{
-  "version": "1.0.0",
-  "lastScanned": 1777255406797,
-  "projectRoot": "/home/shane/dev/tiny-llm",
-  "techStack": {
-    "languages": [
-      {
-        "name": "C/C++",
-        "version": null,
-        "confidence": "high",
-        "markers": [
-          "CMakeLists.txt"
-        ]
-      }
-    ],
-    "frameworks": [],
-    "packageManager": null,
-    "runtime": null
-  },
-  "build": {
-    "buildCommand": null,
-    "testCommand": null,
-    "lintCommand": null,
-    "devCommand": null,
-    "scripts": {}
-  },
-  "conventions": {
-    "namingStyle": null,
-    "importStyle": null,
-    "testPattern": null,
-    "fileOrganization": null
-  },
-  "structure": {
-    "isMonorepo": false,
-    "workspaces": [],
-    "mainDirectories": [
-      "docs",
-      "src",
-      "tests"
-    ],
-    "gitBranches": {
-      "defaultBranch": "master",
-      "branchingStrategy": null
-    }
-  },
-  "customNotes": [],
-  "directoryMap": {
-    "_bmad": {
-      "path": "_bmad",
-      "purpose": null,
-      "fileCount": 0,
-      "lastAccessed": 1777255406776,
-      "keyFiles": []
-    },
-    "_bmad-output": {
-      "path": "_bmad-output",
-      "purpose": null,
-      "fileCount": 0,
-      "lastAccessed": 1777255406783,
-      "keyFiles": []
-    },
-    "build": {
-      "path": "build",
-      "purpose": "Build output",
-      "fileCount": 7,
-      "lastAccessed": 1777255406786,
-      "keyFiles": [
-        "CMakeCache.txt",
-        "CTestTestfile.cmake",
-        "Makefile",
-        "cmake_install.cmake",
-        "compile_commands.json"
-      ]
-    },
-    "docs": {
-      "path": "docs",
-      "purpose": "Documentation",
-      "fileCount": 0,
-      "lastAccessed": 1777255406787,
-      "keyFiles": []
-    },
-    "include": {
-      "path": "include",
-      "purpose": null,
-      "fileCount": 0,
-      "lastAccessed": 1777255406788,
-      "keyFiles": []
-    },
-    "kernels": {
-      "path": "kernels",
-      "purpose": null,
-      "fileCount": 9,
-      "lastAccessed": 1777255406788,
-      "keyFiles": [
-        "attention.cu",
-        "attention.cuh",
-        "elementwise.cu",
-        "elementwise.cuh",
-        "rmsnorm.cu"
-      ]
-    },
-    "openspec": {
-      "path": "openspec",
-      "purpose": null,
-      "fileCount": 2,
-      "lastAccessed": 1777255406789,
-      "keyFiles": [
-        "MIGRATION.md",
-        "config.yaml"
-      ]
-    },
-    "src": {
-      "path": "src",
-      "purpose": "Source code",
-      "fileCount": 8,
-      "lastAccessed": 1777255406790,
-      "keyFiles": [
-        "gguf_parser.cpp",
-        "inference_engine.cpp",
-        "kv_cache.cpp",
-        "logger.cpp",
-        "main.cpp"
-      ]
-    },
-    "tests": {
-      "path": "tests",
-      "purpose": "Test files",
-      "fileCount": 10,
-      "lastAccessed": 1777255406790,
-      "keyFiles": [
-        "test_cuda_utils.cpp",
-        "test_inference_engine.cu",
-        "test_integration.cu",
-        "test_kernels.cu",
-        "test_kv_cache.cpp"
-      ]
-    },
-    "website": {
-      "path": "website",
-      "purpose": null,
-      "fileCount": 9,
-      "lastAccessed": 1777255406790,
-      "keyFiles": [
-        "404.html",
-        "CONTRIBUTING.md",
-        "Gemfile",
-        "Gemfile.lock",
-        "_config.yml"
-      ]
-    },
-    "build/bin": {
-      "path": "build/bin",
-      "purpose": "Executable scripts",
-      "fileCount": 0,
-      "lastAccessed": 1777255406794,
-      "keyFiles": []
-    },
-    "build/lib": {
-      "path": "build/lib",
-      "purpose": "Library code",
-      "fileCount": 4,
-      "lastAccessed": 1777255406795,
-      "keyFiles": [
-        "libgmock.a",
-        "libgmock_main.a",
-        "libgtest.a"
-      ]
-    },
-    "openspec/schemas": {
-      "path": "openspec/schemas",
-      "purpose": "Schema definitions",
-      "fileCount": 0,
-      "lastAccessed": 1777255406796,
-      "keyFiles": []
-    },
-    "website/assets": {
-      "path": "website/assets",
-      "purpose": "Static assets",
-      "fileCount": 0,
-      "lastAccessed": 1777255406796,
-      "keyFiles": []
-    }
-  },
-  "hotPaths": [
-    {
-      "path": "src/model_loader.cpp",
-      "accessCount": 13,
-      "lastAccessed": 1777257673956,
-      "type": "file"
-    },
-    {
-      "path": "tests/test_transformer.cu",
-      "accessCount": 9,
-      "lastAccessed": 1777257236015,
-      "type": "file"
-    },
-    {
-      "path": "src/kv_cache.cpp",
-      "accessCount": 8,
-      "lastAccessed": 1777257759828,
-      "type": "file"
-    },
-    {
-      "path": "include/tiny_llm/kv_cache.h",
-      "accessCount": 7,
-      "lastAccessed": 1777257453553,
-      "type": "file"
-    },
-    {
-      "path": "website/_config.yml",
-      "accessCount": 6,
-      "lastAccessed": 1777258100896,
-      "type": "file"
-    },
-    {
-      "path": "src",
-      "accessCount": 5,
-      "lastAccessed": 1777255779397,
-      "type": "directory"
-    },
-    {
-      "path": "CMakeLists.txt",
-      "accessCount": 5,
-      "lastAccessed": 1777258089724,
-      "type": "file"
-    },
-    {
-      "path": "website/docs/en/QUICKSTART.md",
-      "accessCount": 4,
-      "lastAccessed": 1777257367165,
-      "type": "file"
-    },
-    {
-      "path": "include/tiny_llm/transformer.h",
-      "accessCount": 4,
-      "lastAccessed": 1777257428455,
-      "type": "file"
-    },
-    {
-      "path": "src/inference_engine.cpp",
-      "accessCount": 4,
-      "lastAccessed": 1777257795452,
-      "type": "file"
-    },
-    {
-      "path": "AGENTS.md",
-      "accessCount": 4,
-      "lastAccessed": 1777258003740,
-      "type": "file"
-    },
-    {
-      "path": "CHANGELOG.md",
-      "accessCount": 4,
-      "lastAccessed": 1777258036771,
-      "type": "file"
-    },
-    {
-      "path": "README.md",
-      "accessCount": 3,
-      "lastAccessed": 1777255779363,
-      "type": "file"
-    },
-    {
-      "path": "CONTRIBUTING.md",
-      "accessCount": 3,
-      "lastAccessed": 1777255800009,
-      "type": "file"
-    },
-    {
-      "path": "openspec/changes/normalize-archive-readiness/tasks.md",
-      "accessCount": 3,
-      "lastAccessed": 1777255995800,
-      "type": "file"
-    },
-    {
-      "path": "include/tiny_llm/types.h",
-      "accessCount": 3,
-      "lastAccessed": 1777256852250,
-      "type": "file"
-    },
-    {
-      "path": "website/docs/en/API.md",
-      "accessCount": 3,
-      "lastAccessed": 1777257338308,
-      "type": "file"
-    },
-    {
-      "path": "website/docs/zh/API.md",
-      "accessCount": 3,
-      "lastAccessed": 1777257394533,
-      "type": "file"
-    },
-    {
-      "path": "website/docs/zh/QUICKSTART.md",
-      "accessCount": 3,
-      "lastAccessed": 1777257411287,
-      "type": "file"
-    },
-    {
-      "path": "CLAUDE.md",
-      "accessCount": 2,
-      "lastAccessed": 1777255730189,
-      "type": "file"
-    },
-    {
-      "path": "include",
-      "accessCount": 2,
-      "lastAccessed": 1777255759060,
-      "type": "directory"
-    },
-    {
-      "path": "include/tiny_llm/result.h",
-      "accessCount": 2,
-      "lastAccessed": 1777255759125,
-      "type": "file"
-    },
-    {
-      "path": "src/transformer.cpp",
-      "accessCount": 2,
-      "lastAccessed": 1777255759218,
-      "type": "file"
-    },
-    {
-      "path": "tests",
-      "accessCount": 2,
-      "lastAccessed": 1777255772007,
-      "type": "directory"
-    },
-    {
-      "path": "include/tiny_llm/gguf_parser.h",
-      "accessCount": 2,
-      "lastAccessed": 1777256300155,
-      "type": "file"
-    },
-    {
-      "path": "README.zh-CN.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255466026,
-      "type": "file"
-    },
-    {
-      "path": "include/tiny_llm/cuda_utils.h",
-      "accessCount": 1,
-      "lastAccessed": 1777255466220,
-      "type": "file"
-    },
-    {
-      "path": "website/index.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255475051,
-      "type": "file"
-    },
-    {
-      "path": "website/docs/zh/README.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255475144,
-      "type": "file"
-    },
-    {
-      "path": "website/docs/en/README.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255475197,
-      "type": "file"
-    },
-    {
-      "path": "include/tiny_llm/validator.h",
-      "accessCount": 1,
-      "lastAccessed": 1777255476063,
-      "type": "file"
-    },
-    {
-      "path": "include/tiny_llm/inference_engine.h",
-      "accessCount": 1,
-      "lastAccessed": 1777255476593,
-      "type": "file"
-    },
-    {
-      "path": "include/tiny_llm/model_loader.h",
-      "accessCount": 1,
-      "lastAccessed": 1777255476772,
-      "type": "file"
-    },
-    {
-      "path": "include/tiny_llm/logger.h",
-      "accessCount": 1,
-      "lastAccessed": 1777255477006,
-      "type": "file"
-    },
-    {
-      "path": "website/docs/zh/DEVELOPER.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255483010,
-      "type": "file"
-    },
-    {
-      "path": "website/docs/en/BENCHMARKS.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255483203,
-      "type": "file"
-    },
-    {
-      "path": "website/docs/en/DEVELOPER.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255483261,
-      "type": "file"
-    },
-    {
-      "path": "website/docs/zh/BENCHMARKS.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255483373,
-      "type": "file"
-    },
-    {
-      "path": "openspec/MIGRATION.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255487782,
-      "type": "file"
-    },
-    {
-      "path": "openspec/config.yaml",
-      "accessCount": 1,
-      "lastAccessed": 1777255487804,
-      "type": "file"
-    },
-    {
-      "path": "website/docs/en/TROUBLESHOOTING.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255490015,
-      "type": "file"
-    },
-    {
-      "path": "website/changelog/en/v2.0.1.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255490067,
-      "type": "file"
-    },
-    {
-      "path": "website/docs/zh/TROUBLESHOOTING.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255490229,
-      "type": "file"
-    },
-    {
-      "path": "website/changelog/en/v2.0.0.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255491500,
-      "type": "file"
-    },
-    {
-      "path": "tests/test_main.cpp",
-      "accessCount": 1,
-      "lastAccessed": 1777255500171,
-      "type": "file"
-    },
-    {
-      "path": "kernels/attention.cuh",
-      "accessCount": 1,
-      "lastAccessed": 1777255500226,
-      "type": "file"
-    },
-    {
-      "path": "kernels/w8a16_matmul.cu",
-      "accessCount": 1,
-      "lastAccessed": 1777255500289,
-      "type": "file"
-    },
-    {
-      "path": "kernels/attention.cu",
-      "accessCount": 1,
-      "lastAccessed": 1777255500376,
-      "type": "file"
-    },
-    {
-      "path": "tests/test_inference_engine.cu",
-      "accessCount": 1,
-      "lastAccessed": 1777255500404,
-      "type": "file"
-    },
-    {
-      "path": "openspec/specs/inference-engine/spec.md",
-      "accessCount": 1,
-      "lastAccessed": 1777255503595,
-      "type": "file"
-    }
-  ],
-  "userDirectives": []
-}
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 100644
index 35c88a8..0000000
--- a/AGENTS.md
+++ /dev/null
@@ -1,139 +0,0 @@
-# Tiny-LLM Agent Guide
-
-Tiny-LLM is in a **final hardening / archive-readiness** phase. Treat this repository as a CUDA/C++ engine that should become **smaller, sharper, and lower-noise** over time.
-
-## Operating mode
-
-- Prioritize correctness, coherence, and maintainability over new roadmap expansion.
-- Prefer deleting, merging, or rewriting low-value content instead of preserving redundant guidance.
-- Keep public claims aligned with what the repository actually implements and validates.
-- Avoid over-engineering new automation, process, or tooling layers.
-
-## Source of truth
-
-1. **Active OpenSpec change** in `openspec/changes/<name>/`
-2. **Current capability specs** in `openspec/specs/`
-3. **Repository code and configuration**
-4. **Project instruction files** (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`)
-
-Local-only overrides such as `CLAUDE.local.md` are allowed for personal use, but they are **not** authoritative and should not be committed.
-
-## Required workflow
-
-### 1. Explore before guessing
-
-Use `/opsx:explore` for open-ended investigation, architecture trade-offs, and requirement clarification.
-
-### 2. Propose before non-trivial changes
-
-Use `/opsx:propose <change-name>` for:
-
-- repository-wide cleanup
-- workflow changes
-- public-surface repositioning
-- feature or behavior changes
-- multi-file refactors with architectural impact
-
-### 3. Apply from explicit tasks
-
-Use `/opsx:apply <change-name>` and implement directly from `tasks.md`. Work in dependency order and keep each task tightly scoped.
-
-### 4. Review major workstreams
-
-After major workflow, documentation, or architecture changes, run a review-oriented pass (`/review` or equivalent) before considering the workstream complete.
-
-### 5. Archive finished changes
-
-Use `/opsx:archive <change-name>` only after specs, code, docs, and validation results all agree.
-
-## Repository priorities
-
-### OpenSpec-first governance
-
-- Do not reintroduce legacy `/specs` workflow guidance.
-- Keep contributor docs aligned with `openspec/`.
-- Preserve history through OpenSpec archive, not through duplicated meta-docs.
-
-### Minimal, high-signal documentation
-
-- Prefer one authoritative document per topic.
-- Remove stale changelog pages, duplicated contribution docs, and generic AI boilerplate.
-- Keep README and Pages useful for new users, not just comprehensive.
-
-### Non-mutating automation
-
-- CI should validate, not rewrite tracked files or commit back to the branch.
-- Keep workflow triggers and jobs as small as possible while preserving confidence.
-
-### Public-surface consistency
-
-- README, GitHub Pages, release notes, and GitHub metadata must describe the same project.
-- Remove unsupported roadmap promises and speculative positioning.
-
-## Engineering invariants
-
-- **Language/toolchain:** C++17, CUDA C++17, CMake 3.18+
-- **GPU baseline:** CUDA 11.0+, Compute Capability 7.0+
-- **Error handling:** `Result<T>` for fallible operations; no exceptions for control flow
-- **CUDA safety:** use the project CUDA utilities/macros instead of silent failures
-- **Resource management:** prefer RAII wrappers over raw ownership
-- **Formatting:** `clang-format-18` with the repository `.clang-format`
-- **Editor baseline:** `clangd` + `compile_commands.json`
-
-## Core architecture
-
-| Component | Responsibility |
-|-----------|----------------|
-| `Result<T>` | No-exception error propagation |
-| `ModelConfig` | Model hyperparameters (vocab_size, hidden_dim, etc.) |
-| `QuantizedWeight` | INT8 weights with per-group scales |
-| `TransformerLayer` | W8A16 quantized attention + FFN |
-| `KVCacheManager` | Pre-allocated cache slots for sequences |
-| `InferenceEngine` | Public API: load(), generate() |
-
-### Validation commands
-
-```bash
-cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
-cmake --build build -j$(nproc)
-ctest --test-dir build --output-on-failure --timeout 300
-find . -type f \( -name '*.cpp' -o -name '*.h' -o -name '*.cu' -o -name '*.cuh' \) \
-  ! -path './build/*' | xargs clang-format-18 --dry-run --Werror
-```
-
-`nvcc` must be available for a real configure/build.
-
-## Practical AI-tooling guidance
-
-- **AGENTS.md**: repository-wide rules and architecture constraints
-- **CLAUDE.md**: Claude/agent execution guidance for this repo
-- **Copilot instructions**: concise code-generation and workflow constraints
-
-Use a **long-running single session** for large repository hardening work. Avoid `/fleet` unless the work is clearly parallelizable and the higher token cost is justified.
-
-Use subagents and research helpers selectively:
-
-- good fit: independent audits, workflow inspection, broad doc inventories
-- bad fit: tightly coupled refactors where one agent needs end-to-end context
-
-Keep MCP usage narrow. Prefer built-in GitHub tooling and `gh` unless MCP gives a clear repository-specific win.
-
-## Repository map
-
-```text
-openspec/                 OpenSpec config, active changes, archived changes, specs, schemas
-include/tiny_llm/         Public headers
-src/                      Host-side C++ implementation
-kernels/                  CUDA kernels
-tests/                    Unit and property tests
-website/                  GitHub Pages site
-.github/workflows/        CI, Pages, release automation
-```
-
-## Do not do these by default
-
-- Do not add large new roadmap features just because they are easy to imagine.
-- Do not preserve outdated docs “for completeness”.
-- Do not commit personal-only tool config.
-- Do not rely on CI to auto-fix formatting or repository drift.
-- Do not split work across many stale branches without quick review and merge.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26daa24..3bd2966 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,20 +1,17 @@
 # Changelog
 
-Tiny-LLM keeps a deliberately short public changelog. Only meaningful release milestones belong here.
-
-English | [中文](changelog/index.zh)
-
----
+All notable tracked releases of Tiny-LLM are recorded here.
 
 ## Releases
 
-| Version | Date | Summary | English | 中文 |
-|---|---|---|---|---|
-| v2.0.2 | 2026-04-27 | Code quality improvements, GGUF quantization utilities, repository cleanup | [Details](https://lessup.github.io/tiny-llm/changelog/en/v2.0.2) | [详情](https://lessup.github.io/tiny-llm/changelog/zh/v2.0.2) |
-| v2.0.1 | 2026-04-16 | Bug-fix release for scale-dimension handling and cleanup | [Details](https://lessup.github.io/tiny-llm/changelog/en/v2.0.1) | [详情](https://lessup.github.io/tiny-llm/changelog/zh/v2.0.1) |
-| v2.0.0 | 2026-03-09 | Core engine milestone with KV cache API redesign | [Details](https://lessup.github.io/tiny-llm/changelog/en/v2.0.0) | [详情](https://lessup.github.io/tiny-llm/changelog/zh/v2.0.0) |
+| Version | Date | Summary |
+|---|---|---|
+| v2.0.2 | 2026-04-27 | Code quality improvements, GGUF quantization utilities, and repository cleanup |
+| v2.0.1 | 2026-04-16 | Bug-fix release for scale-dimension handling and loader cleanup |
+| v2.0.0 | 2026-03-09 | Core engine milestone with KV cache API redesign |
 
-## Notes
+## Policy
 
-- Infrastructure-only or low-signal changes are intentionally omitted from the public changelog.
-- Detailed release notes live in the [website changelog](https://lessup.github.io/tiny-llm/changelog/).
+- This file is the only tracked changelog in the repository.
+- Keep entries short and focused on meaningful user-facing or maintainer-relevant milestones.
+- Do not duplicate release history in the documentation site.
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index 2561bf9..0000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# CLAUDE.md
-
-This file defines the preferred Claude/agent operating style for Tiny-LLM.
-
-## Mission
-
-Help finish the repository cleanly:
-
-- tighten OpenSpec compliance
-- reduce document and workflow drift
-- keep the CUDA/C++ core reliable
-- make the public project surface sharper
-- avoid speculative expansion
-
-## Default workflow
-
-1. Read the active OpenSpec change and current specs first.
-2. If the task is non-trivial and no change exists, propose one before broad edits.
-3. Implement from `tasks.md` in dependency order.
-4. Run a review pass after major workstreams.
-5. Archive the change when code, docs, and specs agree.
-
-## Editing posture
-
-- Prefer precise rewrites over layering more generic text.
-- Prefer deleting stale material over “keeping both”.
-- Keep CI non-mutating.
-- Keep user-facing claims conservative and verifiable.
-- Respect existing user changes in the working tree; reconcile before overwriting.
-
-## Tooling posture
-
-- Use `gh` for repository metadata work.
-- Treat `clangd` + `compile_commands.json` as the canonical LSP baseline.
-- Keep MCP/plugin usage optional and narrow.
-- Prefer long single-session execution over `/fleet`.
-
-## Technical reminders
-
-- C++17 + CUDA C++17
-- `Result<T>` instead of control-flow exceptions
-- RAII for resource ownership
-- `clang-format-18`
-- `nvcc` required for real configure/build/test passes
-
-## Core architecture
-
-| Component | Responsibility |
-|-----------|----------------|
-| `Result<T>` | No-exception error propagation |
-| `ModelConfig` | Model hyperparameters (vocab_size, hidden_dim, etc.) |
-| `QuantizedWeight` | INT8 weights with per-group scales |
-| `TransformerLayer` | W8A16 quantized attention + FFN |
-| `KVCacheManager` | Pre-allocated cache slots for sequences |
-| `InferenceEngine` | Public API: load(), generate() |
-
-## Validation commands
-
-```bash
-cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
-cmake --build build -j$(nproc)
-ctest --test-dir build --output-on-failure --timeout 300
-```
-
-## Local overrides
-
-Personal overrides may live in `CLAUDE.local.md`, but that file is local-only and must stay untracked.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c49e7fe..976755d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,40 +1,20 @@
 # Contributing to Tiny-LLM
 
-Tiny-LLM accepts focused issues and pull requests, but the repository is now optimized for **coherent hardening work**, not broad roadmap expansion. Keep changes small, reviewable, and anchored in the current architecture.
+Tiny-LLM is in a hardening and cleanup phase. Prefer focused, reviewable changes that make the repository smaller, clearer, and more accurate.
 
-## Core rules
+## Working rules
 
-1. **OpenSpec first.** Non-trivial changes start in `openspec/`, not in ad hoc docs or code-only branches.
-2. **One authoritative source per topic.** Prefer deleting or merging stale docs over adding parallel guidance.
-3. **Short-lived branches.** Avoid long-lived local/cloud drift; merge or rebase frequently.
+1. **Keep one source of truth per topic.** If two documents explain the same thing, merge or delete one.
+2. **Do not reintroduce workflow scaffolding.** Avoid adding repository-level agent command packs, memory dumps, spec trees, or parallel instruction documents.
+3. **Keep release history in one place.** The root `CHANGELOG.md` is the only tracked changelog.
 4. **CI validates, contributors fix.** Do not rely on automation to rewrite tracked files for you.
 
-## Required workflow
+## Typical workflow
 
-### 1. Explore when the scope is unclear
-
-Use `/opsx:explore` for investigation, trade-off analysis, and requirement clarification.
-
-### 2. Propose before cross-cutting implementation
-
-Use `/opsx:propose <change-name>` for repository-wide cleanup, new behavior, or architectural changes. The proposal should produce:
-
-- `proposal.md`
-- `design.md`
-- `specs/.../spec.md`
-- `tasks.md`
-
-### 3. Implement against explicit tasks
-
-Use `/opsx:apply <change-name>` and work directly from `tasks.md`. Finish tasks in dependency order and keep edits tightly scoped.
-
-### 4. Review before concluding major workstreams
-
-Use `/review` or an equivalent review pass after major workflow, documentation, or architecture changes. Do not batch unrelated cleanup into one unreviewed sweep.
-
-### 5. Archive completed changes
-
-Use `/opsx:archive <change-name>` after specs, code, and docs are aligned and the repository is ready to preserve the change in `openspec/changes/archive/`.
+1. Read the current code and the directly relevant docs.
+2. Make one coherent change at a time.
+3. Update user-facing docs when behavior, supported workflows, or public links change.
+4. Run the validation commands before concluding your work.
 
 ## Build and validation
 
@@ -53,25 +33,17 @@ find . -type f \( -name '*.cpp' -o -name '*.h' -o -name '*.cu' -o -name '*.cuh'
   ! -path './build/*' | xargs clang-format-18 --dry-run --Werror
 ```
 
-## Repository hygiene
-
-- Keep README, GitHub Pages, and GitHub metadata consistent with the actual shipped engine.
-- Treat low-value changelog entries, duplicated workflow docs, and stale roadmap promises as cleanup targets.
-- If a document references removed directories or obsolete workflow commands, fix or delete it before merging.
-
-## Low-maintenance flow
-
-When the repository only needs focused follow-up work, use this loop:
-
-1. Keep one active OpenSpec change per meaningful workstream.
-2. Prefer short-lived branches or a single coordinated branch over parallel stale branches.
-3. Use review checkpoints after each major workstream instead of saving all review until the end.
-4. Archive the change as soon as specs, code, and docs converge so the repository returns to a calm baseline quickly.
+## Documentation rules
 
-## Project-specific guidance
+- Keep README, GitHub Pages, badges, clone links, and issue links aligned with the same repository identity.
+- Keep public claims conservative and verifiable.
+- If a page becomes stale, duplicated, or lower-signal than the code itself, rewrite it or remove it.
+- The documentation site should document the engine, not mirror release history or process bureaucracy.
 
-- **Repository workflow and architecture constraints:** [AGENTS.md](AGENTS.md)
-- **Current capabilities and requirements:** `openspec/specs/`
-- **Active and archived change history:** `openspec/changes/`
+## Project-specific constraints
 
-Use [Conventional Commits](https://www.conventionalcommits.org/) where practical (`feat:`, `fix:`, `docs:`, `ci:`, `refactor:`), but prioritize clear, reviewable changes over ceremony.
+- Language/toolchain: **C++17 + CUDA C++17**
+- Error model: prefer **`Result<T>`** for fallible operations
+- Ownership model: prefer **RAII** over raw lifetime management
+- Formatting: **`clang-format-18`**
+- Language intelligence baseline: **`clangd` + `compile_commands.json`**
diff --git a/README.md b/README.md
index 4a43e8f..5ec8d9d 100644
--- a/README.md
+++ b/README.md
@@ -1,44 +1,40 @@
-# Tiny-LLM Inference Engine
+# Tiny-LLM
 
-> CUDA-native C++ inference engine for focused Transformer deployments.
+> CUDA-native C++ inference engine for focused Transformer workloads.
 
-[![CI](https://github.com/LessUp/tiny-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/LessUp/tiny-llm/actions/workflows/ci.yml)
-[![Pages](https://github.com/LessUp/tiny-llm/actions/workflows/pages.yml/badge.svg)](https://lessup.github.io/tiny-llm/)
-[![Release](https://img.shields.io/github/v/release/LessUp/tiny-llm?include_prereleases&label=version)](https://github.com/LessUp/tiny-llm/releases)
+[![CI](https://github.com/AICL-Lab/tiny-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/AICL-Lab/tiny-llm/actions/workflows/ci.yml)
+[![Pages](https://github.com/AICL-Lab/tiny-llm/actions/workflows/pages.yml/badge.svg)](https://aicl-lab.github.io/tiny-llm/)
+[![Release](https://img.shields.io/github/v/release/AICL-Lab/tiny-llm?include_prereleases&label=version)](https://github.com/AICL-Lab/tiny-llm/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 ![CUDA](https://img.shields.io/badge/CUDA-11.0+-76B900?logo=nvidia&logoColor=white)
 ![C++](https://img.shields.io/badge/C%2B%2B-17-00599C?logo=c%2B%2B&logoColor=white)
 ![CMake](https://img.shields.io/badge/CMake-3.18+-064F8C?logo=cmake&logoColor=white)
 
-[English](README.md) • [简体中文](README.zh-CN.md) • [Documentation](https://lessup.github.io/tiny-llm/) • [Architecture](https://lessup.github.io/tiny-llm/en/architecture/overview) • [Changelog](https://lessup.github.io/tiny-llm/en/changelog/)
+[English](README.md) • [简体中文](README.zh-CN.md) • [Documentation](https://aicl-lab.github.io/tiny-llm/) • [Architecture](https://aicl-lab.github.io/tiny-llm/en/architecture/) • [API](https://aicl-lab.github.io/tiny-llm/en/api/) • [Changelog](CHANGELOG.md)
 
 ---
 
 ## Overview
 
-Tiny-LLM is a lightweight inference engine for Transformer workloads on NVIDIA GPUs. It is built around a focused CUDA/C++ stack: W8A16 quantization, explicit KV cache management, hand-tuned kernels, and a repository workflow designed to keep the codebase coherent as it hardens.
+Tiny-LLM keeps the repository surface deliberately small: CUDA/C++17 kernels, W8A16 quantization, explicit KV cache management, and a narrow runtime path that is easier to audit and maintain.
 
-## Why Tiny-LLM
+## What is implemented
 
-- **W8A16 quantization** with INT8 weights and FP16 activations
-- **Explicit KV cache management** for incremental decoding
+- **W8A16 inference path** with INT8 weights and FP16 activations
+- **Explicit KV cache management** for autoregressive decoding
 - **CUDA-native kernels** with shared-memory and warp-level optimization patterns
-- **Minimal runtime surface** with `spdlog` as the primary runtime dependency
-- **OpenSpec-governed development** so architecture, docs, and changes stay aligned
+- **`Result<T>`-based fallible APIs** for host-side error propagation
+- **GoogleTest + RapidCheck coverage** for core runtime paths
 
-## Core capabilities
+## Model-loading surfaces
 
-| Capability | What it covers | Status |
-|---|---|---|
-| W8A16 inference path | Quantized weights, FP16 activations, CUDA kernels | Stable |
-| KV cache manager | Sequence allocation, growth, and release | Stable |
-| Sampling utilities | Greedy, temperature, top-k, top-p | Stable |
-| Error handling | `Result<T>`-based fallible APIs | Stable |
-| Test strategy | GoogleTest + RapidCheck coverage for core paths | Active |
+- `InferenceEngine::load()` currently accepts the repository's supported **binary runtime format**.
+- `GGUFParser` is available for **GGUF parsing, metadata extraction, and tensor inspection**.
+- Direct GGUF runtime loading is **not** part of the current inference path.
 
 ## Build from source
 
-Tiny-LLM requires a working CUDA toolchain (`nvcc` on `PATH` or an equivalent configured install).
+Tiny-LLM requires a working CUDA toolchain (`nvcc` on `PATH` or an equivalent configured installation).
 
 | Component | Minimum |
 |---|---|
@@ -48,7 +44,7 @@ Tiny-LLM requires a working CUDA toolchain (`nvcc` on `PATH` or an equivalent co
 | C++ Compiler | GCC 9+ or Clang 10+ |
 
 ```bash
-git clone https://github.com/LessUp/tiny-llm.git
+git clone https://github.com/AICL-Lab/tiny-llm.git
 cd tiny-llm
 
 cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
@@ -59,54 +55,55 @@ ctest --test-dir build --output-on-failure --timeout 300
 ## Minimal usage example
 
 ```cpp
+#include <iostream>
 #include <tiny_llm/inference_engine.h>
 
 int main() {
+    using namespace tiny_llm;
+
     ModelConfig config;
     config.vocab_size = 32000;
     config.hidden_dim = 4096;
     config.num_layers = 32;
 
-    auto engine = InferenceEngine::load("model.bin", config).value();
+    auto engine_result = InferenceEngine::load("model.bin", config);
+    if (engine_result.isErr()) {
+        std::cerr << engine_result.error() << '\n';
+        return 1;
+    }
 
     GenerationConfig gen;
-    gen.max_new_tokens = 256;
+    gen.max_new_tokens = 64;
     gen.temperature = 0.7f;
     gen.top_p = 0.9f;
+    gen.do_sample = true;
+
+    auto engine = std::move(engine_result.value());
+    auto output = engine->generate({1, 15043, 29892}, gen);
+    if (output.isErr()) {
+        std::cerr << output.error() << '\n';
+        return 1;
+    }
 
-    auto output = engine.generate({1, 15043, 29892}, gen);
-    (void)output;
+    return 0;
 }
 ```
 
 ## Repository map
 
 ```text
-openspec/                 Current specs, active changes, archived changes, schemas
 include/tiny_llm/         Public headers
 src/                      Host-side C++ implementation
 kernels/                  CUDA kernels
 tests/                    Unit and property tests
 docs/                     VitePress documentation site
 .github/workflows/        CI, Pages, and release automation
+CHANGELOG.md              Canonical tracked release history
 ```
 
-## Documentation and specs
-
-- **Project site:** https://lessup.github.io/tiny-llm/
-- **Architecture guide:** https://lessup.github.io/tiny-llm/en/architecture/overview
-- **Developer guide:** https://lessup.github.io/tiny-llm/en/developer
-- **API reference:** https://lessup.github.io/tiny-llm/en/api/
-- **OpenSpec source of truth:** `openspec/specs/`
-- **Change history:** `openspec/changes/`
-
 ## Contributing
 
-Tiny-LLM uses an OpenSpec-first workflow for non-trivial changes.
-
-- Start with [CONTRIBUTING.md](CONTRIBUTING.md)
-- Read repository-specific constraints in [AGENTS.md](AGENTS.md)
-- Use `/opsx:propose`, `/opsx:apply`, and `/opsx:archive` for structured work
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before sending changes. Keep changes focused, keep docs aligned with the real runtime surface, and keep the repository free of duplicate workflow scaffolding.
 
 ## License
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index c796aa5..c04ca0f 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,44 +1,40 @@
 # Tiny-LLM 推理引擎
 
-> 面向聚焦型 Transformer 部署场景的 CUDA 原生 C++ 推理引擎。
+> 面向聚焦型 Transformer 工作负载的 CUDA 原生 C++ 推理引擎。
 
-[![CI](https://github.com/LessUp/tiny-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/LessUp/tiny-llm/actions/workflows/ci.yml)
-[![Pages](https://github.com/LessUp/tiny-llm/actions/workflows/pages.yml/badge.svg)](https://lessup.github.io/tiny-llm/)
-[![Release](https://img.shields.io/github/v/release/LessUp/tiny-llm?include_prereleases&label=version)](https://github.com/LessUp/tiny-llm/releases)
+[![CI](https://github.com/AICL-Lab/tiny-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/AICL-Lab/tiny-llm/actions/workflows/ci.yml)
+[![Pages](https://github.com/AICL-Lab/tiny-llm/actions/workflows/pages.yml/badge.svg)](https://aicl-lab.github.io/tiny-llm/)
+[![Release](https://img.shields.io/github/v/release/AICL-Lab/tiny-llm?include_prereleases&label=version)](https://github.com/AICL-Lab/tiny-llm/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 ![CUDA](https://img.shields.io/badge/CUDA-11.0+-76B900?logo=nvidia&logoColor=white)
 ![C++](https://img.shields.io/badge/C%2B%2B-17-00599C?logo=c%2B%2B&logoColor=white)
 ![CMake](https://img.shields.io/badge/CMake-3.18+-064F8C?logo=cmake&logoColor=white)
 
-[English](README.md) • [简体中文](README.zh-CN.md) • [文档](https://lessup.github.io/tiny-llm/) • [架构说明](https://lessup.github.io/tiny-llm/zh/architecture/overview) • [更新日志](https://lessup.github.io/tiny-llm/zh/changelog/)
+[English](README.md) • [简体中文](README.zh-CN.md) • [文档](https://aicl-lab.github.io/tiny-llm/) • [架构说明](https://aicl-lab.github.io/tiny-llm/zh/architecture/) • [API](https://aicl-lab.github.io/tiny-llm/zh/api/) • [更新日志](CHANGELOG.md)
 
 ---
 
 ## 项目概述
 
-Tiny-LLM 是一个面向 NVIDIA GPU 的轻量级 Transformer 推理引擎，围绕一套聚焦的 CUDA/C++ 技术栈构建：W8A16 量化、显式 KV Cache 管理、手工优化的 CUDA Kernel，以及用来约束仓库演进的 OpenSpec 工作流。
+Tiny-LLM 将仓库表面保持得尽量小：CUDA/C++17 内核、W8A16 量化、显式 KV Cache 管理，以及一条更容易审计和维护的精简运行时路径。
 
-## 为什么是 Tiny-LLM
+## 已实现能力
 
-- **W8A16 量化路径**：INT8 权重 + FP16 激活
-- **显式 KV Cache 管理**：适合增量解码
+- **W8A16 推理路径**：INT8 权重 + FP16 激活
+- **显式 KV Cache 管理**：面向自回归解码
 - **CUDA 原生 Kernel**：共享内存与 warp 级优化模式
-- **运行时依赖面很小**：主要运行时依赖为 `spdlog`
-- **OpenSpec 驱动开发**：让架构、文档和改动保持同步
+- **基于 `Result<T>` 的可失败 API**：宿主侧错误传播更直接
+- **GoogleTest + RapidCheck 测试覆盖**：覆盖核心运行时路径
 
-## 核心能力
+## 模型加载边界
 
-| 能力 | 说明 | 状态 |
-|---|---|---|
-| W8A16 推理路径 | 量化权重、FP16 激活、CUDA Kernel | 稳定 |
-| KV Cache 管理 | 序列分配、增长和释放 | 稳定 |
-| 采样工具 | Greedy、temperature、top-k、top-p | 稳定 |
-| 错误处理 | 基于 `Result<T>` 的可失败 API | 稳定 |
-| 测试策略 | GoogleTest + RapidCheck 覆盖核心路径 | 持续维护 |
+- `InferenceEngine::load()` 当前接受仓库支持的**二进制运行时格式**。
+- `GGUFParser` 用于 **GGUF 解析、元数据提取和 tensor 检查**。
+- 直接用 GGUF 进行运行时加载 **不属于** 当前推理路径。
 
 ## 从源码构建
 
-Tiny-LLM 需要可用的 CUDA 工具链（`nvcc` 在 `PATH` 中，或已正确配置的 CUDA 安装）。
+Tiny-LLM 需要可用的 CUDA 工具链（`nvcc` 在 `PATH` 中，或已正确配置 CUDA 安装）。
 
 | 组件 | 最低要求 |
 |---|---|
@@ -48,7 +44,7 @@ Tiny-LLM 需要可用的 CUDA 工具链（`nvcc` 在 `PATH` 中，或已正确
 | C++ 编译器 | GCC 9+ 或 Clang 10+ |
 
 ```bash
-git clone https://github.com/LessUp/tiny-llm.git
+git clone https://github.com/AICL-Lab/tiny-llm.git
 cd tiny-llm
 
 cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
@@ -59,54 +55,55 @@ ctest --test-dir build --output-on-failure --timeout 300
 ## 最小使用示例
 
 ```cpp
+#include <iostream>
 #include <tiny_llm/inference_engine.h>
 
 int main() {
+    using namespace tiny_llm;
+
     ModelConfig config;
     config.vocab_size = 32000;
     config.hidden_dim = 4096;
     config.num_layers = 32;
 
-    auto engine = InferenceEngine::load("model.bin", config).value();
+    auto engine_result = InferenceEngine::load("model.bin", config);
+    if (engine_result.isErr()) {
+        std::cerr << engine_result.error() << '\n';
+        return 1;
+    }
 
     GenerationConfig gen;
-    gen.max_new_tokens = 256;
+    gen.max_new_tokens = 64;
     gen.temperature = 0.7f;
     gen.top_p = 0.9f;
+    gen.do_sample = true;
+
+    auto engine = std::move(engine_result.value());
+    auto output = engine->generate({1, 15043, 29892}, gen);
+    if (output.isErr()) {
+        std::cerr << output.error() << '\n';
+        return 1;
+    }
 
-    auto output = engine.generate({1, 15043, 29892}, gen);
-    (void)output;
+    return 0;
 }
 ```
 
 ## 仓库结构
 
 ```text
-openspec/                 当前规范、活跃变更、归档变更、schemas
 include/tiny_llm/         公共头文件
 src/                      主机端 C++ 实现
 kernels/                  CUDA kernels
 tests/                    单元测试与属性测试
 docs/                     VitePress 文档站点
 .github/workflows/        CI、Pages、release 自动化
+CHANGELOG.md              唯一的已跟踪发布历史
 ```
 
-## 文档与规范
-
-- **项目主页：** https://lessup.github.io/tiny-llm/
-- **架构说明：** https://lessup.github.io/tiny-llm/zh/architecture/overview
-- **开发者指南：** https://lessup.github.io/tiny-llm/zh/developer
-- **API 参考：** https://lessup.github.io/tiny-llm/zh/api/
-- **OpenSpec 规范源：** `openspec/specs/`
-- **变更历史：** `openspec/changes/`
-
 ## 参与贡献
 
-Tiny-LLM 对非平凡改动采用 OpenSpec-first 工作流。
-
-- 先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)
-- 再阅读仓库级约束 [AGENTS.md](AGENTS.md)
-- 通过 `/opsx:propose`、`/opsx:apply`、`/opsx:archive` 进行结构化开发
+提交改动前请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。保持改动聚焦、让文档与真实运行时边界一致，并避免重新引入重复的流程脚手架。
 
 ## 许可证
 
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 88132f0..3e1aad1 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -21,7 +21,7 @@ export default withMermaid(
     head: [
       ['meta', { name: 'theme-color', content: '#00D4AA' }],
       ['meta', { name: 'og:type', content: 'website' }],
-      ['meta', { name: 'og:title', content: 'Tiny-LLM | Technical Whitepaper' }],
+      ['meta', { name: 'og:title', content: 'Tiny-LLM | CUDA-Native Inference Engine' }],
       ['meta', { name: 'og:description', content: 'CUDA-native inference engine for Transformer models with W8A16 quantization' }],
       ['link', { rel: 'icon', href: '/tiny-llm/favicon.svg' }],
       ['link', { rel: 'apple-touch-icon', href: '/tiny-llm/apple-touch-icon.png' }],
@@ -51,7 +51,6 @@ export default withMermaid(
             { text: 'Performance', link: '/en/performance/' },
             { text: 'API', link: '/en/api/' },
             { text: 'Guide', link: '/en/guide/getting-started' },
-            { text: 'Changelog', link: '/en/changelog/' },
           ],
           sidebar: {
             '/en/architecture/': [
@@ -112,17 +111,6 @@ export default withMermaid(
                 ],
               },
             ],
-            '/en/changelog/': [
-              {
-                text: 'Changelog',
-                items: [
-                  { text: 'Overview', link: '/en/changelog/' },
-                  { text: 'v2.0.2', link: '/en/changelog/v2.0.2' },
-                  { text: 'v2.0.1', link: '/en/changelog/v2.0.1' },
-                  { text: 'v2.0.0', link: '/en/changelog/v2.0.0' },
-                ],
-              },
-            ],
           },
           editLink: {
             pattern: 'https://github.com/AICL-Lab/tiny-llm/edit/master/docs/:path',
@@ -164,7 +152,6 @@ export default withMermaid(
             { text: '性能', link: '/zh/performance/' },
             { text: 'API', link: '/zh/api/' },
             { text: '指南', link: '/zh/guide/getting-started' },
-            { text: '更新日志', link: '/zh/changelog/' },
           ],
           sidebar: {
             '/zh/architecture/': [
@@ -225,17 +212,6 @@ export default withMermaid(
                 ],
               },
             ],
-            '/zh/changelog/': [
-              {
-                text: '更新日志',
-                items: [
-                  { text: '概述', link: '/zh/changelog/' },
-                  { text: 'v2.0.2', link: '/zh/changelog/v2.0.2' },
-                  { text: 'v2.0.1', link: '/zh/changelog/v2.0.1' },
-                  { text: 'v2.0.0', link: '/zh/changelog/v2.0.0' },
-                ],
-              },
-            ],
           },
           editLink: {
             pattern: 'https://github.com/AICL-Lab/tiny-llm/edit/master/docs/:path',
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
index 1410399..d26c141 100644
--- a/docs/.vitepress/theme/custom.css
+++ b/docs/.vitepress/theme/custom.css
@@ -1,7 +1,7 @@
 /**
- * Tiny-LLM Technical Whitepaper - Custom Styles
+ * Tiny-LLM Documentation Site - Custom Styles
  *
- * Design Language: Technical whitepaper / Architecture showcase
+ * Design Language: Minimal technical documentation
  * Brand Colors:
  * - Primary (Teal): oklch(0.75 0.15 168) ≈ #00D4AA
  * - Accent (CUDA Green): oklch(0.70 0.20 95) ≈ #76B900
@@ -38,7 +38,7 @@
   --vp-c-brand-3: var(--tiny-llm-primary-dark);
   --vp-c-brand-soft: oklch(0.75 0.06 168);
 
-  /* Refined backgrounds (whitepaper feel) */
+  /* Refined documentation backgrounds */
   --vp-c-bg: oklch(0.99 0 0);
   --vp-c-bg-soft: oklch(0.97 0 0);
   --vp-c-bg-mute: oklch(0.94 0 0);
@@ -85,7 +85,7 @@
   --vp-c-brand-3: var(--tiny-llm-primary-dark);
   --vp-c-brand-soft: oklch(0.75 0.06 168 / 0.16);
 
-  /* True dark for whitepaper */
+  /* Dark-mode documentation background */
   --vp-c-bg: oklch(0.13 0 0);
   --vp-c-bg-soft: oklch(0.17 0 0);
   --vp-c-bg-mute: oklch(0.21 0 0);
diff --git a/docs/en/api/index.md b/docs/en/api/index.md
index 83eb7ce..bdd6386 100644
--- a/docs/en/api/index.md
+++ b/docs/en/api/index.md
@@ -1,81 +1,52 @@
 # API Reference
 
-Welcome to the Tiny-LLM API reference documentation.
+Tiny-LLM exposes a compact public C++ surface under the `tiny_llm` namespace.
 
-## Core Components
+## Primary Headers
 
-| Component | Description |
-|-----------|-------------|
-| [InferenceEngine](/en/api/inference-engine) | Main inference engine class |
-| [ModelConfig](/en/api/model-config) | Model hyperparameters |
-| [Result\<T\>](/en/api/result) | Error handling wrapper |
-| [KVCacheManager](/en/api/kv-cache) | Key-value cache management |
+| Header | Purpose |
+|--------|---------|
+| `<tiny_llm/inference_engine.h>` | Runtime loading and token generation |
+| `<tiny_llm/model_loader.h>` | Host-side runtime model loading helpers |
+| `<tiny_llm/gguf_parser.h>` | GGUF parsing, metadata extraction, tensor inspection |
+| `<tiny_llm/kv_cache.h>` | KV cache allocation and sequence management |
+| `<tiny_llm/result.h>` | `Result<T>` error propagation |
+| `<tiny_llm/types.h>` | Shared config, weight, and stats types |
 
 ## Quick Example
 
 ```cpp
-#include <tiny-llm/inference_engine.h>
-#include <tiny-llm/model_config.h>
-#include <tiny-llm/result.h>
-
-using namespace tinyllm;
+#include <iostream>
+#include <tiny_llm/inference_engine.h>
 
 int main() {
-    // Create engine
-    InferenceEngine engine;
+    using namespace tiny_llm;
 
-    // Load model
-    Result<void> load_result = engine.load("model.bin");
-    if (!load_result.ok()) {
-        std::cerr << "Error: " << load_result.error() << std::endl;
+    ModelConfig config;
+    auto engine_result = InferenceEngine::load("model.bin", config);
+    if (engine_result.isErr()) {
+        std::cerr << engine_result.error() << '\n';
         return 1;
     }
 
-    // Generate text
-    GenerationConfig config;
-    config.max_tokens = 100;
-    config.temperature = 0.7f;
-
-    Result<std::string> result = engine.generate("Hello, world!", config);
-    if (result.ok()) {
-        std::cout << result.value() << std::endl;
+    auto engine = std::move(engine_result.value());
+    auto output = engine->generate({1, 15043, 29892}, GenerationConfig{});
+    if (output.isErr()) {
+        std::cerr << output.error() << '\n';
+        return 1;
     }
-
-    return 0;
 }
 ```
 
-## Error Handling
+## Loading Surface
 
-All operations return `Result\<T\>` for safe error propagation:
-
-```cpp
-Result\<T\> result = some_operation();
-if (!result.ok()) {
-    // Handle error
-    std::cerr << result.error() << std::endl;
-} else {
-    // Use result
-    T value = result.value();
-}
-```
-
-## Namespaces
-
-All public APIs are in the `tinyllm` namespace:
-
-```cpp
-using namespace tinyllm;
-// or
-tinyllm::InferenceEngine engine;
-```
+- Use `InferenceEngine::load()` for the supported binary runtime format.
+- Use `GGUFParser` when you need GGUF parsing or metadata access.
+- Do not assume a tokenizer or text-string generation API exists in the public surface.
 
-## Header Files
+## Reference Pages
 
-| Header | Description |
-|--------|-------------|
-| `<tiny-llm/inference_engine.h>` | Main engine class |
-| `<tiny-llm/model_config.h>` | Configuration structs |
-| `<tiny-llm/result.h>` | Result type |
-| `<tiny-llm/kv_cache.h>` | Cache management |
-| `<tiny-llm/tokenizer.h>` | Tokenization utilities |
+- [InferenceEngine](/en/api/inference-engine)
+- [Result&lt;T&gt;](/en/api/result)
+- [KVCacheManager](/en/api/kv-cache)
+- [ModelConfig](/en/api/model-config)
diff --git a/docs/en/api/inference-engine.md b/docs/en/api/inference-engine.md
index 9068109..9051496 100644
--- a/docs/en/api/inference-engine.md
+++ b/docs/en/api/inference-engine.md
@@ -1,646 +1,94 @@
 ---
 layout: doc
 title: "Inference Engine API"
-description: "Complete API reference for Tiny-LLM inference engine"
+description: "Public runtime API for Tiny-LLM"
 ---
 
 # Inference Engine API
 
-Complete API reference for Tiny-LLM inference engine.
-
-## Data Types
-
-### ModelConfig
-
-Model configuration structure defining all hyperparameters.
+## Class Overview
 
 ```cpp
 #include <tiny_llm/inference_engine.h>
 
-struct ModelConfig {
-    int vocab_size = 32000;           // Vocabulary size
-    int hidden_dim = 4096;            // Hidden dimension
-    int num_layers = 32;              // Number of Transformer layers
-    int num_heads = 32;               // Number of attention heads
-    int num_kv_heads = 32;            // Number of KV heads (GQA support)
-    int head_dim = 128;               // Dimension per head
-    int intermediate_dim = 11008;     // FFN intermediate dimension
-    int max_seq_len = 2048;           // Maximum sequence length
-    float rope_theta = 10000.0f;      // RoPE base frequency
-    float rms_norm_eps = 1e-5f;       // RMSNorm epsilon
-    int eos_token_id = 2;             // End-of-sequence token ID
-    int bos_token_id = 1;             // Beginning-of-sequence token ID
-};
-```
-
-**Common Configurations**:
-
-| Model Size | hidden_dim | num_layers | num_heads | intermediate_dim |
-|------------|------------|------------|-----------|------------------|
-| 7B | 4096 | 32 | 32 | 11008 |
-| 13B | 5120 | 40 | 40 | 13824 |
-| 70B | 8192 | 80 | 64 | 28672 |
-
-### GenerationConfig
-
-Text generation configuration controlling sampling behavior.
-
-```cpp
-struct GenerationConfig {
-    int max_new_tokens = 256;         // Maximum tokens to generate
-    float temperature = 1.0f;         // Sampling temperature
-    int top_k = 50;                   // Top-k sampling cutoff
-    float top_p = 0.9f;               // Top-p (nucleus) sampling threshold
-    bool do_sample = false;           // Enable sampling (false = greedy)
-    float repetition_penalty = 1.0f;  // Penalty for repeated tokens
-};
-```
-
-**Sampling Parameters**:
-
-| Parameter | Range | Effect |
-|-----------|-------|--------|
-| `temperature` | 0.0 - 2.0 | Lower = more deterministic |
-| `top_k` | 1 - vocab_size | Consider only top k tokens |
-| `top_p` | 0.0 - 1.0 | Consider tokens with cumulative prob ≤ p |
-| `repetition_penalty` | 1.0 - 2.0 | >1.0 penalizes repeated tokens |
-
-### QuantizedWeight
-
-INT8 quantized weight with FP16 scales.
-
-```cpp
-struct QuantizedWeight {
-    int8_t* data;                     // INT8 weights [rows, cols]
-    half* scales;                     // FP16 scales [rows/group_size, cols]
-    int rows;                         // Input dimension
-    int cols;                         // Output dimension
-    int group_size = 128;             // Quantization group size
-    
-    // Helper methods
-    int scaleRows() const;            // ceil(rows / group_size)
-    int scaleCols() const;            // cols
-    size_t weightElements() const;    // rows * cols
-    size_t scaleElements() const;     // scaleRows() * cols
-    size_t weightBytes() const;       // weightElements()
-    size_t scaleBytes() const;        // scaleElements() * 2
-    size_t totalBytes() const;        // weightBytes + scaleBytes
-    bool isValid() const;             // Validate dimensions
-};
-```
-
-### GenerationStats
-
-Performance statistics from text generation.
-
-```cpp
-struct GenerationStats {
-    float prefill_time_ms = 0.0f;     // Prefill phase time (ms)
-    float decode_time_ms = 0.0f;      // Decode phase time (ms)
-    int prompt_tokens = 0;            // Number of prompt tokens
-    int tokens_generated = 0;         // Number of generated tokens
-    float tokens_per_second = 0.0f;   // Generation throughput
-    size_t peak_memory_bytes = 0;     // Peak GPU memory usage
-};
-```
-
-## Core Classes
-
-### InferenceEngine
-
-Main inference engine class. Thread-safe for concurrent generation on different engine instances.
-
-```cpp
-#include <tiny_llm/inference_engine.h>
+namespace tiny_llm {
 
 class InferenceEngine {
 public:
-    // Load model from custom binary format
-    static Result\<std::unique_ptr\<InferenceEngine\>\> load(
+    static Result<std::unique_ptr<InferenceEngine>> load(
         const std::string& model_path,
-        const ModelConfig& config
-    );
-    
-    // Generate completion for prompt
-    std::vector<int> generate(
+        const ModelConfig& config);
+
+    Result<std::vector<int>> generate(
         const std::vector<int>& prompt_tokens,
-        const GenerationConfig& gen_config
-    );
-    
-    // Get generation statistics
+        const GenerationConfig& config);
+
     const GenerationStats& getStats() const;
     void resetStats();
-    
-    // Standalone sampling functions (stateless)
-    static int sampleGreedy(
-        const half* logits, int vocab_size);
-    
-    static int sampleTemperature(
-        const half* logits, int vocab_size,
-        float temperature, unsigned seed = 0);
-    
-    static int sampleTopK(
-        const half* logits, int vocab_size,
-        int k, float temperature, unsigned seed = 0);
-    
-    static int sampleTopP(
-        const half* logits, int vocab_size,
-        float p, float temperature, unsigned seed = 0);
-};
-```
-
-**Usage Example**:
-
-```cpp
-// Configure model
-ModelConfig config;
-config.vocab_size = 32000;
-config.hidden_dim = 4096;
-config.num_layers = 32;
 
-// Load model
-auto result = InferenceEngine::load("model.bin", config);
-if (result.isErr()) {
-    std::cerr << "Error: " << result.error() << std::endl;
-    return 1;
-}
-auto engine = std::move(result.value());
-
-// Configure generation
-GenerationConfig gen_config;
-gen_config.max_new_tokens = 256;
-gen_config.temperature = 0.7f;
-gen_config.top_p = 0.9f;
-gen_config.do_sample = true;
-
-// Generate
-std::vector<int> prompt = {1, 15043, 29892};  // "Hello,"
-auto output = engine->generate(prompt, gen_config);
-
-// Check performance
-const auto& stats = engine->getStats();
-std::cout << "Speed: " << stats.tokens_per_second << " tok/s" << std::endl;
-```
-
-### KVCacheManager
-
-Efficient key-value cache management for autoregressive generation.
-
-```cpp
-#include <tiny_llm/kv_cache.h>
-
-struct KVCacheConfig {
-    int num_layers = 32;              // Number of transformer layers
-    int num_heads = 32;               // Number of KV heads
-    int head_dim = 128;               // Dimension per head
-    int max_seq_len = 2048;           // Maximum sequence length
-    int max_batch_size = 1;           // Maximum batch size
+    static int sampleGreedy(const half* logits, int vocab_size);
+    static int sampleTemperature(const half* logits, int vocab_size, float temperature,
+                                 unsigned seed = 0);
+    static int sampleTopK(const half* logits, int vocab_size, int k, float temperature,
+                          unsigned seed = 0);
+    static int sampleTopP(const half* logits, int vocab_size, float p, float temperature,
+                          unsigned seed = 0);
 };
 
-class KVCacheManager {
-public:
-    explicit KVCacheManager(const KVCacheConfig& config);
-    ~KVCacheManager();
-    
-    // Sequence management
-    Result\<int\> allocateSequence(int max_len);
-    void releaseSequence(int seq_id);
-    bool hasSequence(int seq_id) const;
-    
-    // Cache access for attention computation
-    std::pair<half*, half*> getCache(int seq_id, int layer_idx);
-    int getSeqLen(int seq_id) const;
-    
-    // KV append (write-only, stateless)
-    void appendKV(int seq_id, int layer_idx,
-                  const half* new_k, const half* new_v,
-                  int num_tokens, cudaStream_t stream = 0);
-    
-    // Advance sequence length after all layers complete
-    void advanceSeqLen(int seq_id, int num_tokens);
-    
-    // Memory statistics
-    size_t getUsedMemory() const;
-    size_t getTotalMemory() const;
-    size_t getFreeMemory() const;
-    int getActiveSequenceCount() const;
-};
-```
-
-**Usage Pattern**:
-
-```cpp
-KVCacheConfig cache_config;
-cache_config.num_layers = 32;
-cache_config.num_heads = 32;
-cache_config.head_dim = 128;
-cache_config.max_seq_len = 2048;
-
-// Use factory method for proper error handling
-auto cache_result = KVCacheManager::create(cache_config);
-if (cache_result.isErr()) {
-    // Handle creation failure
-}
-auto kv_cache = std::move(cache_result.value());
-
-// Allocate sequence
-auto seq_result = kv_cache->allocateSequence(1024);
-if (seq_result.isErr()) {
-    // Handle allocation failure
-}
-int seq_id = seq_result.value();
-
-// Forward pass through layers
-for (int i = 0; i < num_layers; i++) {
-    layers[i]->forward(hidden_states, *kv_cache, seq_id, position, stream);
-}
-
-// Advance sequence length after all layers
-kv_cache->advanceSeqLen(seq_id, 1);
-
-// Release when done
-kv_cache->releaseSequence(seq_id);
+} // namespace tiny_llm
 ```
 
-### TransformerLayer
-
-Single transformer layer with attention and FFN.
-
-```cpp
-#include <tiny_llm/transformer.h>
-
-class TransformerLayer {
-public:
-    TransformerLayer(int layer_idx,
-                     const TransformerWeights& weights,
-                     const ModelConfig& config);
-    
-    // Single token forward (decode phase)
-    void forward(half* hidden_states,
-                 KVCacheManager& kv_cache,
-                 int seq_id,
-                 int position,
-                 cudaStream_t stream = 0);
-    
-    // Multi-token forward (prefill phase)
-    void forwardPrefill(half* hidden_states,
-                        KVCacheManager& kv_cache,
-                        int seq_id,
-                        int seq_len,
-                        cudaStream_t stream = 0);
-    
-    int getLayerIdx() const;
-};
-```
+## Runtime Loading
 
-## CUDA Kernels
+- `load("model.bin", config)` targets the supported binary runtime format.
+- Passing a `.gguf` path returns a structured error explaining that direct GGUF runtime loading is not currently supported.
+- GGUF parsing/inspection lives on `GGUFParser`.
 
-### W8A16 Matrix Multiplication
+## Usage Example
 
 ```cpp
-#include <w8a16_matmul.cuh>
-
-namespace tiny_llm::kernels {
-
-// Main W8A16 matmul kernel
-void w8a16_matmul(
-    const half* input,           // [M, K] FP16
-    const int8_t* weight,        // [K, N] INT8 (column-major)
-    const half* scales,          // [K/group_size, N] FP16
-    half* output,                // [M, N] FP16
-    int M,                       // Batch size
-    int N,                       // Output dimension
-    int K,                       // Input dimension
-    int group_size,              // Quantization group size
-    cudaStream_t stream = 0
-);
-
-// Weight dequantization (for testing/reference)
-void dequantize_weights(
-    const int8_t* weight_int8,
-    const half* scales,
-    half* weight_fp16,
-    int K, int N,
-    int group_size,
-    cudaStream_t stream = 0
-);
-
-// Reference implementation for validation
-void w8a16_matmul_reference(
-    const half* input,
-    const int8_t* weight,
-    const half* scales,
-    half* output,
-    int M, int N, int K,
-    int group_size
-);
-
-}
-```
-
-### Attention Kernels
-
-```cpp
-#include <attention.cuh>
-
-namespace tiny_llm::kernels {
-
-// Decode: single query token against cached KV
-void attention_decode(
-    const half* query,           // [batch, num_heads, 1, head_dim]
-    const half* k_cache,         // [batch, num_heads, seq_len, head_dim]
-    const half* v_cache,         // [batch, num_heads, seq_len, head_dim]
-    half* output,                // [batch, num_heads, 1, head_dim]
-    float scale,                 // 1/sqrt(head_dim)
-    int batch_size,
-    int num_heads,
-    int seq_len,
-    int head_dim,
-    cudaStream_t stream = 0
-);
-
-// Prefill: all query tokens with causal mask
-void attention_prefill(
-    const half* query,           // [batch, num_heads, seq_len, head_dim]
-    const half* key,             // [batch, num_heads, seq_len, head_dim]
-    const half* value,           // [batch, num_heads, seq_len, head_dim]
-    half* output,                // [batch, num_heads, seq_len, head_dim]
-    float scale,
-    int batch_size,
-    int num_heads,
-    int seq_len,
-    int head_dim,
-    cudaStream_t stream = 0
-);
-
-// Standalone softmax
-void softmax(
-    const half* input,           // [batch, seq_len]
-    half* output,
-    int batch_size,
-    int seq_len,
-    cudaStream_t stream = 0
-);
-
-}
-```
-
-### RMSNorm
-
-```cpp
-#include <rmsnorm.cuh>
-
-namespace tiny_llm::kernels {
-
-// RMSNorm: output = x / sqrt(mean(x^2) + eps) * weight
-void rmsnorm(
-    const half* input,           // [batch, hidden_dim]
-    const half* weight,          // [hidden_dim]
-    half* output,                // [batch, hidden_dim]
-    int batch_size,
-    int hidden_dim,
-    float eps = 1e-5f,
-    cudaStream_t stream = 0
-);
-
-// In-place RMSNorm
-void rmsnorm_inplace(
-    half* x,                     // [batch, hidden_dim] (in-place)
-    const half* weight,
-    int batch_size,
-    int hidden_dim,
-    float eps = 1e-5f,
-    cudaStream_t stream = 0
-);
-
-}
-```
-
-### Elementwise Operations
-
-```cpp
-#include <elementwise.cuh>
-
-namespace tiny_llm::kernels {
-
-// In-place addition: data[i] += add[i]
-void add_inplace(
-    half* data,
-    const half* add,
-    int num_elements,
-    cudaStream_t stream = 0
-);
-
-// SwiGLU fused: gate[i] = silu(gate[i]) * up[i]
-void silu_mul_inplace(
-    half* gate,
-    const half* up,
-    int num_elements,
-    cudaStream_t stream = 0
-);
-
-// Embedding lookup
-void gather_embeddings(
-    const int* tokens,           // [num_tokens]
-    const half* embedding,       // [vocab_size, hidden_dim]
-    half* output,                // [num_tokens, hidden_dim]
-    int num_tokens,
-    int hidden_dim,
-    int vocab_size,
-    cudaStream_t stream = 0
-);
-
-}
-```
-
-## Error Handling
-
-### Result\<T\>
+#include <iostream>
+#include <tiny_llm/inference_engine.h>
 
-Rust-inspired Result type for error handling without exceptions.
+int main() {
+    using namespace tiny_llm;
 
-```cpp
-#include <tiny_llm/result.h>
+    ModelConfig config;
+    auto engine_result = InferenceEngine::load("model.bin", config);
+    if (engine_result.isErr()) {
+        std::cerr << engine_result.error() << '\n';
+        return 1;
+    }
 
-template\<typename T\>
-class Result {
-public:
-    // Constructors
-    static Result\<T\> ok(T value);
-    static Result\<T\> err(std::string message);
-    
-    // State checks
-    bool isOk() const;
-    bool isErr() const;
-    
-    // Value access (throws if error)
-    T& value();
-    const T& value() const;
-    T valueOr(T default_value) const;
-    
-    // Error access (throws if ok)
-    const std::string& error() const;
-    
-    // Monadic operations
-    template\<typename F\>
-    auto map(F&& f) -> Result<decltype(f(value()))>;
-    
-    template\<typename F\>
-    auto flatMap(F&& f) -> decltype(f(value()));
-};
-```
+    auto engine = std::move(engine_result.value());
 
-**Usage**:
+    GenerationConfig generation;
+    generation.max_new_tokens = 64;
+    generation.temperature = 0.7f;
+    generation.top_p = 0.9f;
+    generation.do_sample = true;
 
-```cpp
-Result\<int\> parseInt(const std::string& s) {
-    try {
-        return Result\<int\>::ok(std::stoi(s));
-    } catch (...) {
-        return Result\<int\>::err("Invalid integer: " + s);
+    auto output = engine->generate({1, 15043, 29892}, generation);
+    if (output.isErr()) {
+        std::cerr << output.error() << '\n';
+        return 1;
     }
-}
 
-auto result = parseInt("42");
-if (result.isOk()) {
-    std::cout << "Value: " << result.value() << std::endl;
-} else {
-    std::cerr << "Error: " << result.error() << std::endl;
+    const auto& stats = engine->getStats();
+    std::cout << "Generated " << output.value().size()
+              << " tokens at " << stats.tokens_per_second << " tok/s\n";
 }
-
-// Or with default
-int val = parseInt("abc").valueOr(0);  // val = 0
 ```
 
-### CudaException
+## Input and Output Contract
 
-CUDA error exception with context.
+| Method | Input | Output |
+|--------|-------|--------|
+| `load()` | runtime model path + `ModelConfig` | `Result<std::unique_ptr<InferenceEngine>>` |
+| `generate()` | prompt token IDs + `GenerationConfig` | `Result<std::vector<int>>` |
+| `getStats()` | none | `GenerationStats` |
 
-```cpp
-#include <tiny_llm/cuda_utils.h>
+## Notes
 
-class CudaException : public std::exception {
-public:
-    CudaException(cudaError_t err, const char* file, int line);
-    
-    const char* what() const noexcept override;
-    cudaError_t error() const;
-    const char* file() const;
-    int line() const;
-};
-
-// Error checking macro
-#define CUDA_CHECK(call) \
-    do { \
-        cudaError_t err = call; \
-        if (err != cudaSuccess) { \
-            throw CudaException(err, __FILE__, __LINE__); \
-        } \
-    } while(0)
-```
-
-## Utilities
-
-### DeviceBuffer\<T\>
-
-RAII wrapper for GPU memory.
-
-```cpp
-#include <tiny_llm/cuda_utils.h>
-
-template\<typename T\>
-class DeviceBuffer {
-public:
-    DeviceBuffer();                        // Empty buffer
-    explicit DeviceBuffer(size_t count);   // Allocate count elements
-    ~DeviceBuffer();                       // Automatic cleanup
-    
-    // Non-copyable
-    DeviceBuffer(const DeviceBuffer&) = delete;
-    DeviceBuffer& operator=(const DeviceBuffer&) = delete;
-    
-    // Movable
-    DeviceBuffer(DeviceBuffer&&) noexcept;
-    DeviceBuffer& operator=(DeviceBuffer&&) noexcept;
-    
-    // Data access
-    T* data();
-    const T* data() const;
-    size_t size() const;
-    size_t bytes() const;
-    
-    // Data transfer
-    void copyFromHost(const T* src, size_t count, cudaStream_t stream = 0);
-    void copyToHost(T* dst, size_t count, cudaStream_t stream = 0) const;
-};
-```
-
-### CudaStream
-
-RAII wrapper for CUDA streams.
-
-```cpp
-class CudaStream {
-public:
-    CudaStream();
-    ~CudaStream();
-    
-    CudaStream(const CudaStream&) = delete;
-    CudaStream(CudaStream&&) noexcept;
-    
-    cudaStream_t get() const;
-    operator cudaStream_t() const;
-    
-    void synchronize();
-};
-```
-
-### CudaEvent
-
-CUDA event for timing and synchronization.
-
-```cpp
-class CudaEvent {
-public:
-    CudaEvent();
-    ~CudaEvent();
-    
-    void record(cudaStream_t stream = 0);
-    void synchronize();
-    
-    static float elapsedMs(const CudaEvent& start, const CudaEvent& end);
-    
-    cudaEvent_t get() const;
-};
-```
-
-**Timing Example**:
-
-```cpp
-CudaEvent start, end;
-
-start.record(stream);
-kernel\<\<\<grid, block, 0, stream\>\>\>(...);
-end.record(stream);
-
-end.synchronize();
-float ms = CudaEvent::elapsedMs(start, end);
-std::cout << "Kernel time: " << ms << " ms" << std::endl;
-```
-
-### StreamPool
-
-Pool of CUDA streams for parallel execution.
-
-```cpp
-class StreamPool {
-public:
-    explicit StreamPool(int num_streams = 4);
-    
-    cudaStream_t getStream();        // Round-robin
-    cudaStream_t getStream(int idx);  // By index
-    
-    void synchronizeAll();
-    int numStreams() const;
-};
-```
+- Prompts are token IDs, not raw text strings.
+- Check `isErr()` before calling `value()` or `error()`.
diff --git a/docs/en/api/result.md b/docs/en/api/result.md
index 98142c5..f7b6f1c 100644
--- a/docs/en/api/result.md
+++ b/docs/en/api/result.md
@@ -1,204 +1,51 @@
 # Result\<T\>
 
-The `Result\<T\>` class provides no-exception error handling for Tiny-LLM operations.
+`Result<T>` is Tiny-LLM's host-side fallible return type.
 
-## Overview
-
-Instead of throwing exceptions, Tiny-LLM operations return `Result\<T\>` which either contains a value of type `T` or an error message.
-
-## Class Definition
+## Shape
 
 ```cpp
-namespace tinyllm {
-
 template <typename T>
 class Result {
 public:
-    // Constructors
-    Result(T value);                    // Success result
-    Result(Error error);                // Error result
-    Result(std::string error_message);  // Error from string
+    static Result<T> ok(T value);
+    static Result<T> err(std::string message);
 
-    // Check status
-    bool ok() const;
-    explicit operator bool() const;
+    bool isOk() const;
+    bool isErr() const;
 
-    // Access value (undefined behavior if error)
     T& value();
     const T& value() const;
-    T& operator*();
-    const T& operator*() const;
-    T* operator->();
-    const T* operator->() const;
-
-    // Access value with default
-    T value_or(T default_value) const;
-
-    // Access error
-    const Error& error() const;
-    std::string error_message() const;
-
-private:
-    std::variant<T, Error> data_;
+    const std::string& error() const;
+    T valueOr(T default_value) const;
 };
 
-// Specialization for void
 template <>
 class Result<void> {
 public:
-    Result();                           // Success
-    Result(Error error);                // Error
+    static Result<void> ok();
+    static Result<void> err(std::string message);
 
-    bool ok() const;
-    const Error& error() const;
-    std::string error_message() const;
+    bool isOk() const;
+    bool isErr() const;
+    const std::string& error() const;
 };
-
-}  // namespace tinyllm
 ```
 
-## Usage Patterns
-
-### Basic Error Handling
+## Typical Usage
 
 ```cpp
-Result<ModelConfig> config_result = load_config("config.json");
-if (!config_result.ok()) {
-    std::cerr << "Error: " << config_result.error_message() << std::endl;
+auto engine_result = tiny_llm::InferenceEngine::load("model.bin", config);
+if (engine_result.isErr()) {
+    std::cerr << engine_result.error() << '\n';
     return 1;
 }
 
-ModelConfig config = config_result.value();
-```
-
-### Chaining Operations
-
-```cpp
-Result<void> run_inference(const std::string& model_path, const std::string& prompt) {
-    InferenceEngine engine;
-
-    Result<void> load_result = engine.load(model_path);
-    if (!load_result.ok()) {
-        return load_result;  // Propagate error
-    }
-
-    Result<std::string> gen_result = engine.generate(prompt);
-    if (!gen_result.ok()) {
-        return gen_result.error();
-    }
-
-    std::cout << gen_result.value() << std::endl;
-    return {};  // Success
-}
-```
-
-### Using value_or
-
-```cpp
-Result\<int\> get_num_layers() {
-    // ...
-}
-
-int layers = get_num_layers().value_or(32);  // Default to 32 if error
-```
-
-### Boolean Conversion
-
-```cpp
-Result<void> result = engine.load("model.bin");
-
-if (result) {
-    // Success
-    std::cout << "Model loaded successfully" << std::endl;
-} else {
-    // Error
-    std::cerr << result.error_message() << std::endl;
-}
-```
-
-## Error Class
-
-```cpp
-namespace tinyllm {
-
-class Error {
-public:
-    Error(ErrorCode code, std::string message);
-    Error(std::string message);  // Generic error
-
-    ErrorCode code() const;
-    const std::string& message() const;
-    std::string full_message() const;
-
-private:
-    ErrorCode code_;
-    std::string message_;
-};
-
-enum class ErrorCode {
-    Success = 0,
-    InvalidArgument,
-    FileNotFound,
-    InvalidFormat,
-    OutOfMemory,
-    CudaError,
-    InternalError,
-};
-
-}  // namespace tinyllm
-```
-
-## Best Practices
-
-### 1. Always Check Results
-
-```cpp
-// BAD: Undefined behavior if error
-auto value = result.value();
-
-// GOOD: Check first
-if (result.ok()) {
-    auto value = result.value();
-}
-```
-
-### 2. Propagate Errors
-
-```cpp
-Result<void> process() {
-    Result<Data> data = load_data();
-    if (!data.ok()) {
-        return data.error();  // Propagate error
-    }
-
-    Result<void> processed = transform(data.value());
-    if (!processed.ok()) {
-        return processed;  // Propagate error
-    }
-
-    return {};
-}
+auto engine = std::move(engine_result.value());
 ```
 
-### 3. Use Meaningful Error Messages
-
-```cpp
-return Result<ModelConfig>::Error(
-    ErrorCode::InvalidArgument,
-    "vocab_size must be positive, got: " + std::to_string(vocab_size)
-);
-```
-
-## Comparison with Exceptions
-
-| Aspect | Result\<T\> | Exceptions |
-|--------|-----------|------------|
-| Performance | Zero overhead | Stack unwinding cost |
-| Control flow | Explicit | Implicit |
-| Debuggability | Easy to trace | Can be hard to follow |
-| CUDA compatibility | Excellent | Problematic |
-
-## See Also
+## Guidance
 
-- [InferenceEngine](/en/api/inference-engine) - Main API class
-- [Error Handling Guide](/en/architecture/inference-engine#error-handling)
+- Check `isOk()` / `isErr()` before calling `value()` or `error()`.
+- Use `valueOr()` only when a fallback is genuinely correct.
+- Propagate errors upward instead of swallowing them.
diff --git a/docs/en/architecture/index.md b/docs/en/architecture/index.md
index cc6f65a..d7dd3ea 100644
--- a/docs/en/architecture/index.md
+++ b/docs/en/architecture/index.md
@@ -1,314 +1,54 @@
 # Architecture Overview
 
-System architecture and design documentation for Tiny-LLM inference engine.
+Tiny-LLM centers on a narrow CUDA/C++ runtime: a supported binary runtime loader, explicit KV cache management, W8A16 quantized layers, and host-side `Result<T>` error propagation.
 
-## Overview
-
-Tiny-LLM is a high-performance CUDA C++ inference engine designed for efficient Transformer model inference. It focuses on:
-
-| Feature | Technology | Benefit |
-|---------|------------|---------|
-| **W8A16 Quantization** | INT8 weights + FP16 activations | ~50% memory reduction |
-| **Efficient KV Cache** | Incremental decoding with sequence management | O(1) autoregressive step |
-| **Optimized Kernels** | Tensor Core INT8, shared memory tiling | Maximum throughput |
-| **Modular Design** | Clean separation of concerns | Easy to extend and test |
-
----
-
-## System Architecture
-
-```mermaid
-flowchart TB
-    subgraph Input["📥 Input"]
-        A["Model File<br/>.gguf/.bin"] --> B["GGUF Parser"]
-        P["Prompt Tokens"] --> C["Tokenization"]
-    end
-
-    subgraph Engine["⚙️ InferenceEngine"]
-        B --> D["Model Loader"]
-        D --> E["InferenceEngine"]
-        C --> E
-        E --> F["Transformer Stack"]
-    end
-
-    subgraph Transformer["🔄 Transformer Layers"]
-        F --> G["Embedding Layer"]
-        G --> H["Layer 1..N"]
-        H --> I["LM Head"]
-    end
-
-    subgraph KVCache["💾 KV Cache"]
-        H <--> J["KV Cache Manager"]
-        J --> K["Pre-allocated Slots"]
-    end
-
-    subgraph Output["📤 Output"]
-        I --> L["Sampling"]
-        L --> M["Generated Tokens"]
-    end
-
-    style A fill:#00D4AA,stroke:#00C49A,color:#fff
-    style E fill:#76B900,stroke:#5a8f00,color:#fff
-    style J fill:#F59E0B,stroke:#d97706,color:#fff
-    style L fill:#8B5CF6,stroke:#7c3aed,color:#fff
-```
-
----
-
-## Core Components
-
-### 1. InferenceEngine
-
-The main entry point for model inference.
-
-```cpp
-class InferenceEngine {
-public:
-    // Load model from disk
-    static Result\<std::unique_ptr\<InferenceEngine\>\> load(
-        const std::string& path, const ModelConfig& config);
-    
-    // Complete generation pipeline
-    std::vector<int> generate(
-        const std::vector<int>& prompt, 
-        const GenerationConfig& config);
-    
-    // Statistics and profiling
-    const GenerationStats& getStats() const;
-    void resetStats();
-};
-```
-
-**Key Responsibilities**:
-- Model lifecycle management
-- Prefill/decode orchestration
-- Token sampling and generation loop
-- Performance profiling
-
-### 2. KV Cache Manager
-
-Efficient key-value cache for autoregressive generation.
+## System Sketch
 
 ```mermaid
 flowchart LR
-    subgraph CacheStructure["KV Cache Memory Layout"]
-        K["K Cache<br/>[batch, layers, seq, heads, dim]"]
-        V["V Cache<br/>[batch, layers, seq, heads, dim]"]
-    end
-
-    subgraph Operations["Operations"]
-        A1["allocateSequence()"]
-        A2["appendKV()"]
-        A3["getCache()"]
-        A4["advanceSeqLen()"]
-    end
-
-    A1 --> CacheStructure
-    A2 --> CacheStructure
-    A3 --> CacheStructure
-    A4 --> CacheStructure
-
-    style K fill:#76B900,stroke:#5a8f00,color:#fff
-    style V fill:#76B900,stroke:#5a8f00,color:#fff
+    A[Binary runtime model] --> B[InferenceEngine::load()]
+    C[GGUF file] --> D[GGUFParser]
+    B --> E[ModelWeights]
+    E --> F[Transformer Layers]
+    F --> G[KVCacheManager]
+    F --> H[W8A16 Kernels]
+    H --> I[Sampling]
+    I --> J[Generated token IDs]
+    D --> K[Metadata / Tensor Inspection]
 ```
 
-### 3. W8A16 Quantization
-
-Weight-only INT8 quantization with FP16 activations.
-
-```mermaid
-flowchart TB
-    subgraph QuantScheme["Quantization Scheme"]
-        W["Weight: INT8<br/>[rows, cols]"]
-        S["Scales: FP16<br/>[rows/128, cols]"]
-        O["Output: FP16<br/>= dequant(W, S) @ Act"]
-    end
-
-    W --> O
-    S --> O
-
-    subgraph GroupWise["Group-wise Layout"]
-        G0["group 0 (128 elem) → scales[0]"]
-        G1["group 1 (128 elem) → scales[1]"]
-        GN["..."]
-    end
-
-    style W fill:#8B5CF6,stroke:#7c3aed,color:#fff
-    style S fill:#F59E0B,stroke:#d97706,color:#fff
-    style O fill:#00D4AA,stroke:#00C49A,color:#fff
-```
-
-**Benefits**:
-- 50% weight memory reduction
-- No activation quantization (maintains precision)
-- Efficient INT8 Tensor Core utilization on Ampere+
-
----
-
-## Data Flow
-
-### Prefill Phase (Prompt Processing)
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant Engine as InferenceEngine
-    participant Trans as Transformer
-    participant KV as KV Cache
-    participant Sample as Sampling
-
-    User->>Engine: generate(prompt, config)
-    Engine->>Engine: tokenize(prompt)
-    Engine->>Trans: forward(tokens, prefill=true)
-    
-    loop For each layer
-        Trans->>Trans: RMSNorm
-        Trans->>Trans: QKV Projection (W8A16)
-        Trans->>Trans: RoPE
-        Trans->>Trans: Attention Prefill
-        Trans->>KV: store_kv(layer, k, v)
-        Trans->>Trans: Output Projection
-        Trans->>Trans: Residual
-    end
-    
-    Trans-->>Engine: logits
-    Engine->>Sample: sample(logits)
-    Sample-->>Engine: first_token
-    Engine-->>User: first_token
-```
-
-### Decode Phase (Token Generation)
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant Engine as InferenceEngine
-    participant Trans as Transformer
-    participant KV as KV Cache
-    participant Sample as Sampling
-
-    loop For each new token
-        User->>Engine: continue generation
-        Engine->>Trans: forward(next_token, prefill=false)
-        
-        loop For each layer
-            Trans->>Trans: RMSNorm
-            Trans->>Trans: QKV Projection (W8A16)
-            Trans->>Trans: RoPE
-            Trans->>KV: get_cache(layer)
-            Trans->>Trans: Attention Decode
-            Trans->>KV: append_kv(layer, k, v)
-            Trans->>Trans: Output Projection
-            Trans->>Trans: Residual
-        end
-        
-        Trans-->>Engine: logits
-        Engine->>Sample: sample(logits)
-        Sample-->>Engine: next_token
-    end
-    
-    Engine-->>User: full_output
-```
-
----
-
-## Memory Layout
-
-### Weight Storage
-
-```mermaid
-block-beta
-    columns 1
-    
-    block:Header["Model Weights"]
-        A["Token Embeddings<br/>FP16 [vocab, hidden]"]
-    end
-    
-    block:Layers["Layer Weights (×N)"]
-        B1["Attention<br/>INT8 q/k/v/o_proj"]
-        B2["FFN<br/>INT8 gate/up/down"]
-        B3["Scales<br/>FP16 per-group"]
-    end
-    
-    block:Output["Output"]
-        C["LM Head<br/>FP16 [hidden, vocab]"]
-    end
-```
-
-### Activation Buffers
-
-| Buffer | Shape | Dtype | Size (B=1, S=2048, H=4096) |
-|--------|-------|-------|---------------------------|
-| Hidden States | [B, S, H] | FP16 | 16 MB |
-| Attention Output | [B, heads, S, head_dim] | FP16 | 16 MB |
-| QKV | [B, S, 3×H] | FP16 | 48 MB |
-| FFN Intermediate | [B, S, intermediate_dim] | FP16 | 44 MB |
-
----
-
-## Performance Optimizations
-
-### Memory Optimizations
-
-| Technique | Implementation | Benefit |
-|-----------|----------------|---------|
-| W8A16 Quantization | Per-group INT8 weights + FP16 scales | 50% weight memory |
-| KV Cache Paging | Pre-allocated with sequence management | Efficient batching |
-| Activation Reuse | In-place operations | Reduced allocations |
+## Core Components
 
-### Compute Optimizations
+| Component | Responsibility |
+|-----------|----------------|
+| `InferenceEngine` | Public runtime entry point for loading supported binary models and generating token IDs |
+| `ModelLoader` | Host-side runtime weight loading for the supported binary format |
+| `GGUFParser` | GGUF parsing, metadata extraction, and tensor inspection |
+| `TransformerLayer` | W8A16 attention + FFN execution |
+| `KVCacheManager` | Pre-allocated cache slots and sequence lifecycle |
+| `Result<T>` | Fallible host-side API boundary |
 
-| Technique | Application | Speedup |
-|-----------|-------------|---------|
-| Tensor Cores | INT8 matmul on Ampere+ | 2-4× vs FP16 |
-| Warp Shuffle | Reductions | Eliminates shared memory |
-| Vectorized Loads | 128-bit memory access | Better bandwidth |
-| Kernel Fusion | RMSNorm+Resid, SiLU+Mul | Reduced kernel launch |
+## Loading Boundary
 
-### Optimized Kernel Performance
+- **Runtime loading:** `InferenceEngine::load("model.bin", config)`
+- **GGUF tooling:** `GGUFParser` for parse/inspect/validate workflows
+- **Not supported:** direct `.gguf` runtime loading through `InferenceEngine::load()`
 
-```mermaid
-xychart-beta
-    title "Kernel Throughput (7B Model, A100)"
-    x-axis ["w8a16_matmul", "attn_decode", "attn_prefill", "rmsnorm", "rope"]
-    y-axis "Throughput" 0-->100
-    bar [80, 65, 75, 95, 98]
-```
+## Generation Flow
 
----
+1. Load weights through the supported binary runtime path.
+2. Feed prompt token IDs into `generate()`.
+3. Run prefill across the Transformer stack.
+4. Reuse KV cache state during decode.
+5. Sample the next token ID from logits until EOS or `max_new_tokens`.
 
-## Design Principles
-
-```mermaid
-mindmap
-  root((Design Principles))
-    Modularity
-      Clear interfaces
-      Separation of concerns
-      Plugin architecture
-    Type Safety
-      Result&lt;T&gt; errors
-      Strong typing
-      No exceptions
-    RAII
-      Auto GPU memory
-      Stream management
-      Resource cleanup
-    Testability
-      Unit tests
-      Property-based
-      CUDA testing
-    Extensibility
-      New kernels
-      Sampling strategies
-      Model formats
-```
+## Notes
 
----
+- Public examples should use token IDs, not an in-repo tokenizer API.
+- Public docs should describe the binary runtime path and GGUF parser separately.
 
 ## Next Steps
 
-- [Quantization Details](./quantization) - Deep dive into W8A16 implementation
-- [KV Cache](./kv-cache) - Cache management strategies
-- [CUDA Kernels](./cuda-kernels) - Kernel optimization techniques
-- [API Reference](../api/inference-engine) - Complete API documentation
+- [Inference Engine](/en/architecture/inference-engine)
+- [API Reference](/en/api/)
+- [Performance Guide](/en/performance/)
diff --git a/docs/en/architecture/inference-engine.md b/docs/en/architecture/inference-engine.md
index 79777aa..2062d24 100644
--- a/docs/en/architecture/inference-engine.md
+++ b/docs/en/architecture/inference-engine.md
@@ -1,165 +1,51 @@
-# Architecture Overview
+# Inference Engine
 
-Tiny-LLM is designed with simplicity and educational value in mind while maintaining production-quality performance.
+`InferenceEngine` is the public runtime entry point for Tiny-LLM. It owns loaded runtime weights, creates the KV cache, builds the Transformer layer stack, and drives prefill/decode generation.
 
-## Core Components
-
-```
-┌─────────────────────────────────────────────────────┐
-│                  InferenceEngine                     │
-│                    (Public API)                      │
-├─────────────────────────────────────────────────────┤
-│                                                      │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
-│  │ ModelConfig │  │   Result\<T\> │  │  KVCache    │ │
-│  │             │  │             │  │  Manager    │ │
-│  └─────────────┘  └─────────────┘  └─────────────┘ │
-│                                                      │
-├─────────────────────────────────────────────────────┤
-│               TransformerLayer                       │
-│  ┌─────────────────┐    ┌─────────────────┐        │
-│  │  Attention      │    │      FFN        │        │
-│  │  (W8A16)        │    │    (W8A16)      │        │
-│  └─────────────────┘    └─────────────────┘        │
-├─────────────────────────────────────────────────────┤
-│               QuantizedWeight                        │
-│         (INT8 weights + per-group scales)           │
-├─────────────────────────────────────────────────────┤
-│                  CUDA Kernels                        │
-│   (Attention, FFN, Quantization, Memory Ops)        │
-└─────────────────────────────────────────────────────┘
-```
-
-## Component Responsibilities
-
-### InferenceEngine
-
-The public API that orchestrates model loading and generation:
-
-- `load()` - Load model weights from disk
-- `generate()` - Generate text from a prompt
-- `encode()` - Tokenize input text
-
-### Result\<T\>
-
-No-exception error propagation mechanism:
+## Public API
 
 ```cpp
-Result<void> result = engine.load("model.bin");
-if (!result.ok()) {
-    // Handle error
-    std::cerr << result.error() << std::endl;
-}
-```
+#include <tiny_llm/inference_engine.h>
 
-### ModelConfig
+namespace tiny_llm {
 
-Holds model hyperparameters:
+class InferenceEngine {
+public:
+    static Result<std::unique_ptr<InferenceEngine>> load(
+        const std::string& model_path,
+        const ModelConfig& config);
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `vocab_size` | `size_t` | Vocabulary size |
-| `hidden_dim` | `size_t` | Hidden dimension |
-| `num_layers` | `size_t` | Number of transformer layers |
-| `num_heads` | `size_t` | Number of attention heads |
-| `max_seq_len` | `size_t` | Maximum sequence length |
+    Result<std::vector<int>> generate(
+        const std::vector<int>& prompt_tokens,
+        const GenerationConfig& config);
 
-### QuantizedWeight
+    const GenerationStats& getStats() const;
+    void resetStats();
+};
 
-INT8 quantized weights with per-group scales:
-
-- Weights stored as INT8
-- Per-group scaling factors for dequantization
-- Supports W8A16 inference pattern
-
-### TransformerLayer
-
-Single transformer layer with:
-
-- Multi-head self-attention
-- Feed-forward network
-- Layer normalization
-- Residual connections
-
-### KVCacheManager
+} // namespace tiny_llm
+```
 
-Manages key-value cache for efficient generation:
+## Loading Boundary
 
-- Pre-allocated cache slots
-- Per-sequence cache management
-- Memory-efficient caching strategy
+- `InferenceEngine::load()` uses the supported **binary runtime format**.
+- `.gguf` paths are rejected by the runtime path with a structured error.
+- GGUF parsing and metadata extraction live on `GGUFParser`, not on the runtime fast path.
 
-## Memory Layout
+## Responsibilities
 
-```
-┌────────────────────────────────────────┐
-│           Weight Memory                │
-│  ┌──────────────────────────────────┐  │
-│  │   Embedding Table (FP16)         │  │
-│  └──────────────────────────────────┘  │
-│  ┌──────────────────────────────────┐  │
-│  │   Layer Weights (INT8 + Scales)  │  │
-│  │   ┌────────────────────────────┐ │  │
-│  │   │  Q, K, V Projections       │ │  │
-│  │   │  Output Projection         │ │  │
-│  │   │  FFN Up/Down Projections   │ │  │
-│  │   └────────────────────────────┘ │  │
-│  └──────────────────────────────────┘  │
-│  ┌──────────────────────────────────┐  │
-│  │   Output Layer (FP16)           │  │
-│  └──────────────────────────────────┘  │
-└────────────────────────────────────────┘
-```
+1. Validate `ModelConfig` before runtime setup.
+2. Load runtime weights through `ModelLoader::loadBin()`.
+3. Allocate the CUDA stream and reusable hidden/logit buffers.
+4. Create `KVCacheManager` and the `TransformerLayer` stack.
+5. Run prefill once, then decode token-by-token until EOS or the generation limit.
 
-## Data Flow
+## Inputs and Outputs
 
-```
-Input Text
-    │
-    ▼
-┌─────────────┐
-│  Tokenizer  │
-└─────────────┘
-    │
-    ▼
-Token IDs
-    │
-    ▼
-┌─────────────────┐
-│  Embedding      │  ← FP16 Lookup
-└─────────────────┘
-    │
-    ▼
-┌─────────────────────────────────────┐
-│         Transformer Layers          │
-│  ┌─────────────────────────────┐    │
-│  │     Self-Attention          │    │  ← W8A16 Quantized
-│  │  (Q×K^T / √d) → Softmax → V │    │
-│  └─────────────────────────────┘    │
-│              │                      │
-│              ▼                      │
-│  ┌─────────────────────────────┐    │
-│  │     Feed-Forward Network    │    │  ← W8A16 Quantized
-│  │     Linear → GELU → Linear  │    │
-│  └─────────────────────────────┘    │
-└─────────────────────────────────────┘
-    │
-    ▼
-┌─────────────────┐
-│  Output Layer   │  ← FP16 Logits
-└─────────────────┘
-    │
-    ▼
-┌─────────────────┐
-│   Sampling      │
-└─────────────────┘
-    │
-    ▼
-Output Tokens
-```
+- **Input:** prompt token IDs (`std::vector<int>`)
+- **Output:** generated token IDs via `Result<std::vector<int>>`
+- **Stats:** prefill time, decode time, throughput, and token counts
 
-## Next Steps
+## Failure Model
 
-- [Quantization Guide](/en/guide/quantization) - Learn about INT8 quantization
-- [Performance Guide](/en/performance/optimization) - Optimization techniques
-- [API Reference](/en/api/) - Detailed API documentation
+The runtime surface returns `Result<T>` errors for invalid config, unsupported runtime inputs, allocation failures, and generation validation failures. Callers should check `isErr()` before reading `value()`.
diff --git a/docs/en/changelog/index.md b/docs/en/changelog/index.md
deleted file mode 100644
index f60e368..0000000
--- a/docs/en/changelog/index.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# Changelog
-
-All notable changes to Tiny-LLM are documented here.
-
-## Versions
-
-| Version | Date | Summary |
-|---------|------|---------|
-| [v2.0.2](/en/changelog/v2.0.2) | 2024-01-15 | Bug fixes and stability improvements |
-| [v2.0.1](/en/changelog/v2.0.1) | 2024-01-08 | Performance optimizations |
-| [v2.0.0](/en/changelog/v2.0.0) | 2024-01-01 | Major release with INT8 quantization |
-
-## Versioning Scheme
-
-Tiny-LLM follows [Semantic Versioning](https://semver.org/):
-
-- **MAJOR**: Incompatible API changes
-- **MINOR**: Backward-compatible new features
-- **PATCH**: Backward-compatible bug fixes
-
-## Release Channels
-
-| Channel | Description |
-|---------|-------------|
-| `main` | Stable releases |
-| `develop` | Development builds |
-| `v*` tags | Version-specific releases |
diff --git a/docs/en/changelog/v2.0.0.md b/docs/en/changelog/v2.0.0.md
deleted file mode 100644
index e11b212..0000000
--- a/docs/en/changelog/v2.0.0.md
+++ /dev/null
@@ -1,148 +0,0 @@
-# v2.0.0
-
-Released: 2024-01-01
-
-We're excited to announce Tiny-LLM v2.0.0, a major release with INT8 quantization support!
-
-## Major Features
-
-### INT8 Quantization (W8A16)
-
-The headline feature of v2.0.0 is full support for INT8 weight quantization:
-
-- **50% memory reduction** for model weights
-- **2x faster inference** on memory-bound workloads
-- **Minimal accuracy loss** with per-group quantization
-
-```cpp
-// Load quantized model
-InferenceEngine engine;
-engine.load("model-int8.bin");
-
-// Generate as normal
-engine.generate("Hello, world!");
-```
-
-### New Architecture
-
-Completely rewritten core with modern C++17 design:
-
-- `Result\<T\>` for no-exception error handling
-- `KVCacheManager` for efficient generation
-- Modular `TransformerLayer` architecture
-
-### CUDA Optimizations
-
-- Fused attention kernels
-- Optimized INT8 matrix multiplication
-- Improved memory coalescing
-
-## Breaking Changes
-
-### API Changes
-
-The API has been redesigned for v2.0.0:
-
-| v1.x | v2.0.0 |
-|------|--------|
-| `loadModel()` | `load()` |
-| `generateText()` | `generate()` |
-| `getError()` | `result.error()` |
-
-### Configuration Changes
-
-Configuration is now struct-based:
-
-```cpp
-// Old (v1.x)
-engine.set("max_tokens", 100);
-
-// New (v2.0.0)
-GenerationConfig config;
-config.max_tokens = 100;
-engine.generate(prompt, config);
-```
-
-### Model Format
-
-v2.0.0 uses a new model format. Convert your models:
-
-```bash
-tinyllm-convert --input model-v1.bin --output model-v2.bin
-```
-
-## New Components
-
-### Result\<T\>
-
-No-exception error propagation:
-
-```cpp
-Result<std::string> result = engine.generate("Hello");
-if (!result.ok()) {
-    std::cerr << result.error_message() << std::endl;
-}
-```
-
-### KVCacheManager
-
-Efficient key-value caching:
-
-```cpp
-KVCacheManager cache;
-cache.initialize(model_config, cache_config);
-auto seq_id = cache.create_sequence();
-```
-
-## Performance
-
-### Benchmarks (LLaMA-7B on RTX 4090)
-
-| Metric | v1.x | v2.0.0 | Improvement |
-|--------|------|--------|-------------|
-| Memory (INT8) | 13 GB | 6.5 GB | 50% |
-| Prefill | 650 tok/s | 850 tok/s | 31% |
-| Decode | 48 tok/s | 65 tok/s | 35% |
-
-## Migration Guide
-
-### Step 1: Update Model Files
-
-```bash
-tinyllm-convert --input old-model.bin --output new-model.bin
-```
-
-### Step 2: Update Code
-
-```cpp
-// Old
-TinyLLM engine;
-engine.loadModel("model.bin");
-auto text = engine.generateText("Hello");
-
-// New
-InferenceEngine engine;
-engine.load("model.bin");
-auto result = engine.generate("Hello");
-if (result.ok()) {
-    std::cout << result.value() << std::endl;
-}
-```
-
-### Step 3: Update Build
-
-```bash
-# v2.0.0 requires C++17
-cmake -S . -B build -DCMAKE_CXX_STANDARD=17
-cmake --build build -j$(nproc)
-```
-
-## Known Issues
-
-- INT4 quantization not yet supported
-- Flash Attention requires CUDA 11.6+
-- Windows support is experimental
-
-## Contributors
-
-Special thanks to all contributors who made v2.0.0 possible!
diff --git a/docs/en/changelog/v2.0.1.md b/docs/en/changelog/v2.0.1.md
deleted file mode 100644
index 471250c..0000000
--- a/docs/en/changelog/v2.0.1.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# v2.0.1
-
-Released: 2024-01-08
-
-## New Features
-
-- Added support for grouped-query attention (GQA)
-- Added top-k sampling option
-- Added repetition penalty parameter
-
-## Performance Improvements
-
-- Optimized INT8 dequantization kernel (20% faster)
-- Reduced KV cache memory usage by 10%
-- Improved prompt processing speed for long contexts
-
-## Bug Fixes
-
-- Fixed incorrect output when temperature is 0.0 (greedy decoding)
-- Fixed tokenizer handling of Unicode characters
-- Fixed CUDA graph capture issue on multi-GPU systems
-
-## API Changes
-
-### New Parameters
-
-```cpp
-GenerationConfig config;
-config.top_k = 50;  // New: Top-K sampling
-config.repetition_penalty = 1.1f;  // New: Repetition penalty
-```
-
-### ModelConfig Extensions
-
-```cpp
-ModelConfig config;
-config.num_kv_heads = 8;  // New: For GQA support
-```
-
-## Known Issues
-
-- Flash Attention may produce incorrect results with sequence lengths > 4096
-- Windows build may require manual CUDA path configuration
-
-## Contributors
-
-Thanks to all contributors who made this release possible!
diff --git a/docs/en/changelog/v2.0.2.md b/docs/en/changelog/v2.0.2.md
deleted file mode 100644
index cbb5d9e..0000000
--- a/docs/en/changelog/v2.0.2.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# v2.0.2
-
-Released: 2024-01-15
-
-## Bug Fixes
-
-### Critical Fixes
-
-- Fixed memory leak in KV cache when destroying sequences
-- Fixed incorrect tokenization for special characters
-- Fixed CUDA kernel crash on Ampere GPUs with specific sequence lengths
-
-### Minor Fixes
-
-- Fixed incorrect error message when model file is corrupted
-- Fixed race condition in multi-threaded inference
-- Fixed incorrect RMS normalization epsilon value
-
-## Improvements
-
-### Performance
-
-- Reduced memory allocation overhead by 15%
-- Improved token generation speed by 5-8% on RTX 40-series GPUs
-
-### Documentation
-
-- Added troubleshooting guide for common issues
-- Updated API reference with more examples
-- Added performance benchmarks for LLaMA-7B
-
-## Compatibility
-
-- Minimum CUDA version: 11.0 (unchanged)
-- Tested on: Ubuntu 20.04/22.04, Windows 10/11
-- GPU compatibility: Volta (SM70) and newer
-
-## Migration Guide
-
-No breaking changes from v2.0.1. Simply rebuild:
-
-```bash
-git pull origin main
-cmake --build build -j$(nproc)
-```
-
-## Contributors
-
-Thanks to all contributors who made this release possible!
diff --git a/docs/en/guide/quickstart.md b/docs/en/guide/quickstart.md
index 0b4eee8..205df36 100644
--- a/docs/en/guide/quickstart.md
+++ b/docs/en/guide/quickstart.md
@@ -1,80 +1,52 @@
 # Quick Start
 
-This tutorial will guide you through your first inference with Tiny-LLM.
+This page shows the smallest end-to-end runtime path that matches the current codebase.
 
-## Prerequisites
-
-Make sure you have [installed Tiny-LLM](/en/guide/installation) first.
-
-## Basic Usage
-
-### 1. Loading a Model
+## 1. Load a supported runtime model
 
 ```cpp
-#include <tiny-llm/inference_engine.h>
-
-using namespace tinyllm;
+#include <iostream>
+#include <tiny_llm/inference_engine.h>
 
 int main() {
-    // Create the inference engine
-    InferenceEngine engine;
+    using namespace tiny_llm;
 
-    // Load model from file
-    Result<void> result = engine.load("model.bin");
-    if (!result.ok()) {
-        std::cerr << "Failed to load model: " << result.error() << std::endl;
+    ModelConfig config;
+    auto engine_result = InferenceEngine::load("model.bin", config);
+    if (engine_result.isErr()) {
+        std::cerr << engine_result.error() << '\n';
         return 1;
     }
-
-    return 0;
 }
 ```
 
-### 2. Running Inference
+## 2. Generate token IDs
 
 ```cpp
-#include <tiny-llm/inference_engine.h>
-#include <iostream>
-
-int main() {
-    InferenceEngine engine;
-    engine.load("model.bin");
+using namespace tiny_llm;
 
-    // Generate text from prompt
-    std::string prompt = "The future of AI is";
-    Result<std::string> result = engine.generate(prompt, /*max_tokens=*/50);
+auto engine = std::move(engine_result.value());
 
-    if (result.ok()) {
-        std::cout << "Generated: " << result.value() << std::endl;
-    } else {
-        std::cerr << "Error: " << result.error() << std::endl;
-    }
+GenerationConfig generation;
+generation.max_new_tokens = 32;
+generation.do_sample = true;
+generation.temperature = 0.7f;
 
-    return 0;
+auto output = engine->generate({1, 15043, 29892}, generation);
+if (output.isErr()) {
+    std::cerr << output.error() << '\n';
+    return 1;
 }
 ```
 
-### 3. Configuration Options
-
-```cpp
-GenerationConfig config;
-config.max_tokens = 100;
-config.temperature = 0.7f;
-config.top_p = 0.9f;
-config.top_k = 50;
-
-Result<std::string> result = engine.generate(prompt, config);
-```
-
-## Building Your Application
+## 3. Know the boundary
 
-```bash
-# Compile your application
-g++ -std=c++17 my_app.cpp -o my_app -I/path/to/tiny-llm/include -L/path/to/tiny-llm/build -ltinyllm
-```
+- `InferenceEngine::load()` uses the supported binary runtime format.
+- `GGUFParser` is the entry point for GGUF parsing and inspection.
+- The public runtime API works on token IDs, not raw strings.
 
 ## Next Steps
 
-- [Architecture Overview](/en/architecture/inference-engine) - Learn about the internals
-- [Configuration Guide](/en/guide/configuration) - Detailed configuration options
-- [API Reference](/en/api/) - Complete API documentation
+- [Architecture Overview](/en/architecture/)
+- [API Reference](/en/api/)
+- [Installation](/en/guide/installation)
diff --git a/docs/en/guide/troubleshooting.md b/docs/en/guide/troubleshooting.md
index 0ce4620..d26dc50 100644
--- a/docs/en/guide/troubleshooting.md
+++ b/docs/en/guide/troubleshooting.md
@@ -232,5 +232,5 @@ When reporting issues, please provide:
 ### Resources
 
 - [GitHub Issues](https://github.com/AICL-Lab/tiny-llm/issues)
-- [Documentation](https://lessup.github.io/tiny-llm/)
-- [API Reference](https://lessup.github.io/tiny-llm/docs/en/API)
+- [Documentation](https://aicl-lab.github.io/tiny-llm/)
+- [API Reference](https://aicl-lab.github.io/tiny-llm/en/api/)
diff --git a/docs/en/index.md b/docs/en/index.md
index 5fabe65..efd79b6 100644
--- a/docs/en/index.md
+++ b/docs/en/index.md
@@ -3,98 +3,72 @@ layout: home
 
 hero:
   name: "Tiny-LLM"
-  text: "Technical Whitepaper"
-  tagline: CUDA-native inference engine with W8A16 quantization
+  text: "CUDA-Native Inference Engine"
+  tagline: Focused Transformer inference with W8A16 kernels, explicit KV cache management, and a smaller-maintenance repository.
   image:
     src: /images/logo.svg
     alt: Tiny-LLM Logo
   actions:
     - theme: brand
-      text: Architecture
-      link: /en/architecture/
+      text: Get Started
+      link: /en/guide/getting-started
     - theme: alt
-      text: Performance
-      link: /en/performance/
+      text: API Reference
+      link: /en/api/
 
 features:
   - icon: "⚡"
-    title: W8A16 Quantization
-    details: INT8 weights with FP16 activations — 50% memory reduction with <1% accuracy loss
-  - icon: "🔧"
-    title: CUDA-Native Kernels
-    details: Tensor Core INT8 matmul, optimized attention decode, warp-level primitives
+    title: W8A16 Inference
+    details: INT8 weights with FP16 activations for a compact CUDA runtime path.
   - icon: "📦"
-    title: KV Cache Manager
-    details: Pre-allocated slots, O(1) incremental decoding, sequence lifecycle management
+    title: Binary Runtime Path
+    details: "`InferenceEngine::load()` targets the supported binary runtime format used by the current engine."
+  - icon: "🔎"
+    title: GGUF Parsing Utilities
+    details: GGUF parsing, metadata extraction, and tensor inspection remain available without pretending to be the runtime path.
+  - icon: "🧠"
+    title: Explicit KV Cache
+    details: Pre-allocated sequence slots keep autoregressive decoding predictable.
   - icon: "🛡️"
-    title: Result<T> Pattern
-    details: No-exception error propagation for predictable control flow and safe resource handling
-  - icon: "📊"
-    title: OpenSpec Governance
-    details: Requirements-driven development with automated test coverage validation
+    title: "Result<T> APIs"
+    details: Host-side failures stay explicit and inspectable.
   - icon: "🧪"
-    title: Property-Based Testing
-    details: RapidCheck integration for invariant verification across input spaces
+    title: Tested Core
+    details: GoogleTest and RapidCheck cover the core loader, cache, and generation surfaces.
 ---
 
-## Key Results
+## Runtime Surfaces
 
-| Metric | Value | vs FP16 |
-|--------|-------|---------|
-| **Memory** | 7.8 GB | **50% ↓** |
-| **Decode** | 85 tok/s | **9% ↑** |
-| **Accuracy** | 9.12 ppl | 0.4% Δ |
+| Surface | Status | Notes |
+|---------|--------|-------|
+| Binary runtime loading | Supported | Used by `InferenceEngine::load()` |
+| GGUF parsing and inspection | Supported | Use `GGUFParser` for metadata and tensor access |
+| Direct GGUF runtime loading | Not supported | `.gguf` paths are rejected by the runtime loader |
 
-*Benchmarks: LLaMA-7B, RTX 4090, INT8 weights*
-
-## Architecture
+## Architecture Sketch
 
 ```mermaid
 flowchart LR
-    A[Model File] --> B[GGUF Parser]
-    B --> C[InferenceEngine]
-    C --> D[Transformer Layers]
-    D --> E[KV Cache]
-    D --> F[W8A16 Matmul]
-    F --> G[Sampling]
-    G --> H[Output Tokens]
-
-    style C fill:#00D4AA,stroke:#00C49A,color:#fff
-    style F fill:#76B900,stroke:#5a8f00,color:#fff
+    A[Binary runtime model] --> B[InferenceEngine::load()]
+    C[GGUF file] --> D[GGUFParser]
+    B --> E[Transformer Layers]
+    E --> F[KV Cache]
+    E --> G[W8A16 MatMul]
+    G --> H[Sampling]
+    H --> I[Output Tokens]
+    D --> J[Metadata / Tensor Inspection]
+
+    style B fill:#00D4AA,stroke:#00C49A,color:#fff
+    style G fill:#76B900,stroke:#5a8f00,color:#fff
+    style D fill:#8B5CF6,stroke:#7c3aed,color:#fff
 ```
 
-## Quick Start
-
-```bash
-# Clone
-git clone https://github.com/AICL-Lab/tiny-llm.git
-cd tiny-llm
-
-# Build (requires CUDA 11.0+)
-cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
-cmake --build build -j$(nproc)
-
-# Test
-ctest --test-dir build --output-on-failure
-```
-
-## Documentation
-
-| Resource | Description |
-|----------|-------------|
-| [Architecture Overview](/en/architecture/) | System design and data flow |
-| [W8A16 Quantization](/en/architecture/quantization) | Quantization scheme details |
-| [CUDA Kernels](/en/architecture/cuda-kernels) | Kernel optimization techniques |
-| [Performance](/en/performance/) | Benchmarks and profiling guides |
-| [API Reference](/en/api/) | Complete API documentation |
-
-## Core Components
+## Start Here
 
-| Component | Responsibility |
-|-----------|----------------|
-| `Result<T>` | No-exception error propagation |
-| `ModelConfig` | Model hyperparameters (vocab_size, hidden_dim, etc.) |
-| `QuantizedWeight` | INT8 weights with per-group scales |
-| `TransformerLayer` | W8A16 quantized attention + FFN |
-| `KVCacheManager` | Pre-allocated cache slots for sequences |
-| `InferenceEngine` | Public API: load(), generate() |
+| Resource | Why it matters |
+|----------|----------------|
+| [Getting Started](/en/guide/getting-started) | Minimal build and first-run path |
+| [Architecture](/en/architecture/) | Runtime structure and responsibilities |
+| [API Reference](/en/api/) | Public headers and types |
+| [Performance](/en/performance/) | Benchmarks and optimization notes |
+| [GitHub Repository](https://github.com/AICL-Lab/tiny-llm) | Source, issues, and releases |
diff --git a/docs/index.md b/docs/index.md
index 4ed0bd8..cad5755 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,8 +3,8 @@ layout: home
 
 hero:
   name: "Tiny-LLM"
-  text: "Educational CUDA LLM Inference"
-  tagline: A minimal, educational LLM inference engine in CUDA C++ with INT8 quantization
+  text: "CUDA C++ Inference, Kept Small"
+  tagline: Focused Transformer inference engine with W8A16 kernels, explicit KV cache management, and a deliberately small repository surface.
   image:
     src: /images/logo.svg
     alt: Tiny-LLM Logo
@@ -17,37 +17,22 @@ hero:
       link: https://github.com/AICL-Lab/tiny-llm
 
 features:
-  - icon: "\U0001F680"
-    title: High Performance
-    details: Optimized CUDA kernels for attention, FFN, and quantized inference with W8A16 quantization
-  - icon: "\U0001F4DA"
-    title: Educational
-    details: Clean, well-documented codebase designed for learning LLM inference internals
-  - icon: "\U0001F4CA"
-    title: INT8 Quantization
-    details: Per-group INT8 quantization for memory efficiency with minimal accuracy loss
-  - icon: "\U0001F512"
-    title: No-Exception Design
-    details: Result\<T\> based error propagation for predictable and safe error handling
-  - icon: "\U0001F9E0"
-    title: KV Cache
-    details: Pre-allocated KV cache manager for efficient autoregressive generation
-  - icon: "\U0001F310"
-    details: Cross-platform support with CMake build system for Linux and Windows
+  - icon: "⚡"
+    title: W8A16 Runtime
+    details: INT8 weights with FP16 activations for a compact CUDA inference path.
+  - icon: "📦"
+    title: Narrow Loading Surface
+    details: Runtime loading stays on the supported binary path, while GGUF parsing remains available for inspection and validation.
+  - icon: "🧠"
+    title: Explicit KV Cache
+    details: Pre-allocated sequence slots keep autoregressive decoding predictable.
+  - icon: "🛡️"
+    title: "Result<T> APIs"
+    details: Host-side fallible operations return explicit results instead of hiding failures.
+  - icon: "🧪"
+    title: Tested Core
+    details: GoogleTest and RapidCheck cover the core loader, cache, and generation paths.
+  - icon: "📚"
+    title: Focused Docs
+    details: Pages documents the engine itself instead of duplicating process and changelog scaffolding.
 ---
-
-<style>
-/* Custom home page styles */
-.VPHero .name {
-  background: linear-gradient(135deg, #00D4AA 0%, #76B900 100%);
-  -webkit-background-clip: text;
-  background-clip: text;
-  -webkit-text-fill-color: transparent;
-}
-
-.VPHero .image-bg {
-  background: linear-gradient(135deg, #00D4AA, #76B900);
-  opacity: 0.2;
-  filter: blur(100px);
-}
-</style>
diff --git a/docs/zh/api/index.md b/docs/zh/api/index.md
index 19a2f6f..528908e 100644
--- a/docs/zh/api/index.md
+++ b/docs/zh/api/index.md
@@ -1,81 +1,52 @@
 # API 参考
 
-欢迎使用 Tiny-LLM API 参考文档。
+Tiny-LLM 在 `tiny_llm` 命名空间下暴露了一套很紧凑的公共 C++ 接口。
 
-## 核心组件
+## 主要头文件
 
-| 组件 | 描述 |
-|------|------|
-| [InferenceEngine](/zh/api/inference-engine) | 主推理引擎类 |
-| [ModelConfig](/zh/api/model-config) | 模型超参数 |
-| [Result\<T\>](/zh/api/result) | 错误处理包装器 |
-| [KVCacheManager](/zh/api/kv-cache) | 键值缓存管理 |
+| 头文件 | 用途 |
+|--------|------|
+| `<tiny_llm/inference_engine.h>` | 运行时加载与 token 生成 |
+| `<tiny_llm/model_loader.h>` | 宿主侧运行时模型加载辅助 |
+| `<tiny_llm/gguf_parser.h>` | GGUF 解析、元数据提取、tensor 检查 |
+| `<tiny_llm/kv_cache.h>` | KV cache 分配与序列管理 |
+| `<tiny_llm/result.h>` | `Result<T>` 错误传播 |
+| `<tiny_llm/types.h>` | 共享配置、权重与统计类型 |
 
 ## 快速示例
 
 ```cpp
-#include <tiny-llm/inference_engine.h>
-#include <tiny-llm/model_config.h>
-#include <tiny-llm/result.h>
-
-using namespace tinyllm;
+#include <iostream>
+#include <tiny_llm/inference_engine.h>
 
 int main() {
-    // 创建引擎
-    InferenceEngine engine;
+    using namespace tiny_llm;
 
-    // 加载模型
-    Result<void> load_result = engine.load("model.bin");
-    if (!load_result.ok()) {
-        std::cerr << "错误: " << load_result.error() << std::endl;
+    ModelConfig config;
+    auto engine_result = InferenceEngine::load("model.bin", config);
+    if (engine_result.isErr()) {
+        std::cerr << engine_result.error() << '\n';
         return 1;
     }
 
-    // 生成文本
-    GenerationConfig config;
-    config.max_tokens = 100;
-    config.temperature = 0.7f;
-
-    Result<std::string> result = engine.generate("你好，世界！", config);
-    if (result.ok()) {
-        std::cout << result.value() << std::endl;
+    auto engine = std::move(engine_result.value());
+    auto output = engine->generate({1, 15043, 29892}, GenerationConfig{});
+    if (output.isErr()) {
+        std::cerr << output.error() << '\n';
+        return 1;
     }
-
-    return 0;
 }
 ```
 
-## 错误处理
+## 加载边界
 
-所有操作返回 `Result\<T\>` 进行安全的错误传播：
+- 用 `InferenceEngine::load()` 加载支持的二进制运行时格式。
+- 需要 GGUF 解析或元数据访问时使用 `GGUFParser`。
+- 不要假设公共接口里存在 tokenizer 或“输入字符串直接生成字符串”的 API。
 
-```cpp
-Result\<T\> result = some_operation();
-if (!result.ok()) {
-    // 处理错误
-    std::cerr << result.error() << std::endl;
-} else {
-    // 使用结果
-    T value = result.value();
-}
-```
+## 参考页面
 
-## 命名空间
-
-所有公共 API 都在 `tinyllm` 命名空间中：
-
-```cpp
-using namespace tinyllm;
-// 或
-tinyllm::InferenceEngine engine;
-```
-
-## 头文件
-
-| 头文件 | 描述 |
-|--------|------|
-| `<tiny-llm/inference_engine.h>` | 主引擎类 |
-| `<tiny-llm/model_config.h>` | 配置结构体 |
-| `<tiny-llm/result.h>` | Result 类型 |
-| `<tiny-llm/kv_cache.h>` | 缓存管理 |
-| `<tiny-llm/tokenizer.h>` | 分词工具 |
+- [InferenceEngine](/zh/api/inference-engine)
+- [Result&lt;T&gt;](/zh/api/result)
+- [KVCacheManager](/zh/api/kv-cache)
+- [ModelConfig](/zh/api/model-config)
diff --git a/docs/zh/api/inference-engine.md b/docs/zh/api/inference-engine.md
index 232afe5..3a761e5 100644
--- a/docs/zh/api/inference-engine.md
+++ b/docs/zh/api/inference-engine.md
@@ -1,666 +1,94 @@
 ---
 layout: doc
-title: "API 参考 — Tiny-LLM"
-description: "Tiny-LLM 推理引擎完整 API 参考"
+title: "InferenceEngine API"
+description: "Tiny-LLM 的公开运行时 API"
 ---
 
-# API 参考
+# InferenceEngine API
 
-Tiny-LLM 推理引擎的完整 API 参考文档。
-
----
-
-## 目录
-
-- [数据类型](#数据类型)
-- [核心类](#核心类)
-- [CUDA Kernel](#cuda-kernel)
-- [错误处理](#错误处理)
-- [工具类](#工具类)
-
----
-
-## 数据类型
-
-### ModelConfig
-
-模型配置结构体，定义所有超参数。
+## 类概览
 
 ```cpp
 #include <tiny_llm/inference_engine.h>
 
-struct ModelConfig {
-    int vocab_size = 32000;           // 词表大小
-    int hidden_dim = 4096;            // 隐藏层维度
-    int num_layers = 32;              // Transformer 层数
-    int num_heads = 32;               // 注意力头数
-    int num_kv_heads = 32;            // KV 头数 (支持 GQA)
-    int head_dim = 128;               // 每头维度
-    int intermediate_dim = 11008;     // FFN 中间层维度
-    int max_seq_len = 2048;           // 最大序列长度
-    float rope_theta = 10000.0f;      // RoPE 基频
-    float rms_norm_eps = 1e-5f;       // RMSNorm epsilon
-    int eos_token_id = 2;             // 结束符 token ID
-    int bos_token_id = 1;             // 起始符 token ID
-};
-```
-
-**常见配置**:
-
-| 模型大小 | hidden_dim | num_layers | num_heads | intermediate_dim |
-|------------|------------|------------|-----------|------------------|
-| 7B | 4096 | 32 | 32 | 11008 |
-| 13B | 5120 | 40 | 40 | 13824 |
-| 70B | 8192 | 80 | 64 | 28672 |
-
-### GenerationConfig
-
-文本生成配置，控制采样行为。
-
-```cpp
-struct GenerationConfig {
-    int max_new_tokens = 256;         // 最大生成 token 数
-    float temperature = 1.0f;         // 采样温度
-    int top_k = 50;                   // Top-k 采样截断
-    float top_p = 0.9f;               // Top-p (核) 采样阈值
-    bool do_sample = false;           // 启用采样 (false = 贪婪)
-    float repetition_penalty = 1.0f;  // 重复 token 惩罚
-};
-```
-
-**采样参数**:
-
-| 参数 | 范围 | 效果 |
-|-----------|-------|--------|
-| `temperature` | 0.0 - 2.0 | 越低越确定 |
-| `top_k` | 1 - vocab_size | 只考虑概率最高的 k 个 token |
-| `top_p` | 0.0 - 1.0 | 从累积概率达到 p 的 token 中采样 |
-| `repetition_penalty` | 1.0 - 2.0 | >1.0 惩罚重复 token |
-
-### QuantizedWeight
-
-INT8 量化权重，带 FP16 缩放因子。
-
-```cpp
-struct QuantizedWeight {
-    int8_t* data;                     // INT8 权重 [rows, cols]
-    half* scales;                     // FP16 缩放 [rows/group_size, cols]
-    int rows;                         // 输入维度
-    int cols;                         // 输出维度
-    int group_size = 128;             // 量化组大小
-
-    // 辅助方法
-    int scaleRows() const;            // ceil(rows / group_size)
-    int scaleCols() const;            // cols
-    size_t weightElements() const;    // rows * cols
-    size_t scaleElements() const;     // scaleRows() * cols
-    size_t weightBytes() const;       // weightElements()
-    size_t scaleBytes() const;        // scaleElements() * 2
-    size_t totalBytes() const;        // weightBytes + scaleBytes
-    bool isValid() const;             // 验证维度
-};
-```
-
-### GenerationStats
-
-文本生成的性能统计。
-
-```cpp
-struct GenerationStats {
-    float prefill_time_ms = 0.0f;     // Prefill 阶段时间 (ms)
-    float decode_time_ms = 0.0f;      // Decode 阶段时间 (ms)
-    int prompt_tokens = 0;            // Prompt token 数
-    int tokens_generated = 0;         // 生成 token 数
-    float tokens_per_second = 0.0f;   // 生成吞吐
-    size_t peak_memory_bytes = 0;     // 峰值 GPU 显存使用
-};
-```
-
----
-
-## 核心类
-
-### InferenceEngine
-
-主推理引擎类。对不同引擎实例的并发生成是线程安全的。
-
-```cpp
-#include <tiny_llm/inference_engine.h>
+namespace tiny_llm {
 
 class InferenceEngine {
 public:
-    // 从自定义二进制格式加载模型
-    static Result\<std::unique_ptr\<InferenceEngine\>\> load(
+    static Result<std::unique_ptr<InferenceEngine>> load(
         const std::string& model_path,
-        const ModelConfig& config
-    );
+        const ModelConfig& config);
 
-    // 为 prompt 生成补全
-    std::vector<int> generate(
+    Result<std::vector<int>> generate(
         const std::vector<int>& prompt_tokens,
-        const GenerationConfig& gen_config
-    );
+        const GenerationConfig& config);
 
-    // 获取生成统计
     const GenerationStats& getStats() const;
     void resetStats();
 
-    // 独立采样函数（无状态）
-    static int sampleGreedy(
-        const half* logits, int vocab_size);
-
-    static int sampleTemperature(
-        const half* logits, int vocab_size,
-        float temperature, unsigned seed = 0);
-
-    static int sampleTopK(
-        const half* logits, int vocab_size,
-        int k, float temperature, unsigned seed = 0);
-
-    static int sampleTopP(
-        const half* logits, int vocab_size,
-        float p, float temperature, unsigned seed = 0);
+    static int sampleGreedy(const half* logits, int vocab_size);
+    static int sampleTemperature(const half* logits, int vocab_size, float temperature,
+                                 unsigned seed = 0);
+    static int sampleTopK(const half* logits, int vocab_size, int k, float temperature,
+                          unsigned seed = 0);
+    static int sampleTopP(const half* logits, int vocab_size, float p, float temperature,
+                          unsigned seed = 0);
 };
-```
-
-**使用示例**:
-
-```cpp
-// 配置模型
-ModelConfig config;
-config.vocab_size = 32000;
-config.hidden_dim = 4096;
-config.num_layers = 32;
-
-// 加载模型
-auto result = InferenceEngine::load("model.bin", config);
-if (result.isErr()) {
-    std::cerr << "Error: " << result.error() << std::endl;
-    return 1;
-}
-auto engine = std::move(result.value());
-
-// 配置生成
-GenerationConfig gen_config;
-gen_config.max_new_tokens = 256;
-gen_config.temperature = 0.7f;
-gen_config.top_p = 0.9f;
-gen_config.do_sample = true;
-
-// 生成
-std::vector<int> prompt = {1, 15043, 29892};  // "Hello,"
-auto output = engine->generate(prompt, gen_config);
-
-// 查看性能
-const auto& stats = engine->getStats();
-std::cout << "速度: " << stats.tokens_per_second << " tok/s" << std::endl;
-```
-
-### KVCacheManager
-
-用于自回归生成的高效键值缓存管理。
-
-```cpp
-#include <tiny_llm/kv_cache.h>
-
-struct KVCacheConfig {
-    int num_layers = 32;              // Transformer 层数
-    int num_heads = 32;               // KV 头数
-    int head_dim = 128;               // 每头维度
-    int max_seq_len = 2048;           // 最大序列长度
-    int max_batch_size = 1;           // 最大 batch 大小
-};
-
-class KVCacheManager {
-public:
-    explicit KVCacheManager(const KVCacheConfig& config);
-    ~KVCacheManager();
-
-    // 序列管理
-    Result\<int\> allocateSequence(int max_len);
-    void releaseSequence(int seq_id);
-    bool hasSequence(int seq_id) const;
-
-    // 获取用于注意力计算的缓存
-    std::pair<half*, half*> getCache(int seq_id, int layer_idx);
-    int getSeqLen(int seq_id) const;
-
-    // 追加 KV（只写，无状态）
-    void appendKV(int seq_id, int layer_idx,
-                  const half* new_k, const half* new_v,
-                  int num_tokens, cudaStream_t stream = 0);
-
-    // 所有层完成后推进序列长度
-    void advanceSeqLen(int seq_id, int num_tokens);
-
-    // 显存统计
-    size_t getUsedMemory() const;
-    size_t getTotalMemory() const;
-    size_t getFreeMemory() const;
-    int getActiveSequenceCount() const;
-};
-```
-
-**使用模式**:
-
-```cpp
-KVCacheConfig cache_config;
-cache_config.num_layers = 32;
-cache_config.num_heads = 32;
-cache_config.head_dim = 128;
-cache_config.max_seq_len = 2048;
-
-// 使用工厂方法进行正确的错误处理
-auto cache_result = KVCacheManager::create(cache_config);
-if (cache_result.isErr()) {
-    // 处理创建失败
-}
-auto kv_cache = std::move(cache_result.value());
-
-// 分配序列
-auto seq_result = kv_cache->allocateSequence(1024);
-if (seq_result.isErr()) {
-    // 处理分配失败
-}
-int seq_id = seq_result.value();
-
-// 前向传播各层
-for (int i = 0; i < num_layers; i++) {
-    layers[i]->forward(hidden_states, *kv_cache, seq_id, position, stream);
-}
-
-// 所有层完成后推进序列长度
-kv_cache->advanceSeqLen(seq_id, 1);
-
-// 完成后释放
-kv_cache->releaseSequence(seq_id);
-```
-
-### TransformerLayer
-
-带注意力和 FFN 的单个 Transformer 层。
-
-```cpp
-#include <tiny_llm/transformer.h>
-
-class TransformerLayer {
-public:
-    TransformerLayer(int layer_idx,
-                     const TransformerWeights& weights,
-                     const ModelConfig& config);
-
-    // 单 token 前向 (decode 阶段)
-    void forward(half* hidden_states,
-                 KVCacheManager& kv_cache,
-                 int seq_id,
-                 int position,
-                 cudaStream_t stream = 0);
-
-    // 多 token 前向 (prefill 阶段)
-    void forwardPrefill(half* hidden_states,
-                        KVCacheManager& kv_cache,
-                        int seq_id,
-                        int seq_len,
-                        cudaStream_t stream = 0);
-
-    int getLayerIdx() const;
-};
-```
-
----
-
-## CUDA Kernel
-
-### W8A16 矩阵乘法
-
-```cpp
-#include <w8a16_matmul.cuh>
-
-namespace tiny_llm::kernels {
-
-// 主 W8A16 矩阵乘 kernel
-void w8a16_matmul(
-    const half* input,           // [M, K] FP16
-    const int8_t* weight,        // [K, N] INT8 (列主序)
-    const half* scales,          // [K/group_size, N] FP16
-    half* output,                // [M, N] FP16
-    int M,                       // Batch 大小
-    int N,                       // 输出维度
-    int K,                       // 输入维度
-    int group_size,              // 量化组大小
-    cudaStream_t stream = 0
-);
 
-// 权重反量化（用于测试/参考）
-void dequantize_weights(
-    const int8_t* weight_int8,
-    const half* scales,
-    half* weight_fp16,
-    int K, int N,
-    int group_size,
-    cudaStream_t stream = 0
-);
-
-// 参考实现，用于验证
-void w8a16_matmul_reference(
-    const half* input,
-    const int8_t* weight,
-    const half* scales,
-    half* output,
-    int M, int N, int K,
-    int group_size
-);
-
-}
-```
-
-### Attention Kernel
-
-```cpp
-#include <attention.cuh>
-
-namespace tiny_llm::kernels {
-
-// Decode: 单 query token 对缓存的 KV
-void attention_decode(
-    const half* query,           // [batch, num_heads, 1, head_dim]
-    const half* k_cache,         // [batch, num_heads, seq_len, head_dim]
-    const half* v_cache,         // [batch, num_heads, seq_len, head_dim]
-    half* output,                // [batch, num_heads, 1, head_dim]
-    float scale,                 // 1/sqrt(head_dim)
-    int batch_size,
-    int num_heads,
-    int seq_len,
-    int head_dim,
-    cudaStream_t stream = 0
-);
-
-// Prefill: 多 token 带因果掩码
-void attention_prefill(
-    const half* query,           // [batch, num_heads, seq_len, head_dim]
-    const half* key,             // [batch, num_heads, seq_len, head_dim]
-    const half* value,           // [batch, num_heads, seq_len, head_dim]
-    half* output,                // [batch, num_heads, seq_len, head_dim]
-    float scale,
-    int batch_size,
-    int num_heads,
-    int seq_len,
-    int head_dim,
-    cudaStream_t stream = 0
-);
-
-// 独立 softmax
-void softmax(
-    const half* input,           // [batch, seq_len]
-    half* output,
-    int batch_size,
-    int seq_len,
-    cudaStream_t stream = 0
-);
-
-}
+} // namespace tiny_llm
 ```
 
-### RMSNorm
+## 运行时加载
 
-```cpp
-#include <rmsnorm.cuh>
-
-namespace tiny_llm::kernels {
-
-// RMSNorm: output = x / sqrt(mean(x^2) + eps) * weight
-void rmsnorm(
-    const half* input,           // [batch, hidden_dim]
-    const half* weight,          // [hidden_dim]
-    half* output,                // [batch, hidden_dim]
-    int batch_size,
-    int hidden_dim,
-    float eps = 1e-5f,
-    cudaStream_t stream = 0
-);
-
-// 原地 RMSNorm
-void rmsnorm_inplace(
-    half* x,                     // [batch, hidden_dim] (原地)
-    const half* weight,
-    int batch_size,
-    int hidden_dim,
-    float eps = 1e-5f,
-    cudaStream_t stream = 0
-);
-
-}
-```
+- `load("model.bin", config)` 面向支持的二进制运行时格式。
+- 传入 `.gguf` 路径会返回结构化错误，说明当前不支持直接 GGUF 运行时加载。
+- GGUF 的解析与检查能力由 `GGUFParser` 提供。
 
-### 逐元素操作
+## 使用示例
 
 ```cpp
-#include <elementwise.cuh>
-
-namespace tiny_llm::kernels {
-
-// 原地加法: data[i] += add[i]
-void add_inplace(
-    half* data,
-    const half* add,
-    int num_elements,
-    cudaStream_t stream = 0
-);
-
-// 融合 SwiGLU: gate[i] = silu(gate[i]) * up[i]
-void silu_mul_inplace(
-    half* gate,
-    const half* up,
-    int num_elements,
-    cudaStream_t stream = 0
-);
-
-// Embedding 查找
-void gather_embeddings(
-    const int* tokens,           // [num_tokens]
-    const half* embedding,       // [vocab_size, hidden_dim]
-    half* output,                // [num_tokens, hidden_dim]
-    int num_tokens,
-    int hidden_dim,
-    int vocab_size,
-    cudaStream_t stream = 0
-);
-
-}
-```
-
----
-
-## 错误处理
-
-### Result\<T\>
-
-受 Rust 启发的 Result 类型，无需异常的错误处理。
-
-```cpp
-#include <tiny_llm/result.h>
-
-template\<typename T\>
-class Result {
-public:
-    // 构造函数
-    static Result\<T\> ok(T value);
-    static Result\<T\> err(std::string message);
-
-    // 状态检查
-    bool isOk() const;
-    bool isErr() const;
-
-    // 获取值（error 时抛出）
-    T& value();
-    const T& value() const;
-    T valueOr(T default_value) const;
+#include <iostream>
+#include <tiny_llm/inference_engine.h>
 
-    // 获取错误（ok 时抛出）
-    const std::string& error() const;
+int main() {
+    using namespace tiny_llm;
 
-    // Monadic 操作
-    template\<typename F\>
-    auto map(F&& f) -> Result<decltype(f(value()))>;
+    ModelConfig config;
+    auto engine_result = InferenceEngine::load("model.bin", config);
+    if (engine_result.isErr()) {
+        std::cerr << engine_result.error() << '\n';
+        return 1;
+    }
 
-    template\<typename F\>
-    auto flatMap(F&& f) -> decltype(f(value()));
-};
-```
+    auto engine = std::move(engine_result.value());
 
-**使用**:
+    GenerationConfig generation;
+    generation.max_new_tokens = 64;
+    generation.temperature = 0.7f;
+    generation.top_p = 0.9f;
+    generation.do_sample = true;
 
-```cpp
-Result\<int\> parseInt(const std::string& s) {
-    try {
-        return Result\<int\>::ok(std::stoi(s));
-    } catch (...) {
-        return Result\<int\>::err("Invalid integer: " + s);
+    auto output = engine->generate({1, 15043, 29892}, generation);
+    if (output.isErr()) {
+        std::cerr << output.error() << '\n';
+        return 1;
     }
-}
 
-auto result = parseInt("42");
-if (result.isOk()) {
-    std::cout << "Value: " << result.value() << std::endl;
-} else {
-    std::cerr << "Error: " << result.error() << std::endl;
+    const auto& stats = engine->getStats();
+    std::cout << "生成了 " << output.value().size()
+              << " 个 token，速度 " << stats.tokens_per_second << " tok/s\n";
 }
-
-// 或使用默认值
-int val = parseInt("abc").valueOr(0);  // val = 0
 ```
 
-### CudaException
+## 输入输出约定
 
-带上下文的 CUDA 错误异常。
+| 方法 | 输入 | 输出 |
+|------|------|------|
+| `load()` | 运行时模型路径 + `ModelConfig` | `Result<std::unique_ptr<InferenceEngine>>` |
+| `generate()` | prompt token ID + `GenerationConfig` | `Result<std::vector<int>>` |
+| `getStats()` | 无 | `GenerationStats` |
 
-```cpp
-#include <tiny_llm/cuda_utils.h>
-
-class CudaException : public std::exception {
-public:
-    CudaException(cudaError_t err, const char* file, int line);
+## 说明
 
-    const char* what() const noexcept override;
-    cudaError_t error() const;
-    const char* file() const;
-    int line() const;
-};
-
-// 错误检查宏
-#define CUDA_CHECK(call) \
-    do { \
-        cudaError_t err = call; \
-        if (err != cudaSuccess) { \
-            throw CudaException(err, __FILE__, __LINE__); \
-        } \
-    } while(0)
-```
-
----
-
-## 工具类
-
-### DeviceBuffer\<T\>
-
-GPU 显存的 RAII 封装。
-
-```cpp
-#include <tiny_llm/cuda_utils.h>
-
-template\<typename T\>
-class DeviceBuffer {
-public:
-    DeviceBuffer();                        // 空缓存
-    explicit DeviceBuffer(size_t count);   // 分配 count 个元素
-    ~DeviceBuffer();                       // 自动清理
-
-    // 不可复制
-    DeviceBuffer(const DeviceBuffer&) = delete;
-    DeviceBuffer& operator=(const DeviceBuffer&) = delete;
-
-    // 可移动
-    DeviceBuffer(DeviceBuffer&&) noexcept;
-    DeviceBuffer& operator=(DeviceBuffer&&) noexcept;
-
-    // 数据访问
-    T* data();
-    const T* data() const;
-    size_t size() const;
-    size_t bytes() const;
-
-    // 数据传输
-    void copyFromHost(const T* src, size_t count, cudaStream_t stream = 0);
-    void copyToHost(T* dst, size_t count, cudaStream_t stream = 0) const;
-};
-```
-
-### CudaStream
-
-CUDA 流的 RAII 封装。
-
-```cpp
-class CudaStream {
-public:
-    CudaStream();
-    ~CudaStream();
-
-    CudaStream(const CudaStream&) = delete;
-    CudaStream(CudaStream&&) noexcept;
-
-    cudaStream_t get() const;
-    operator cudaStream_t() const;
-
-    void synchronize();
-};
-```
-
-### CudaEvent
-
-用于计时和同步的 CUDA 事件。
-
-```cpp
-class CudaEvent {
-public:
-    CudaEvent();
-    ~CudaEvent();
-
-    void record(cudaStream_t stream = 0);
-    void synchronize();
-
-    static float elapsedMs(const CudaEvent& start, const CudaEvent& end);
-
-    cudaEvent_t get() const;
-};
-```
-
-**计时示例**:
-
-```cpp
-CudaEvent start, end;
-
-start.record(stream);
-kernel\<\<\<grid, block, 0, stream\>\>\>(...);
-end.record(stream);
-
-end.synchronize();
-float ms = CudaEvent::elapsedMs(start, end);
-std::cout << "Kernel 时间: " << ms << " ms" << std::endl;
-```
-
-### StreamPool
-
-用于并行执行的 CUDA 流池。
-
-```cpp
-class StreamPool {
-public:
-    explicit StreamPool(int num_streams = 4);
-
-    cudaStream_t getStream();        // 轮询
-    cudaStream_t getStream(int idx);  // 按索引
-
-    void synchronizeAll();
-    int numStreams() const;
-};
-```
+- Prompt 输入是 token ID，不是原始文本字符串。
+- 在调用 `value()` 或 `error()` 前，应先检查 `isErr()`。
diff --git a/docs/zh/api/result.md b/docs/zh/api/result.md
index 98142c5..b724bb9 100644
--- a/docs/zh/api/result.md
+++ b/docs/zh/api/result.md
@@ -1,204 +1,51 @@
 # Result\<T\>
 
-The `Result\<T\>` class provides no-exception error handling for Tiny-LLM operations.
+`Result<T>` 是 Tiny-LLM 在宿主侧使用的可失败返回类型。
 
-## Overview
-
-Instead of throwing exceptions, Tiny-LLM operations return `Result\<T\>` which either contains a value of type `T` or an error message.
-
-## Class Definition
+## 结构
 
 ```cpp
-namespace tinyllm {
-
 template <typename T>
 class Result {
 public:
-    // Constructors
-    Result(T value);                    // Success result
-    Result(Error error);                // Error result
-    Result(std::string error_message);  // Error from string
+    static Result<T> ok(T value);
+    static Result<T> err(std::string message);
 
-    // Check status
-    bool ok() const;
-    explicit operator bool() const;
+    bool isOk() const;
+    bool isErr() const;
 
-    // Access value (undefined behavior if error)
     T& value();
     const T& value() const;
-    T& operator*();
-    const T& operator*() const;
-    T* operator->();
-    const T* operator->() const;
-
-    // Access value with default
-    T value_or(T default_value) const;
-
-    // Access error
-    const Error& error() const;
-    std::string error_message() const;
-
-private:
-    std::variant<T, Error> data_;
+    const std::string& error() const;
+    T valueOr(T default_value) const;
 };
 
-// Specialization for void
 template <>
 class Result<void> {
 public:
-    Result();                           // Success
-    Result(Error error);                // Error
+    static Result<void> ok();
+    static Result<void> err(std::string message);
 
-    bool ok() const;
-    const Error& error() const;
-    std::string error_message() const;
+    bool isOk() const;
+    bool isErr() const;
+    const std::string& error() const;
 };
-
-}  // namespace tinyllm
 ```
 
-## Usage Patterns
-
-### Basic Error Handling
+## 常见用法
 
 ```cpp
-Result<ModelConfig> config_result = load_config("config.json");
-if (!config_result.ok()) {
-    std::cerr << "Error: " << config_result.error_message() << std::endl;
+auto engine_result = tiny_llm::InferenceEngine::load("model.bin", config);
+if (engine_result.isErr()) {
+    std::cerr << engine_result.error() << '\n';
     return 1;
 }
 
-ModelConfig config = config_result.value();
-```
-
-### Chaining Operations
-
-```cpp
-Result<void> run_inference(const std::string& model_path, const std::string& prompt) {
-    InferenceEngine engine;
-
-    Result<void> load_result = engine.load(model_path);
-    if (!load_result.ok()) {
-        return load_result;  // Propagate error
-    }
-
-    Result<std::string> gen_result = engine.generate(prompt);
-    if (!gen_result.ok()) {
-        return gen_result.error();
-    }
-
-    std::cout << gen_result.value() << std::endl;
-    return {};  // Success
-}
-```
-
-### Using value_or
-
-```cpp
-Result\<int\> get_num_layers() {
-    // ...
-}
-
-int layers = get_num_layers().value_or(32);  // Default to 32 if error
-```
-
-### Boolean Conversion
-
-```cpp
-Result<void> result = engine.load("model.bin");
-
-if (result) {
-    // Success
-    std::cout << "Model loaded successfully" << std::endl;
-} else {
-    // Error
-    std::cerr << result.error_message() << std::endl;
-}
-```
-
-## Error Class
-
-```cpp
-namespace tinyllm {
-
-class Error {
-public:
-    Error(ErrorCode code, std::string message);
-    Error(std::string message);  // Generic error
-
-    ErrorCode code() const;
-    const std::string& message() const;
-    std::string full_message() const;
-
-private:
-    ErrorCode code_;
-    std::string message_;
-};
-
-enum class ErrorCode {
-    Success = 0,
-    InvalidArgument,
-    FileNotFound,
-    InvalidFormat,
-    OutOfMemory,
-    CudaError,
-    InternalError,
-};
-
-}  // namespace tinyllm
-```
-
-## Best Practices
-
-### 1. Always Check Results
-
-```cpp
-// BAD: Undefined behavior if error
-auto value = result.value();
-
-// GOOD: Check first
-if (result.ok()) {
-    auto value = result.value();
-}
-```
-
-### 2. Propagate Errors
-
-```cpp
-Result<void> process() {
-    Result<Data> data = load_data();
-    if (!data.ok()) {
-        return data.error();  // Propagate error
-    }
-
-    Result<void> processed = transform(data.value());
-    if (!processed.ok()) {
-        return processed;  // Propagate error
-    }
-
-    return {};
-}
+auto engine = std::move(engine_result.value());
 ```
 
-### 3. Use Meaningful Error Messages
-
-```cpp
-return Result<ModelConfig>::Error(
-    ErrorCode::InvalidArgument,
-    "vocab_size must be positive, got: " + std::to_string(vocab_size)
-);
-```
-
-## Comparison with Exceptions
-
-| Aspect | Result\<T\> | Exceptions |
-|--------|-----------|------------|
-| Performance | Zero overhead | Stack unwinding cost |
-| Control flow | Explicit | Implicit |
-| Debuggability | Easy to trace | Can be hard to follow |
-| CUDA compatibility | Excellent | Problematic |
-
-## See Also
+## 使用建议
 
-- [InferenceEngine](/en/api/inference-engine) - Main API class
-- [Error Handling Guide](/en/architecture/inference-engine#error-handling)
+- 在调用 `value()` 或 `error()` 前，先检查 `isOk()` / `isErr()`。
+- 只有在 fallback 真正合理时才使用 `valueOr()`。
+- 优先向上传播错误，而不是静默吞掉失败。
diff --git a/docs/zh/architecture/index.md b/docs/zh/architecture/index.md
index 7e9bb7e..785cc87 100644
--- a/docs/zh/architecture/index.md
+++ b/docs/zh/architecture/index.md
@@ -1,314 +1,54 @@
-# 架构设计
+# 架构概览
 
-Tiny-LLM 推理引擎的系统架构和设计文档。
+Tiny-LLM 围绕一条很窄的 CUDA/C++ 运行时路径构建：支持的二进制运行时加载、显式 KV Cache 管理、W8A16 量化层，以及宿主侧基于 `Result<T>` 的错误传播。
 
-## 概述
-
-Tiny-LLM 是一个高性能 CUDA C++ 推理引擎，专为高效的 Transformer 模型推理而设计。其核心特性包括：
-
-| 特性 | 技术 | 收益 |
-|---------|------------|---------|
-| **W8A16 量化** | INT8 权重 + FP16 激活 | 显存减少约 50% |
-| **高效 KV 缓存** | 增量解码与序列管理 | O(1) 自回归步进 |
-| **优化 Kernel** | Tensor Core INT8、共享内存 tiling | 最大吞吐 |
-| **模块化设计** | 清晰职责分离 | 易于扩展和测试 |
-
----
-
-## 系统架构
-
-```mermaid
-flowchart TB
-    subgraph Input["📥 输入"]
-        A["模型文件<br/>.gguf/.bin"] --> B["GGUF 解析器"]
-        P["Prompt Tokens"] --> C["分词"]
-    end
-
-    subgraph Engine["⚙️ InferenceEngine"]
-        B --> D["模型加载器"]
-        D --> E["InferenceEngine"]
-        C --> E
-        E --> F["Transformer 层栈"]
-    end
-
-    subgraph Transformer["🔄 Transformer 层"]
-        F --> G["嵌入层"]
-        G --> H["Layer 1..N"]
-        H --> I["LM Head"]
-    end
-
-    subgraph KVCache["💾 KV 缓存"]
-        H <--> J["KV Cache 管理器"]
-        J --> K["预分配槽位"]
-    end
-
-    subgraph Output["📤 输出"]
-        I --> L["采样"]
-        L --> M["生成的 Tokens"]
-    end
-
-    style A fill:#00D4AA,stroke:#00C49A,color:#fff
-    style E fill:#76B900,stroke:#5a8f00,color:#fff
-    style J fill:#F59E0B,stroke:#d97706,color:#fff
-    style L fill:#8B5CF6,stroke:#7c3aed,color:#fff
-```
-
----
-
-## 核心组件
-
-### 1. InferenceEngine
-
-模型推理的主入口。
-
-```cpp
-class InferenceEngine {
-public:
-    // 从磁盘加载模型
-    static Result\<std::unique_ptr\<InferenceEngine\>\> load(
-        const std::string& path, const ModelConfig& config);
-    
-    // 完整的生成流程
-    std::vector<int> generate(
-        const std::vector<int>& prompt, 
-        const GenerationConfig& config);
-    
-    // 统计和性能分析
-    const GenerationStats& getStats() const;
-    void resetStats();
-};
-```
-
-**核心职责**:
-- 模型生命周期管理
-- Prefill/decode 编排
-- Token 采样和生成循环
-- 性能分析
-
-### 2. KV Cache 管理器
-
-用于自回归生成的高效键值缓存。
+## 系统示意
 
 ```mermaid
 flowchart LR
-    subgraph CacheStructure["KV 缓存内存布局"]
-        K["K 缓存<br/>[batch, layers, seq, heads, dim]"]
-        V["V 缓存<br/>[batch, layers, seq, heads, dim]"]
-    end
-
-    subgraph Operations["操作"]
-        A1["allocateSequence()"]
-        A2["appendKV()"]
-        A3["getCache()"]
-        A4["advanceSeqLen()"]
-    end
-
-    A1 --> CacheStructure
-    A2 --> CacheStructure
-    A3 --> CacheStructure
-    A4 --> CacheStructure
-
-    style K fill:#76B900,stroke:#5a8f00,color:#fff
-    style V fill:#76B900,stroke:#5a8f00,color:#fff
+    A[二进制运行时模型] --> B[InferenceEngine::load()]
+    C[GGUF 文件] --> D[GGUFParser]
+    B --> E[ModelWeights]
+    E --> F[Transformer 层]
+    F --> G[KVCacheManager]
+    F --> H[W8A16 Kernel]
+    H --> I[采样]
+    I --> J[生成的 token ID]
+    D --> K[元数据 / Tensor 检查]
 ```
 
-### 3. W8A16 量化
-
-仅权重的 INT8 量化，使用 FP16 激活。
-
-```mermaid
-flowchart TB
-    subgraph QuantScheme["量化方案"]
-        W["权重: INT8<br/>[rows, cols]"]
-        S["缩放: FP16<br/>[rows/128, cols]"]
-        O["输出: FP16<br/>= dequant(W, S) @ Act"]
-    end
-
-    W --> O
-    S --> O
-
-    subgraph GroupWise["组级布局"]
-        G0["group 0 (128 元素) → scales[0]"]
-        G1["group 1 (128 元素) → scales[1]"]
-        GN["..."]
-    end
-
-    style W fill:#8B5CF6,stroke:#7c3aed,color:#fff
-    style S fill:#F59E0B,stroke:#d97706,color:#fff
-    style O fill:#00D4AA,stroke:#00C49A,color:#fff
-```
-
-**优势**:
-- 权重显存减少 50%
-- 不量化激活 (保持精度)
-- Ampere+ 上高效的 INT8 Tensor Core 利用
-
----
-
-## 数据流
-
-### Prefill 阶段 (Prompt 处理)
-
-```mermaid
-sequenceDiagram
-    participant User as 用户
-    participant Engine as InferenceEngine
-    participant Trans as Transformer
-    participant KV as KV 缓存
-    participant Sample as 采样
-
-    User->>Engine: generate(prompt, config)
-    Engine->>Engine: tokenize(prompt)
-    Engine->>Trans: forward(tokens, prefill=true)
-    
-    loop 每一层
-        Trans->>Trans: RMSNorm
-        Trans->>Trans: QKV 投影 (W8A16)
-        Trans->>Trans: RoPE
-        Trans->>Trans: Attention Prefill
-        Trans->>KV: store_kv(layer, k, v)
-        Trans->>Trans: Output 投影
-        Trans->>Trans: 残差
-    end
-    
-    Trans-->>Engine: logits
-    Engine->>Sample: sample(logits)
-    Sample-->>Engine: first_token
-    Engine-->>User: first_token
-```
-
-### Decode 阶段 (Token 生成)
-
-```mermaid
-sequenceDiagram
-    participant User as 用户
-    participant Engine as InferenceEngine
-    participant Trans as Transformer
-    participant KV as KV 缓存
-    participant Sample as 采样
-
-    loop 每个新 token
-        User->>Engine: continue generation
-        Engine->>Trans: forward(next_token, prefill=false)
-        
-        loop 每一层
-            Trans->>Trans: RMSNorm
-            Trans->>Trans: QKV 投影 (W8A16)
-            Trans->>Trans: RoPE
-            Trans->>KV: get_cache(layer)
-            Trans->>Trans: Attention Decode
-            Trans->>KV: append_kv(layer, k, v)
-            Trans->>Trans: Output 投影
-            Trans->>Trans: 残差
-        end
-        
-        Trans-->>Engine: logits
-        Engine->>Sample: sample(logits)
-        Sample-->>Engine: next_token
-    end
-    
-    Engine-->>User: full_output
-```
-
----
-
-## 内存布局
-
-### 权重存储
-
-```mermaid
-block-beta
-    columns 1
-    
-    block:Header["模型权重"]
-        A["Token 嵌入<br/>FP16 [vocab, hidden]"]
-    end
-    
-    block:Layers["层权重 (×N)"]
-        B1["注意力<br/>INT8 q/k/v/o_proj"]
-        B2["FFN<br/>INT8 gate/up/down"]
-        B3["缩放<br/>FP16 每组"]
-    end
-    
-    block:Output["输出"]
-        C["LM Head<br/>FP16 [hidden, vocab]"]
-    end
-```
-
-### 激活缓存
-
-| 缓存 | 形状 | 数据类型 | 大小 (B=1, S=2048, H=4096) |
-|--------|-------|-------|---------------------------|
-| 隐藏状态 | [B, S, H] | FP16 | 16 MB |
-| 注意力输出 | [B, heads, S, head_dim] | FP16 | 16 MB |
-| QKV | [B, S, 3×H] | FP16 | 48 MB |
-| FFN 中间结果 | [B, S, intermediate_dim] | FP16 | 44 MB |
-
----
-
-## 性能优化
-
-### 内存优化
-
-| 技术 | 实现 | 收益 |
-|-----------|----------------|---------|
-| W8A16 量化 | 每组 INT8 权重 + FP16 缩放 | 权重显存减少 50% |
-| KV Cache 分页 | 预分配 + 序列管理 | 高效批处理 |
-| 激活复用 | 原地操作 | 减少分配 |
+## 核心组件
 
-### 计算优化
+| 组件 | 职责 |
+|------|------|
+| `InferenceEngine` | 公开运行时入口，负责加载支持的二进制模型并生成 token ID |
+| `ModelLoader` | 支持的二进制格式运行时权重加载 |
+| `GGUFParser` | GGUF 解析、元数据提取和 tensor 检查 |
+| `TransformerLayer` | W8A16 注意力与 FFN 执行 |
+| `KVCacheManager` | 预分配缓存槽位与序列生命周期 |
+| `Result<T>` | 宿主侧可失败 API 边界 |
 
-| 技术 | 应用 | 加速比 |
-|-----------|-------------|---------|
-| Tensor Cores | INT8 矩阵乘 (Ampere+) | 2-4× vs FP16 |
-| Warp Shuffle | 归约 | 消除共享内存 |
-| 向量化加载 | 128-bit 内存访问 | 更好带宽 |
-| Kernel 融合 | RMSNorm+Resid, SiLU+Mul | 减少内核启动 |
+## 加载边界
 
-### Kernel 性能
+- **运行时加载：** `InferenceEngine::load("model.bin", config)`
+- **GGUF 工具链：** `GGUFParser` 用于解析、检查和校验
+- **不支持：** 通过 `InferenceEngine::load()` 直接进行 `.gguf` 运行时加载
 
-```mermaid
-xychart-beta
-    title "Kernel 吞吐量 (7B 模型, A100)"
-    x-axis ["w8a16_matmul", "attn_decode", "attn_prefill", "rmsnorm", "rope"]
-    y-axis "吞吐量" 0-->100
-    bar [80, 65, 75, 95, 98]
-```
+## 生成流程
 
----
+1. 通过支持的二进制运行时路径加载权重。
+2. 将 prompt token ID 传给 `generate()`。
+3. 在 Transformer 层栈上执行 prefill。
+4. 在 decode 阶段复用 KV cache。
+5. 从 logits 中采样下一个 token，直到 EOS 或 `max_new_tokens`。
 
-## 设计原则
-
-```mermaid
-mindmap
-  root((设计原则))
-    模块化
-      清晰接口
-      职责分离
-      插件架构
-    类型安全
-      Result&lt;T&gt; 错误处理
-      强类型
-      无异常
-    RAII
-      自动 GPU 显存管理
-      流管理
-      资源清理
-    可测试性
-      单元测试
-      基于属性测试
-      CUDA 测试
-    可扩展性
-      新 Kernel
-      采样策略
-      模型格式
-```
+## 说明
 
----
+- 公共示例应使用 token ID，而不是仓库中并不存在的 tokenizer API。
+- 公共文档必须分开描述二进制运行时路径和 GGUF 解析器。
 
 ## 下一步
 
-- [量化详解](./quantization) - W8A16 实现深入解析
-- [KV 缓存](./kv-cache) - 缓存管理策略
-- [CUDA Kernel](./cuda-kernels) - Kernel 优化技术
-- [API 参考](../api/inference-engine) - 完整 API 文档
+- [推理引擎](/zh/architecture/inference-engine)
+- [API 参考](/zh/api/)
+- [性能指南](/zh/performance/)
diff --git a/docs/zh/architecture/inference-engine.md b/docs/zh/architecture/inference-engine.md
index 7f967af..20618e8 100644
--- a/docs/zh/architecture/inference-engine.md
+++ b/docs/zh/architecture/inference-engine.md
@@ -1,165 +1,51 @@
-# 架构概览
+# 推理引擎
 
-Tiny-LLM 在设计上注重简洁性和教育价值，同时保持生产级的性能。
+`InferenceEngine` 是 Tiny-LLM 的公开运行时入口。它负责持有已加载的运行时权重、创建 KV cache、构建 Transformer 层栈，并驱动 prefill/decode 生成流程。
 
-## 核心组件
-
-```
-┌─────────────────────────────────────────────────────┐
-│                  InferenceEngine                     │
-│                    (公共 API)                        │
-├─────────────────────────────────────────────────────┤
-│                                                      │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
-│  │ ModelConfig │  │   Result\<T\> │  │  KVCache    │ │
-│  │             │  │             │  │  Manager    │ │
-│  └─────────────┘  └─────────────┘  └─────────────┘ │
-│                                                      │
-├─────────────────────────────────────────────────────┤
-│               TransformerLayer                       │
-│  ┌─────────────────┐    ┌─────────────────┐        │
-│  │  Attention      │    │      FFN        │        │
-│  │  (W8A16)        │    │    (W8A16)      │        │
-│  └─────────────────┘    └─────────────────┘        │
-├─────────────────────────────────────────────────────┤
-│               QuantizedWeight                        │
-│         (INT8 权重 + 每组缩放因子)                   │
-├─────────────────────────────────────────────────────┤
-│                  CUDA 内核                           │
-│   (注意力、前馈网络、量化、内存操作)                  │
-└─────────────────────────────────────────────────────┘
-```
-
-## 组件职责
-
-### InferenceEngine
-
-协调模型加载和生成的公共 API：
-
-- `load()` - 从磁盘加载模型权重
-- `generate()` - 从提示词生成文本
-- `encode()` - 对输入文本进行分词
-
-### Result\<T\>
-
-无异常错误传播机制：
+## 公共 API
 
 ```cpp
-Result<void> result = engine.load("model.bin");
-if (!result.ok()) {
-    // 处理错误
-    std::cerr << result.error() << std::endl;
-}
-```
+#include <tiny_llm/inference_engine.h>
 
-### ModelConfig
+namespace tiny_llm {
 
-保存模型超参数：
+class InferenceEngine {
+public:
+    static Result<std::unique_ptr<InferenceEngine>> load(
+        const std::string& model_path,
+        const ModelConfig& config);
 
-| 参数 | 类型 | 描述 |
-|------|------|------|
-| `vocab_size` | `size_t` | 词汇表大小 |
-| `hidden_dim` | `size_t` | 隐藏层维度 |
-| `num_layers` | `size_t` | Transformer 层数 |
-| `num_heads` | `size_t` | 注意力头数 |
-| `max_seq_len` | `size_t` | 最大序列长度 |
+    Result<std::vector<int>> generate(
+        const std::vector<int>& prompt_tokens,
+        const GenerationConfig& config);
 
-### QuantizedWeight
+    const GenerationStats& getStats() const;
+    void resetStats();
+};
 
-带每组缩放因子的 INT8 量化权重：
-
-- 权重以 INT8 存储
-- 每组独立的缩放因子用于反量化
-- 支持 W8A16 推理模式
-
-### TransformerLayer
-
-单个 Transformer 层包含：
-
-- 多头自注意力
-- 前馈网络
-- 层归一化
-- 残差连接
-
-### KVCacheManager
+} // namespace tiny_llm
+```
 
-管理键值缓存以实现高效生成：
+## 加载边界
 
-- 预分配的缓存槽位
-- 每序列缓存管理
-- 内存高效的缓存策略
+- `InferenceEngine::load()` 使用支持的**二进制运行时格式**。
+- `.gguf` 路径会被运行时路径以结构化错误拒绝。
+- GGUF 解析与元数据提取属于 `GGUFParser`，不属于运行时快路径。
 
-## 内存布局
+## 职责
 
-```
-┌────────────────────────────────────────┐
-│           权重内存                      │
-│  ┌──────────────────────────────────┐  │
-│  │   嵌入表 (FP16)                  │  │
-│  └──────────────────────────────────┘  │
-│  ┌──────────────────────────────────┐  │
-│   层权重 (INT8 + 缩放因子)            │  │
-│  │   ┌────────────────────────────┐ │  │
-│  │   │  Q, K, V 投影              │ │  │
-│  │   │  输出投影                  │ │  │
-│  │   │  FFN 上下/下投影           │ │  │
-│  │   └────────────────────────────┘ │  │
-│  └──────────────────────────────────┘  │
-│  ┌──────────────────────────────────┐  │
-│  │   输出层 (FP16)                 │  │
-│  └──────────────────────────────────┘  │
-└────────────────────────────────────────┘
-```
+1. 在运行时初始化前校验 `ModelConfig`。
+2. 通过 `ModelLoader::loadBin()` 加载运行时权重。
+3. 分配 CUDA stream 和可复用的 hidden/logit buffer。
+4. 创建 `KVCacheManager` 与 `TransformerLayer` 层栈。
+5. 先执行一次 prefill，再逐 token decode，直到 EOS 或生成上限。
 
-## 数据流
+## 输入与输出
 
-```
-输入文本
-    │
-    ▼
-┌─────────────┐
-│   分词器    │
-└─────────────┘
-    │
-    ▼
-Token IDs
-    │
-    ▼
-┌─────────────────┐
-│    嵌入层       │  ← FP16 查找
-└─────────────────┘
-    │
-    ▼
-┌─────────────────────────────────────┐
-│         Transformer 层              │
-│  ┌─────────────────────────────┐    │
-│  │     自注意力                 │    │  ← W8A16 量化
-│  │  (Q×K^T / √d) → Softmax → V │    │
-│  └─────────────────────────────┘    │
-│              │                      │
-│              ▼                      │
-│  ┌─────────────────────────────┐    │
-│  │     前馈网络                 │    │  ← W8A16 量化
-│  │     Linear → GELU → Linear  │    │
-│  └─────────────────────────────┘    │
-└─────────────────────────────────────┘
-    │
-    ▼
-┌─────────────────┐
-│    输出层        │  ← FP16 Logits
-└─────────────────┘
-    │
-    ▼
-┌─────────────────┐
-│    采样         │
-└─────────────────┘
-    │
-    ▼
-输出 Tokens
-```
+- **输入：** prompt token ID（`std::vector<int>`）
+- **输出：** 通过 `Result<std::vector<int>>` 返回生成的 token ID
+- **统计：** prefill 时间、decode 时间、吞吐与 token 计数
 
-## 下一步
+## 失败模型
 
-- [量化指南](/zh/guide/quantization) - 了解 INT8 量化
-- [性能指南](/zh/performance/optimization) - 优化技术
-- [API 参考](/zh/api/) - 详细的 API 文档
+运行时表面会通过 `Result<T>` 返回配置无效、输入不受支持、分配失败和生成校验失败等错误。调用方在读取 `value()` 之前应先检查 `isErr()`。
diff --git a/docs/zh/changelog/index.md b/docs/zh/changelog/index.md
deleted file mode 100644
index 6c8136f..0000000
--- a/docs/zh/changelog/index.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# 更新日志
-
-Tiny-LLM 的所有重要变更都记录在此。
-
-## 版本
-
-| 版本 | 日期 | 摘要 |
-|------|------|------|
-| [v2.0.2](/zh/changelog/v2.0.2) | 2024-01-15 | 错误修复和稳定性改进 |
-| [v2.0.1](/zh/changelog/v2.0.1) | 2024-01-08 | 性能优化 |
-| [v2.0.0](/zh/changelog/v2.0.0) | 2024-01-01 | 支持 INT8 量化的主要版本 |
-
-## 版本控制方案
-
-Tiny-LLM 遵循[语义化版本](https://semver.org/)：
-
-- **主版本号**：不兼容的 API 变更
-- **次版本号**：向后兼容的新功能
-- **修订号**：向后兼容的错误修复
-
-## 发布渠道
-
-| 渠道 | 描述 |
-|------|------|
-| `main` | 稳定版本 |
-| `develop` | 开发版本 |
-| `v*` 标签 | 特定版本 |
diff --git a/docs/zh/changelog/v2.0.0.md b/docs/zh/changelog/v2.0.0.md
deleted file mode 100644
index afbef03..0000000
--- a/docs/zh/changelog/v2.0.0.md
+++ /dev/null
@@ -1,148 +0,0 @@
-# v2.0.0
-
-发布日期: 2024-01-01
-
-我们很高兴地宣布 Tiny-LLM v2.0.0，这是一个支持 INT8 量化的主要版本！
-
-## 主要功能
-
-### INT8 量化 (W8A16)
-
-v2.0.0 的核心功能是全面支持 INT8 权重量化：
-
-- **内存减少 50%** 用于模型权重
-- **推理速度提升 2 倍** 在内存受限的工作负载上
-- **精度损失极小** 采用分组量化
-
-```cpp
-// 加载量化模型
-InferenceEngine engine;
-engine.load("model-int8.bin");
-
-// 正常生成
-engine.generate("你好，世界！");
-```
-
-### 新架构
-
-使用现代 C++17 设计完全重写的核心：
-
-- `Result\<T\>` 实现无异常错误处理
-- `KVCacheManager` 实现高效生成
-- 模块化的 `TransformerLayer` 架构
-
-### CUDA 优化
-
-- 融合注意力内核
-- 优化的 INT8 矩阵乘法
-- 改进的内存合并
-
-## 破坏性变更
-
-### API 变更
-
-API 已为 v2.0.0 重新设计：
-
-| v1.x | v2.0.0 |
-|------|--------|
-| `loadModel()` | `load()` |
-| `generateText()` | `generate()` |
-| `getError()` | `result.error()` |
-
-### 配置变更
-
-配置现在使用结构体：
-
-```cpp
-// 旧版 (v1.x)
-engine.set("max_tokens", 100);
-
-// 新版 (v2.0.0)
-GenerationConfig config;
-config.max_tokens = 100;
-engine.generate(prompt, config);
-```
-
-### 模型格式
-
-v2.0.0 使用新的模型格式。转换您的模型：
-
-```bash
-tinyllm-convert --input model-v1.bin --output model-v2.bin
-```
-
-## 新组件
-
-### Result\<T\>
-
-无异常错误传播：
-
-```cpp
-Result<std::string> result = engine.generate("你好");
-if (!result.ok()) {
-    std::cerr << result.error_message() << std::endl;
-}
-```
-
-### KVCacheManager
-
-高效的键值缓存：
-
-```cpp
-KVCacheManager cache;
-cache.initialize(model_config, cache_config);
-auto seq_id = cache.create_sequence();
-```
-
-## 性能
-
-### 基准测试 (RTX 4090 上的 LLaMA-7B)
-
-| 指标 | v1.x | v2.0.0 | 提升 |
-|------|------|--------|------|
-| 内存 (INT8) | 13 GB | 6.5 GB | 50% |
-| 预填充 | 650 tok/s | 850 tok/s | 31% |
-| 解码 | 48 tok/s | 65 tok/s | 35% |
-
-## 迁移指南
-
-### 步骤 1：更新模型文件
-
-```bash
-tinyllm-convert --input old-model.bin --output new-model.bin
-```
-
-### 步骤 2：更新代码
-
-```cpp
-// 旧版
-TinyLLM engine;
-engine.loadModel("model.bin");
-auto text = engine.generateText("你好");
-
-// 新版
-InferenceEngine engine;
-engine.load("model.bin");
-auto result = engine.generate("你好");
-if (result.ok()) {
-    std::cout << result.value() << std::endl;
-}
-```
-
-### 步骤 3：更新构建
-
-```bash
-# v2.0.0 需要 C++17
-cmake -S . -B build -DCMAKE_CXX_STANDARD=17
-cmake --build build -j$(nproc)
-```
-
-## 已知问题
-
-- INT4 量化尚不支持
-- Flash Attention 需要 CUDA 11.6+
-- Windows 支持处于实验阶段
-
-## 贡献者
-
-特别感谢所有让 v2.0.0 成为可能的贡献者！
diff --git a/docs/zh/changelog/v2.0.1.md b/docs/zh/changelog/v2.0.1.md
deleted file mode 100644
index 804f3b8..0000000
--- a/docs/zh/changelog/v2.0.1.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# v2.0.1
-
-发布日期: 2024-01-08
-
-## 新功能
-
-- 添加了分组查询注意力 (GQA) 支持
-- 添加了 Top-K 采样选项
-- 添加了重复惩罚参数
-
-## 性能改进
-
-- 优化 INT8 反量化内核（提速 20%）
-- KV 缓存内存使用减少 10%
-- 长上下文的提示处理速度提升
-
-## 错误修复
-
-- 修复了温度为 0.0（贪心解码）时输出不正确的问题
-- 修复了分词器处理 Unicode 字符的问题
-- 修复了多 GPU 系统上的 CUDA 图捕获问题
-
-## API 变更
-
-### 新参数
-
-```cpp
-GenerationConfig config;
-config.top_k = 50;  // 新增：Top-K 采样
-config.repetition_penalty = 1.1f;  // 新增：重复惩罚
-```
-
-### ModelConfig 扩展
-
-```cpp
-ModelConfig config;
-config.num_kv_heads = 8;  // 新增：用于 GQA 支持
-```
-
-## 已知问题
-
-- Flash Attention 在序列长度 > 4096 时可能产生不正确结果
-- Windows 构建可能需要手动配置 CUDA 路径
-
-## 贡献者
-
-感谢所有为本次发布做出贡献的贡献者！
diff --git a/docs/zh/changelog/v2.0.2.md b/docs/zh/changelog/v2.0.2.md
deleted file mode 100644
index b15f182..0000000
--- a/docs/zh/changelog/v2.0.2.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# v2.0.2
-
-发布日期: 2024-01-15
-
-## 错误修复
-
-### 关键修复
-
-- 修复了销毁序列时 KV 缓存的内存泄漏
-- 修复了特殊字符的分词错误
-- 修复了 Ampere GPU 上特定序列长度时的 CUDA 内核崩溃
-
-### 次要修复
-
-- 修复了模型文件损坏时的错误消息不正确
-- 修复了多线程推理中的竞争条件
-- 修复了 RMS 归一化 epsilon 值不正确
-
-## 改进
-
-### 性能
-
-- 内存分配开销减少 15%
-- RTX 40 系列 GPU 上 token 生成速度提升 5-8%
-
-### 文档
-
-- 添加了常见问题的故障排除指南
-- 更新了 API 参考并添加了更多示例
-- 添加了 LLaMA-7B 的性能基准测试
-
-## 兼容性
-
-- 最低 CUDA 版本：11.0（无变化）
-- 测试平台：Ubuntu 20.04/22.04、Windows 10/11
-- GPU 兼容性：Volta (SM70) 及更新版本
-
-## 迁移指南
-
-与 v2.0.1 没有破坏性变更。只需重新构建：
-
-```bash
-git pull origin main
-cmake --build build -j$(nproc)
-```
-
-## 贡献者
-
-感谢所有为本次发布做出贡献的贡献者！
diff --git a/docs/zh/guide/quickstart.md b/docs/zh/guide/quickstart.md
index b91b195..125fba6 100644
--- a/docs/zh/guide/quickstart.md
+++ b/docs/zh/guide/quickstart.md
@@ -1,80 +1,52 @@
 # 快速开始
 
-本教程将引导您完成使用 Tiny-LLM 进行首次推理。
+本页展示与当前代码库一致的最小运行时路径。
 
-## 前提条件
-
-请确保您已经[安装 Tiny-LLM](/zh/guide/installation)。
-
-## 基本用法
-
-### 1. 加载模型
+## 1. 加载支持的运行时模型
 
 ```cpp
-#include <tiny-llm/inference_engine.h>
-
-using namespace tinyllm;
+#include <iostream>
+#include <tiny_llm/inference_engine.h>
 
 int main() {
-    // 创建推理引擎
-    InferenceEngine engine;
+    using namespace tiny_llm;
 
-    // 从文件加载模型
-    Result<void> result = engine.load("model.bin");
-    if (!result.ok()) {
-        std::cerr << "加载模型失败: " << result.error() << std::endl;
+    ModelConfig config;
+    auto engine_result = InferenceEngine::load("model.bin", config);
+    if (engine_result.isErr()) {
+        std::cerr << engine_result.error() << '\n';
         return 1;
     }
-
-    return 0;
 }
 ```
 
-### 2. 运行推理
+## 2. 生成 token ID
 
 ```cpp
-#include <tiny-llm/inference_engine.h>
-#include <iostream>
-
-int main() {
-    InferenceEngine engine;
-    engine.load("model.bin");
+using namespace tiny_llm;
 
-    // 从提示词生成文本
-    std::string prompt = "人工智能的未来是";
-    Result<std::string> result = engine.generate(prompt, /*max_tokens=*/50);
+auto engine = std::move(engine_result.value());
 
-    if (result.ok()) {
-        std::cout << "生成结果: " << result.value() << std::endl;
-    } else {
-        std::cerr << "错误: " << result.error() << std::endl;
-    }
+GenerationConfig generation;
+generation.max_new_tokens = 32;
+generation.do_sample = true;
+generation.temperature = 0.7f;
 
-    return 0;
+auto output = engine->generate({1, 15043, 29892}, generation);
+if (output.isErr()) {
+    std::cerr << output.error() << '\n';
+    return 1;
 }
 ```
 
-### 3. 配置选项
-
-```cpp
-GenerationConfig config;
-config.max_tokens = 100;
-config.temperature = 0.7f;
-config.top_p = 0.9f;
-config.top_k = 50;
-
-Result<std::string> result = engine.generate(prompt, config);
-```
-
-## 编译您的应用程序
+## 3. 明确边界
 
-```bash
-# 编译您的应用程序
-g++ -std=c++17 my_app.cpp -o my_app -I/path/to/tiny-llm/include -L/path/to/tiny-llm/build -ltinyllm
-```
+- `InferenceEngine::load()` 使用支持的二进制运行时格式。
+- `GGUFParser` 是 GGUF 解析与检查入口。
+- 公共运行时 API 面向 token ID，而不是原始字符串。
 
 ## 下一步
 
-- [架构概览](/zh/architecture/inference-engine) - 了解内部原理
-- [配置指南](/zh/guide/configuration) - 详细的配置选项
-- [API 参考](/zh/api/) - 完整的 API 文档
+- [架构概览](/zh/architecture/)
+- [API 参考](/zh/api/)
+- [安装说明](/zh/guide/installation)
diff --git a/docs/zh/guide/troubleshooting.md b/docs/zh/guide/troubleshooting.md
index 98411be..ba1bc15 100644
--- a/docs/zh/guide/troubleshooting.md
+++ b/docs/zh/guide/troubleshooting.md
@@ -252,5 +252,5 @@ std::cout << "intermediate_dim: " << config.intermediate_dim << std::endl;
 ### 资源
 
 - [GitHub Issues](https://github.com/AICL-Lab/tiny-llm/issues)
-- [文档](https://lessup.github.io/tiny-llm/)
+- [文档](https://aicl-lab.github.io/tiny-llm/)
 - [API 参考](/zh/api/inference-engine)
diff --git a/docs/zh/index.md b/docs/zh/index.md
index d79e079..424f163 100644
--- a/docs/zh/index.md
+++ b/docs/zh/index.md
@@ -3,98 +3,72 @@ layout: home
 
 hero:
   name: "Tiny-LLM"
-  text: "技术白皮书"
-  tagline: 支持 W8A16 量化的 CUDA 原生推理引擎
+  text: "CUDA 原生推理引擎"
+  tagline: 面向聚焦型 Transformer 推理，提供 W8A16 kernel、显式 KV Cache 管理，以及更低维护成本的仓库表面。
   image:
     src: /images/logo.svg
     alt: Tiny-LLM Logo
   actions:
     - theme: brand
-      text: 架构
-      link: /zh/architecture/
+      text: 开始使用
+      link: /zh/guide/getting-started
     - theme: alt
-      text: 性能
-      link: /zh/performance/
+      text: API 参考
+      link: /zh/api/
 
 features:
   - icon: "⚡"
-    title: W8A16 量化
-    details: INT8 权重 + FP16 激活 — 50% 内存减少，<1% 精度损失
-  - icon: "🔧"
-    title: CUDA 原生内核
-    details: Tensor Core INT8 矩阵乘法，优化的注意力解码，warp 级原语
+    title: W8A16 推理
+    details: INT8 权重 + FP16 激活，保持精简的 CUDA 运行时路径。
   - icon: "📦"
-    title: KV 缓存管理器
-    details: 预分配槽位，O(1) 增量解码，序列生命周期管理
+    title: 二进制运行时路径
+    details: "`InferenceEngine::load()` 面向当前引擎支持的二进制运行时格式。"
+  - icon: "🔎"
+    title: GGUF 解析工具
+    details: 保留 GGUF 解析、元数据提取和 tensor 检查能力，但不再假装它就是运行时加载路径。
+  - icon: "🧠"
+    title: 显式 KV Cache
+    details: 预分配序列槽位，让自回归解码更可预测。
   - icon: "🛡️"
-    title: Result<T> 模式
-    details: 无异常错误传播，可预测的控制流和安全的资源处理
-  - icon: "📊"
-    title: OpenSpec 治理
-    details: 需求驱动开发，自动化测试覆盖率验证
+    title: "Result<T> API"
+    details: 宿主侧失败显式可见，便于排查和收敛。
   - icon: "🧪"
-    title: 基于属性的测试
-    details: RapidCheck 集成，跨输入空间的不变量验证
+    title: 核心测试覆盖
+    details: GoogleTest 与 RapidCheck 覆盖核心加载、缓存和生成路径。
 ---
 
-## 核心结果
+## 运行时边界
 
-| 指标 | 数值 | vs FP16 |
-|------|------|---------|
-| **内存** | 7.8 GB | **↓50%** |
-| **解码** | 85 tok/s | **↑9%** |
-| **精度** | 9.12 ppl | Δ 0.4% |
+| 能力 | 状态 | 说明 |
+|------|------|------|
+| 二进制运行时加载 | 支持 | `InferenceEngine::load()` 使用这条路径 |
+| GGUF 解析与检查 | 支持 | 使用 `GGUFParser` 读取元数据和 tensor |
+| 直接 GGUF 运行时加载 | 不支持 | 运行时加载器会拒绝 `.gguf` 路径 |
 
-*基准测试：LLaMA-7B, RTX 4090, INT8 权重*
-
-## 架构
+## 架构示意
 
 ```mermaid
 flowchart LR
-    A[模型文件] --> B[GGUF 解析器]
-    B --> C[推理引擎]
-    C --> D[Transformer 层]
-    D --> E[KV 缓存]
-    D --> F[W8A16 矩阵乘法]
-    F --> G[采样]
-    G --> H[输出 Token]
-
-    style C fill:#00D4AA,stroke:#00C49A,color:#fff
-    style F fill:#76B900,stroke:#5a8f00,color:#fff
-```
-
-## 快速开始
-
-```bash
-# 克隆
-git clone https://github.com/AICL-Lab/tiny-llm.git
-cd tiny-llm
-
-# 构建（需要 CUDA 11.0+）
-cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
-cmake --build build -j$(nproc)
-
-# 测试
-ctest --test-dir build --output-on-failure
+    A[二进制运行时模型] --> B[InferenceEngine::load()]
+    C[GGUF 文件] --> D[GGUFParser]
+    B --> E[Transformer 层]
+    E --> F[KV Cache]
+    E --> G[W8A16 矩阵乘法]
+    G --> H[采样]
+    H --> I[输出 Tokens]
+    D --> J[元数据 / Tensor 检查]
+
+    style B fill:#00D4AA,stroke:#00C49A,color:#fff
+    style G fill:#76B900,stroke:#5a8f00,color:#fff
+    style D fill:#8B5CF6,stroke:#7c3aed,color:#fff
 ```
 
-## 文档
-
-| 资源 | 描述 |
-|------|------|
-| [架构概述](/zh/architecture/) | 系统设计和数据流 |
-| [W8A16 量化](/zh/architecture/quantization) | 量化方案详情 |
-| [CUDA 内核](/zh/architecture/cuda-kernels) | 内核优化技术 |
-| [性能](/zh/performance/) | 基准测试和分析指南 |
-| [API 参考](/zh/api/) | 完整 API 文档 |
-
-## 核心组件
+## 从这里开始
 
-| 组件 | 职责 |
+| 资源 | 用途 |
 |------|------|
-| `Result<T>` | 无异常错误传播 |
-| `ModelConfig` | 模型超参数（vocab_size, hidden_dim 等） |
-| `QuantizedWeight` | INT8 权重和每组缩放因子 |
-| `TransformerLayer` | W8A16 量化注意力 + FFN |
-| `KVCacheManager` | 预分配的序列缓存槽位 |
-| `InferenceEngine` | 公共 API：load(), generate() |
+| [开始使用](/zh/guide/getting-started) | 最小构建与首次运行路径 |
+| [架构说明](/zh/architecture/) | 运行时结构与职责划分 |
+| [API 参考](/zh/api/) | 公共头文件与类型 |
+| [性能](/zh/performance/) | 基准和优化说明 |
+| [GitHub 仓库](https://github.com/AICL-Lab/tiny-llm) | 源码、Issue、Release |
diff --git a/openspec/MIGRATION.md b/openspec/MIGRATION.md
deleted file mode 100644
index fa7333d..0000000
--- a/openspec/MIGRATION.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# OpenSpec Migration Record
-
-> **Date:** 2026-04-23
-> **From:** Custom SDD structure (`specs/`)
-> **To:** OpenSpec framework (`openspec/`)
-
----
-
-## Migration Summary
-
-Successfully migrated the Tiny-LLM project from a custom Spec-Driven Development structure to the OpenSpec framework.
-
----
-
-## What Changed
-
-### Directory Structure
-
-| Before | After | Status |
-|--------|-------|--------|
-| `specs/product/*.md` | `openspec/specs/<capability>/spec.md` | Migrated |
-| `specs/rfc/*.md` | `openspec/changes/archive/*/` | Archived |
-| `specs/api/*.yaml` | `openspec/schemas/api/` | Moved |
-| `specs/testing/*.feature` | Embedded in `spec.md` | Integrated |
-| `specs/db/*.dbml` | `openspec/schemas/db/` | Moved |
-| `specs/` | *Deleted* | Removed |
-
-### Workflow Commands
-
-| Before | After |
-|--------|-------|
-| Manual spec-first workflow | `/opsx:propose` |
-| No structured implementation tracking | `/opsx:apply` |
-| No archival process | `/opsx:archive` |
-
----
-
-## Artifacts Created
-
-### OpenSpec Configuration
-- `openspec/config.yaml` - Project configuration with C++/CUDA context
-
-### Capability Specs
-- `openspec/specs/inference-engine/spec.md` - Main inference engine specification
-
-### Archived Changes
-- `openspec/changes/archive/core-architecture/` - Original architecture RFC
-- `openspec/changes/archive/initial-implementation/` - Original implementation tasks
-
-### Supplementary Schemas
-- `openspec/schemas/api/inference-engine.yaml` - API contracts
-- `openspec/schemas/db/schema-v1.dbml` - Data models
-
-### Claude Code Integration
-- `.claude/skills/openspec-propose/SKILL.md`
-- `.claude/skills/openspec-apply-change/SKILL.md`
-- `.claude/skills/openspec-archive-change/SKILL.md`
-- `.claude/skills/openspec-explore/SKILL.md`
-
----
-
-## Key Improvements
-
-1. **Structured Workflow**: OpenSpec provides clear proposal → apply → archive cycle
-2. **Delta Specs**: Changes are tracked with ADDED/MODIFIED/REMOVED sections
-3. **AI Integration**: Built-in slash commands for Claude Code and 27+ other tools
-4. **RFC 2119 Keywords**: Mandatory requirements use SHALL/MUST, recommended use SHOULD
-5. **Scenario-based Testing**: Each requirement has test scenarios in GIVEN/WHEN/THEN format
-
----
-
-## Verification
-
-```bash
-# Validate all specs
-openspec validate --all
-# Result: 1 passed, 0 failed
-
-# List capability specs
-openspec list --specs
-# Result: inference-engine
-
-# Check OpenSpec version
-openspec --version
-# Result: 1.3.1
-```
-
----
-
-## Post-Migration Tasks
-
-- [x] Install OpenSpec CLI (`npm install -g @fission-ai/openspec@latest`)
-- [x] Initialize OpenSpec structure (`openspec init --tools claude`)
-- [x] Create `openspec/config.yaml`
-- [x] Migrate product specs to `openspec/specs/`
-- [x] Archive RFCs to `openspec/changes/archive/`
-- [x] Move API and DB schemas to `openspec/schemas/`
-- [x] Update `AGENTS.md` with OpenSpec workflow
-- [x] Delete original `specs/` directory
-- [x] Validate all specs pass
-
----
-
-## Future Development
-
-For all future development, use the OpenSpec workflow:
-
-1. **New Features**: `/opsx:propose <change-name>`
-2. **Implementation**: `/opsx:apply <change-name>`
-3. **Completion**: `/opsx:archive <change-name>`
-4. **Exploration**: `/opsx:explore`
-
-See `AGENTS.md` for detailed workflow documentation.
diff --git a/openspec/changes/archive/core-architecture/design.md b/openspec/changes/archive/core-architecture/design.md
deleted file mode 100644
index 9f72b6f..0000000
--- a/openspec/changes/archive/core-architecture/design.md
+++ /dev/null
@@ -1,148 +0,0 @@
-# Core Architecture Design
-
-> **Version:** 2.0.1 | **Date:** 2026-04-16 | **Status:** Implemented
-
-## Context
-
-This document captures the architectural decisions made during the initial implementation of the Tiny-LLM inference engine.
-
----
-
-## Goals / Non-Goals
-
-**Goals:**
-- Memory efficiency through INT8 weight quantization (~50% reduction)
-- Bandwidth optimization via register-level dequantization
-- Computational efficiency through warp shuffle and shared memory tiling
-- Extensibility for different model architectures
-
-**Non-Goals:**
-- Multi-GPU support (single GPU only)
-- Training capabilities (inference only)
-- Full precision fallback (W8A16 only)
-
----
-
-## Decisions
-
-### Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      Host (CPU)                             │
-│  Model Loader  │  Tokenizer  │  Generation Controller      │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                      Device (GPU)                           │
-│                                                             │
-│  ┌─ Memory ─────────────────────────────────────────────┐  │
-│  │  Weight Memory (INT8+Scales)  │  KV Cache  │  Activ  │  │
-│  └───────────────────────────────────────────────────────┘  │
-│                                                             │
-│  ┌─ Kernels ────────────────────────────────────────────┐  │
-│  │  W8A16 MatMul  │  Attention  │  RMSNorm  │  Elemwise │  │
-│  └───────────────────────────────────────────────────────┘  │
-│                                                             │
-│  ┌─ Transformer ────────────────────────────────────────┐  │
-│  │  Layer 1  →  Layer 2  →  ...  →  Layer N            │  │
-│  └───────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Core Components
-
-**Model Loader:**
-```cpp
-struct ModelConfig {
-    int vocab_size, hidden_dim, num_layers;
-    int num_heads, num_kv_heads, head_dim;
-    int intermediate_dim, max_seq_len;
-    float rope_theta, rms_norm_eps;
-};
-
-struct QuantizedWeight {
-    int8_t* data;      // INT8 weights
-    half* scales;      // Per-group scales
-    int rows, cols, group_size;
-};
-```
-
-**W8A16 MatMul:**
-- Formula: `output = input @ (weight_int8 * scales)`
-- Optimization: Shared memory tiling (TILE_M × TILE_N × BLOCK_K)
-- Optimization: Warp shuffle reduction
-- Optimization: Register-level dequantization
-
-**KV Cache Manager:**
-```cpp
-Result<int> allocateSequence(int max_len);
-void appendKV(seq_id, layer_idx, k, v, n);  // write-only
-void advanceSeqLen(seq_id, n);              // explicit advance
-void releaseSequence(int seq_id);
-```
-
-### Error Handling Pattern
-
-```cpp
-// CUDA error checking
-#define CUDA_CHECK(call) \
-    do { \
-        cudaError_t err = call; \
-        if (err != cudaSuccess) throw CudaException(err, __FILE__, __LINE__); \
-    } while(0)
-
-// Result type (monadic error handling)
-template<typename T>
-class Result {
-    static Result<T> ok(T value);
-    static Result<T> err(std::string message);
-    bool isOk() const;
-    T& value();
-    const std::string& error() const;
-};
-```
-
----
-
-## Risks / Trade-offs
-
-| Risk | Mitigation |
-|------|------------|
-| INT8 precision loss | Validate against FP16 baseline, maintain < 1% error |
-| GPU memory fragmentation | Pre-allocated KV cache pool |
-| CUDA version compatibility | Support CUDA 11.0+ with forward compatibility |
-
----
-
-## Test Strategy
-
-| Type | Framework | Coverage |
-|------|-----------|----------|
-| Unit Tests | GoogleTest | Concrete examples, edge cases |
-| Property Tests | RapidCheck | General correctness (100+ iterations) |
-| Integration Tests | GoogleTest | End-to-end inference |
-
----
-
-## File Structure
-
-```
-tiny-llm/
-├── include/tiny_llm/     # Public headers
-│   ├── types.h           # Core types
-│   ├── result.h          # Error handling
-│   ├── cuda_utils.h      # CUDA utilities
-│   ├── kv_cache.h        # KV Cache
-│   ├── transformer.h     # Transformer layer
-│   ├── model_loader.h    # Model loading
-│   └── inference_engine.h
-├── kernels/              # CUDA Kernels
-│   ├── w8a16_matmul.cu
-│   ├── attention.cu
-│   ├── rmsnorm.cu
-│   └── elementwise.cu
-├── src/                  # Implementation
-└── tests/                # Tests
-```
diff --git a/openspec/changes/archive/core-architecture/proposal.md b/openspec/changes/archive/core-architecture/proposal.md
deleted file mode 100644
index 44f9d9d..0000000
--- a/openspec/changes/archive/core-architecture/proposal.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Core Architecture
-
-## Why
-
-Establish a lightweight LLM inference engine optimized for CUDA GPUs, focusing on W8A16 quantization for memory efficiency and bandwidth optimization.
-
-## What Changes
-
-### New Capabilities
-- `inference-engine`: Complete W8A16 quantized inference with KV Cache
-
-## Impact
-
-- Defines core system architecture for all future development
-- Establishes CUDA kernel optimization patterns
-- Sets error handling conventions (Result<T> monadic pattern)
-
----
-
-## Status: Archived
-
-This proposal has been implemented. See `openspec/specs/inference-engine/` for current specifications.
diff --git a/openspec/changes/archive/initial-implementation/proposal.md b/openspec/changes/archive/initial-implementation/proposal.md
deleted file mode 100644
index 16592c3..0000000
--- a/openspec/changes/archive/initial-implementation/proposal.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Initial Implementation
-
-## Why
-
-Implement the core Tiny-LLM inference engine with W8A16 quantization and KV Cache for efficient LLM inference on CUDA GPUs.
-
-## What Changes
-
-### New Capabilities
-- `inference-engine`: Complete W8A16 quantized inference engine implementation
-
-## Impact
-
-- Establishes the complete codebase for Tiny-LLM
-- Implements all correctness properties (P1-P9)
-- Provides end-to-end inference capability
-
----
-
-## Status: Archived
-
-This implementation is complete. See `openspec/specs/inference-engine/` for current specifications and `tasks.md` for completed task details.
diff --git a/openspec/changes/archive/initial-implementation/tasks.md b/openspec/changes/archive/initial-implementation/tasks.md
deleted file mode 100644
index 153ef20..0000000
--- a/openspec/changes/archive/initial-implementation/tasks.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# Initial Implementation Tasks
-
-> **Version:** 2.0.1 | **Status:** ✅ Complete
-
----
-
-## Overview
-
-| Phase | Tasks | Status |
-|-------|-------|--------|
-| 1. Infrastructure | 3 | ✅ |
-| 2. Data Types | 2 | ✅ |
-| 3. Model Loading | 5 | ✅ |
-| 4. W8A16 | 4 | ✅ |
-| 5. KV Cache | 3 | ✅ |
-| 6. Attention | 4 | ✅ |
-| 7. Transformer | 3 | ✅ |
-| 8. Inference Engine | 5 | ✅ |
-| 9. Optimization | 3 | ✅ |
-| 10. Integration | 2 | ✅ |
-
----
-
-## Phase 1: Infrastructure ✅
-
-- [x] 1.1 Directory structure + CMake
-- [x] 1.2 CUDA error handling (CUDA_CHECK, Result<T>)
-- [x] 1.3 Error handling tests
-
-## Phase 2: Data Types ✅
-
-- [x] 2.1 ModelConfig, QuantizedWeight, TransformerWeights
-- [x] 2.2 Property test: Scale dimension consistency (P8)
-
-## Phase 3: Model Loading ✅
-
-- [x] 3.1 GGUF header parsing
-- [x] 3.2 Binary weight loading
-- [x] 3.3 GPU memory transfer
-- [x] 3.4 Property test: Corrupted file (P9)
-- [x] 3.5 Unit tests
-
-## Phase 4: W8A16 ✅
-
-- [x] 4.1 MatMul Kernel (tiling + dequant)
-- [x] 4.2 Warp shuffle optimization
-- [x] 4.3 Property test: Numerical precision (P1)
-- [x] 4.4 Unit tests
-
-## Phase 5: KV Cache ✅
-
-- [x] 5.1 Memory pool + slot management
-- [x] 5.2 allocate/append/release/getCache
-- [x] 5.3 Property test: Invariants (P2)
-
-## Phase 6: Attention ✅
-
-- [x] 6.1 RMSNorm Kernel
-- [x] 6.2 Property test: RMSNorm (P4)
-- [x] 6.3 Attention Kernel + causal masking
-- [x] 6.4 Property test: Causal masking (P3)
-
-## Phase 7: Transformer ✅
-
-- [x] 7.1 TransformerLayer (attention + FFN + residual)
-- [x] 7.2 KV Cache integration
-- [x] 7.3 Property test: Incremental decoding (P5)
-
-## Phase 8: Inference Engine ✅
-
-- [x] 8.1 prefill + decodeStep
-- [x] 8.2 Sampling strategies (greedy/temp/top-k/top-p)
-- [x] 8.3 Property test: Greedy sampling (P6)
-- [x] 8.4 Generation control + statistics
-- [x] 8.5 Property test: Length limit (P7)
-
-## Phase 9: Optimization ✅
-
-- [x] 9.1 Memory coalesced access
-- [x] 9.2 Block configuration optimization
-- [x] 9.3 CUDA streams
-
-## Phase 10: Integration ✅
-
-- [x] 10.1 Test models
-- [x] 10.2 End-to-end tests
-
----
-
-## Fixed Issues
-
-### v2.0.1 (2026-04-16)
-
-- [x] `test_integration.cu`: Scale dimension calculation error
-- [x] `attention.cu`: Removed unused code
-
----
-
-## Future Plans
-
-| Priority | Task | Status |
-|----------|------|--------|
-| P1 | Full GGUF runtime | Planned |
-| P2 | Configurable group_size | Planned |
-| P2 | Kernel error checking | Planned |
-| P3 | Paged Attention | Under evaluation |
diff --git a/openspec/changes/archive/normalize-archive-readiness/.openspec.yaml b/openspec/changes/archive/normalize-archive-readiness/.openspec.yaml
deleted file mode 100644
index 8b394c6..0000000
--- a/openspec/changes/archive/normalize-archive-readiness/.openspec.yaml
+++ /dev/null
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-04-23
diff --git a/openspec/changes/archive/normalize-archive-readiness/design.md b/openspec/changes/archive/normalize-archive-readiness/design.md
deleted file mode 100644
index bf49971..0000000
--- a/openspec/changes/archive/normalize-archive-readiness/design.md
+++ /dev/null
@@ -1,127 +0,0 @@
-## Context
-
-Tiny-LLM is a CUDA/C++ inference engine whose repository recently migrated from a custom `specs/` layout to OpenSpec. The migration created the right core structure, but several high-signal repository surfaces still point in different directions:
-
-- contributor guidance still mixes legacy `specs/` instructions with OpenSpec
-- GitHub Actions are more complex than the project's current maintenance intent and CI currently mutates the branch
-- README, changelog, GitHub Pages, and GitHub metadata are not yet aligned around a focused, archive-ready project story
-- AI-tooling guidance is fragmented across `AGENTS.md`, personal `CLAUDE.local.md`, OpenSpec Claude commands, and missing project-level Copilot/Claude guidance
-- the working tree already contains user edits, so cleanup must be precise rather than destructive-by-default in execution order
-
-This change is cross-cutting: it touches repository governance, documentation architecture, automation, public presentation, and the operator workflow used by AI agents during the project's final hardening phase.
-
-## Goals / Non-Goals
-
-**Goals:**
-- Make OpenSpec the single authoritative planning and change-management spine.
-- Reduce repository drift by removing stale guidance, duplicated docs, and low-value workflow behavior.
-- Redesign public and contributor-facing surfaces so they reflect the actual project state and maintenance goals.
-- Standardize the AI-assisted development model for this repository with a small number of project-specific instruction files.
-- Establish a practical developer tooling baseline for a C++17/CUDA project, including LSP guidance and low-friction hooks.
-- Leave the repository in a cleaner, lower-noise state suitable for final bug-fixing and later low-maintenance archival mode.
-
-**Non-Goals:**
-- Expanding Tiny-LLM into a broader feature roadmap or reviving speculative roadmap items.
-- Introducing heavy new platform dependencies, large MCP/plugin stacks, or complex developer infrastructure.
-- Rewriting stable core CUDA architecture without evidence from the later bug audit.
-- Supporting every AI editor/runtime equally with bespoke configuration if shared guidance is sufficient.
-
-## Decisions
-
-### 1. Use a single umbrella OpenSpec change for repository normalization
-
-This work spans multiple repository surfaces that need to stay coordinated. A single umbrella change keeps proposal, design, specs, and tasks unified while still allowing the implementation to proceed in narrow phases.
-
-**Alternatives considered**
-- **Many small changes**: lower local scope, but higher drift risk and weaker overall architecture control.
-- **Ad hoc edits without a change**: faster initially, but contradicts the stated OpenSpec-first workflow.
-
-### 2. Treat aggressive cleanup as the default content strategy
-
-The user explicitly prefers aggressive cleanup. The implementation will therefore bias toward deleting, merging, or rewriting low-value documents and redundant workflow behavior instead of preserving them for historical completeness.
-
-**Alternatives considered**
-- **Preserve most files and only patch references**: safer short-term, but leaves the repository bloated and internally inconsistent.
-- **Freeze current docs and only add new meta-docs**: increases duplication and does not solve drift.
-
-### 3. Separate repository-governance concerns from inference-engine behavior
-
-This change introduces new governance-oriented capabilities instead of overloading the existing `inference-engine` capability with repository process requirements. Code bug fixing discovered later should primarily align implementation to the existing engine spec unless a genuine behavior change is required.
-
-**Alternatives considered**
-- **Modify `inference-engine` now**: possible, but would mix repository-operating concerns into product behavior and create premature spec churn.
-
-### 4. Make CI non-mutating and reduce automation noise
-
-Validation pipelines should check quality and fail loudly; they should not auto-format files and commit back to the branch. This reduces surprise, avoids noisy workflow loops, and better fits a final-hardening repository.
-
-**Alternatives considered**
-- **Keep auto-format-on-push**: convenient for style drift, but high-noise and risky during stabilization.
-- **Add more automation layers**: likely over-engineering for a project moving toward low maintenance.
-
-### 5. Reframe GitHub Pages and README surfaces around credibility and conversion
-
-The public project surface should do four things well: explain what Tiny-LLM is, show why it matters, establish its implementation maturity, and guide the right next step. Pages should not exist merely as a prettier README mirror.
-
-**Alternatives considered**
-- **Keep the current docs-heavy site mostly intact**: less work, but still under-optimized for attracting and orienting new users.
-- **Remove Pages entirely**: would simplify maintenance, but loses a valuable project showcase and homepage target for GitHub metadata.
-
-### 6. Use a minimal, project-specific AI tooling stack
-
-The canonical project instruction surfaces will be:
-- OpenSpec artifacts
-- `AGENTS.md`
-- project `CLAUDE.md`
-- project-level Copilot instructions
-
-Supplementary tool-specific configuration should only be added when it produces a concrete, repository-specific gain.
-
-**Alternatives considered**
-- **Many parallel instruction files for every tool**: higher maintenance, more drift, weak signal.
-- **No project-level AI guidance**: leaves agents relying on generic behavior and increases repository-specific mistakes.
-
-### 7. Standardize on clangd plus compile_commands.json for LSP
-
-For this C++17/CUDA repository, `clangd` backed by `compile_commands.json` is the most portable baseline across editors and AI tooling ecosystems. This becomes the default recommendation unless a tool requires a thin compatibility layer.
-
-**Alternatives considered**
-- **Tool-specific LSP setups**: more fragmentation and duplicated guidance.
-- **No explicit LSP baseline**: leads to inconsistent indexing and weaker editing assistance.
-
-### 8. Keep MCP optional and narrow
-
-MCP should be used only where it materially improves repository operations over existing built-in tools such as `gh`, GitHub integrations, or local CLI commands. This avoids context bloat and unnecessary runtime complexity.
-
-**Alternatives considered**
-- **Broad MCP adoption**: potentially powerful, but high context and maintenance overhead for limited payoff in this repository.
-
-### 9. Update GitHub metadata only after content surfaces stabilize
-
-Repository description, homepage URL, and topics should be updated with `gh` after README and Pages positioning are finalized so the public metadata points at the correct, polished destination.
-
-**Alternatives considered**
-- **Update metadata first**: creates temporary mismatch between GitHub summary and repo/site content.
-
-## Risks / Trade-offs
-
-- **Dirty working tree conflicts** -> Reconcile user-owned changes first and avoid blanket rewrites in touched files.
-- **Cleanup scope becomes too broad** -> Execute in dependency-aware phases and define explicit completion criteria per workstream.
-- **Accidentally removing useful historical context** -> Preserve only high-signal history through OpenSpec archive, meaningful changelog entries, and curated release notes.
-- **Workflow simplification breaks expected automation** -> Re-validate build, tests, and Pages behavior after each major automation change.
-- **Tooling guidance becomes too generic** -> Keep instructions tied to Tiny-LLM's actual stack and maintenance goal.
-- **GitHub metadata drifts again later** -> Make metadata alignment part of the final closure playbook.
-
-## Migration Plan
-
-1. Reconcile the current dirty repository state and establish the baseline audit.
-2. Normalize OpenSpec and contributor-governance surfaces first so later edits follow one workflow.
-3. Simplify workflows, hooks, and engineering config before relying on them for further cleanup.
-4. Redesign README, changelog policy, Pages content, and GitHub metadata as one public-surface pass.
-5. Standardize AI/tooling guidance and then run the repository-wide bug/drift audit.
-6. Finish with a closure playbook that defines the lightweight future maintenance path.
-
-## Open Questions
-
-- Which existing website/doc pages survive aggressive cleanup versus being merged into fewer, higher-signal entry points?
-- Which GitHub topics best balance discoverability with accuracy for a CUDA/C++ inference engine nearing archival mode?
diff --git a/openspec/changes/archive/normalize-archive-readiness/proposal.md b/openspec/changes/archive/normalize-archive-readiness/proposal.md
deleted file mode 100644
index f7a37c5..0000000
--- a/openspec/changes/archive/normalize-archive-readiness/proposal.md
+++ /dev/null
@@ -1,30 +0,0 @@
-## Why
-
-Tiny-LLM has completed a partial migration to OpenSpec, but the repository still behaves like a project with mixed governance models, duplicated documentation layers, and overbuilt automation. Before the project can be finished strongly and moved toward low-maintenance archival mode, its repository structure, contributor workflow, public presentation, and AI-assisted development guidance need to be normalized around a smaller, more coherent operating model.
-
-## What Changes
-
-- Create an OpenSpec-driven cleanup program that governs repository structure, document quality, and archive-readiness.
-- Replace remaining legacy `specs/` references and mixed workflow guidance with a single OpenSpec-first development flow.
-- Redesign AI collaboration guidance around project-specific `AGENTS.md`, project-level `CLAUDE.md`, and Copilot instructions, while keeping tool surface area minimal.
-- Simplify GitHub Actions so CI validates quality instead of mutating the branch, and reduce noisy or redundant workflow behavior.
-- Reposition GitHub Pages, README surfaces, changelog usage, and GitHub metadata so the project presents a focused, credible public surface.
-- Define the preferred local development/tooling baseline for this C++/CUDA repository, including hooks, LSP strategy, review flow, and the trade-offs around MCP/plugins.
-- Audit and fix repository drift, stale claims, and real defects uncovered during normalization.
-
-## Capabilities
-
-### New Capabilities
-- `repository-governance`: Defines the required repository structure, OpenSpec-first governance, documentation quality bar, and workflow simplification rules for Tiny-LLM.
-- `ai-assisted-development`: Defines the project-specific operating model for OpenSpec, AGENTS/CLAUDE/Copilot guidance, review checkpoints, subagent usage, and low-noise automation.
-- `project-presentation`: Defines how README, GitHub Pages, changelog surfaces, and GitHub metadata should present the project to new users and future maintainers.
-
-### Modified Capabilities
-- None.
-
-## Impact
-
-- Affects `openspec/`, `AGENTS.md`, contributor docs, README surfaces, website content, and `.github/workflows/*`.
-- Introduces project-level AI guidance artifacts and a clearer local development baseline.
-- May remove low-value or duplicated documents, changelog entries, and workflow behavior as part of aggressive cleanup.
-- Drives subsequent bug-fixing and repository hardening work from a single OpenSpec change instead of ad hoc edits.
diff --git a/openspec/changes/archive/normalize-archive-readiness/specs/ai-assisted-development/spec.md b/openspec/changes/archive/normalize-archive-readiness/specs/ai-assisted-development/spec.md
deleted file mode 100644
index cc4c136..0000000
--- a/openspec/changes/archive/normalize-archive-readiness/specs/ai-assisted-development/spec.md
+++ /dev/null
@@ -1,34 +0,0 @@
-## ADDED Requirements
-
-### Requirement: The repository SHALL provide a clear project-specific AI instruction hierarchy
-Tiny-LLM SHALL define a compact, project-specific instruction hierarchy for AI-assisted development. `AGENTS.md`, project `CLAUDE.md`, OpenSpec artifacts, and project-level Copilot instructions SHALL be internally consistent and SHALL identify the repository's authoritative workflow, quality expectations, and scope boundaries.
-
-#### Scenario: An AI agent starts work
-- **WHEN** an AI agent reads repository guidance before making changes
-- **THEN** it SHALL be able to identify the authoritative workflow, current architectural constraints, and where project-specific instructions live
-
-#### Scenario: Local-only configuration coexists with project guidance
-- **WHEN** a local or personal instruction file exists alongside project-level guidance
-- **THEN** repository documentation SHALL make clear that local-only files do not override the project's authoritative rules
-
-### Requirement: AI-assisted development SHALL follow an OpenSpec-centered operating model
-AI-assisted work on Tiny-LLM SHALL use an OpenSpec-centered operating model: explore or propose first for non-trivial changes, apply against explicit tasks, and use review checkpoints before concluding major repository-wide edits. The operating model SHALL prefer long-running single-session execution over unnecessary parallel fleet usage and SHALL document when `/review` and subagents are appropriate.
-
-#### Scenario: A non-trivial cleanup is requested
-- **WHEN** an agent is asked to make a cross-cutting repository change
-- **THEN** it SHALL anchor the work in an OpenSpec change with explicit tasks before broad implementation begins
-
-#### Scenario: Review checkpoint is needed
-- **WHEN** a major workstream such as workflow redesign, governance rewrite, or public-site repositioning is completed
-- **THEN** the documented process SHALL require a review-oriented checkpoint before finalizing the workstream
-
-### Requirement: Developer tooling guidance SHALL standardize LSP and right-size integrations
-The project SHALL standardize on `clangd` plus `compile_commands.json` as the default LSP path for local development in this C++17/CUDA repository. Tooling guidance SHALL explain that this baseline is reusable across supported editors and AI coding tools, while MCP servers, plugins, and extra integrations SHALL remain optional and SHALL be adopted only when they provide clear repository-specific value.
-
-#### Scenario: A developer configures local intelligence tools
-- **WHEN** a developer or AI tool needs language-aware navigation for Tiny-LLM
-- **THEN** the project guidance SHALL direct them to the canonical `clangd` plus `compile_commands.json` setup
-
-#### Scenario: A new integration is considered
-- **WHEN** a plugin, MCP server, or tool-specific integration is proposed
-- **THEN** it SHALL be adopted only if its value exceeds the added maintenance and context cost
diff --git a/openspec/changes/archive/normalize-archive-readiness/specs/project-presentation/spec.md b/openspec/changes/archive/normalize-archive-readiness/specs/project-presentation/spec.md
deleted file mode 100644
index 4e34aa3..0000000
--- a/openspec/changes/archive/normalize-archive-readiness/specs/project-presentation/spec.md
+++ /dev/null
@@ -1,34 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Public project surfaces SHALL present one focused project identity
-The repository README, GitHub description/about, homepage URL, and repository topics SHALL present a consistent explanation of what Tiny-LLM is, what it is good at, and how a new user should evaluate or start with it. Public messaging SHALL avoid stale roadmap inflation, duplicated positioning, and unsupported claims.
-
-#### Scenario: A new user lands on the repository
-- **WHEN** a user reads the README or GitHub About section
-- **THEN** they SHALL see a concise, consistent description of Tiny-LLM's purpose, maturity, and next-step links
-
-#### Scenario: Public claims are reviewed
-- **WHEN** a feature, performance, or roadmap claim cannot be supported by the repository's current implementation or validated documentation
-- **THEN** that claim SHALL be revised or removed from the public project surface
-
-### Requirement: GitHub Pages SHALL act as a focused showcase and onboarding surface
-The GitHub Pages site SHALL exist to attract, orient, and qualify new users. Its homepage and key entry pages SHALL emphasize Tiny-LLM's value proposition, architecture, implementation maturity, and developer entry points rather than functioning as a low-signal mirror of repository documents.
-
-#### Scenario: A visitor opens the homepage
-- **WHEN** a visitor lands on the GitHub Pages root
-- **THEN** the page SHALL communicate the project's value proposition, technical strengths, and primary calls to action within the first screenful
-
-#### Scenario: The site duplicates repository content
-- **WHEN** a Pages section provides little value beyond copying README text or low-signal historical content
-- **THEN** it SHALL be removed, merged, or redesigned into a higher-signal entry point
-
-### Requirement: Changelog and release surfaces SHALL stay high-signal
-Changelog pages, release notes, and related navigation SHALL focus on meaningful user-facing or maintainer-relevant changes. Low-value, noisy, or repetitive entries SHALL be consolidated or removed, and the remaining surfaces SHALL support a low-maintenance archival trajectory.
-
-#### Scenario: A change is considered for the changelog
-- **WHEN** a change does not materially affect users, maintainers, or the public understanding of the project
-- **THEN** it SHALL not receive a standalone changelog surface
-
-#### Scenario: Release history is presented
-- **WHEN** a reader browses release or changelog surfaces
-- **THEN** they SHALL encounter a concise history that highlights meaningful milestones instead of workflow noise
diff --git a/openspec/changes/archive/normalize-archive-readiness/specs/repository-governance/spec.md b/openspec/changes/archive/normalize-archive-readiness/specs/repository-governance/spec.md
deleted file mode 100644
index bafa8de..0000000
--- a/openspec/changes/archive/normalize-archive-readiness/specs/repository-governance/spec.md
+++ /dev/null
@@ -1,45 +0,0 @@
-## ADDED Requirements
-
-### Requirement: OpenSpec SHALL be the canonical change-management workflow
-The repository SHALL use OpenSpec as the only normative workflow for non-trivial changes, repository restructuring, and cross-cutting cleanup. Contributor-facing guidance SHALL reference `openspec/` paths and OpenSpec commands instead of legacy `specs/` structures or ad hoc spec-first instructions.
-
-#### Scenario: Cross-cutting change is prepared
-- **WHEN** a contributor begins a repository-wide or behavior-affecting change
-- **THEN** an active OpenSpec change SHALL exist before implementation proceeds
-
-#### Scenario: Contributor guidance references the workflow
-- **WHEN** a user reads project workflow documentation
-- **THEN** the documentation SHALL reference only the canonical OpenSpec workflow and current repository structure
-
-### Requirement: Repository structure SHALL stay coherent with documented ownership
-The repository SHALL maintain a clear and current mapping between top-level directories, their purpose, and the documents that govern them. Legacy or misleading references to removed directories, obsolete ownership models, or personal-only configuration SHALL be removed from project-level guidance.
-
-#### Scenario: Repository layout is described
-- **WHEN** a top-level guide describes the repository structure
-- **THEN** every referenced directory or file SHALL exist and match its documented purpose
-
-#### Scenario: Personal configuration is distinguished
-- **WHEN** the repository includes both project-level and personal/local configuration files
-- **THEN** project-level guidance SHALL identify which files are authoritative for the repository and which are local-only
-
-### Requirement: Repository automation SHALL be low-noise and non-mutating
-Continuous integration, release, and documentation workflows SHALL validate repository state without auto-committing back to the branch. Workflow triggers, jobs, and output SHALL be minimized to the smallest set that preserves confidence in buildability, correctness, and public-site integrity.
-
-#### Scenario: CI validates source quality
-- **WHEN** a CI workflow checks formatting, buildability, or tests
-- **THEN** it SHALL report failures directly instead of rewriting tracked files and creating commits
-
-#### Scenario: Workflow inventory is reviewed
-- **WHEN** a repository workflow provides no meaningful quality, release, or presentation value
-- **THEN** it SHALL be removed, simplified, or merged into a higher-signal workflow
-
-### Requirement: Repository documents SHALL be aggressively pruned for signal
-Project-level documentation SHALL prioritize Tiny-LLM-specific, actionable guidance. Low-value, duplicated, stale, or generic documents SHALL be deleted, merged, or rewritten so the repository becomes smaller and more coherent over time.
-
-#### Scenario: Duplicate guidance exists
-- **WHEN** two or more documents explain the same workflow or project concept
-- **THEN** the repository SHALL retain one authoritative version and remove or redirect the rest
-
-#### Scenario: Stale content is discovered
-- **WHEN** a document contains outdated structure, roadmap, or process claims
-- **THEN** that content SHALL be corrected or removed before the cleanup change is considered complete
diff --git a/openspec/changes/archive/normalize-archive-readiness/tasks.md b/openspec/changes/archive/normalize-archive-readiness/tasks.md
deleted file mode 100644
index 8b9ff11..0000000
--- a/openspec/changes/archive/normalize-archive-readiness/tasks.md
+++ /dev/null
@@ -1,36 +0,0 @@
-## 1. Baseline audit
-
-- [x] 1.1 Inventory the dirty working tree, legacy `specs/` references, active docs drift, workflow sprawl, and site/public-surface inconsistencies
-- [x] 1.2 Run the current CMake configure/build/test flow and capture baseline failures, warnings, and environment/tooling gaps
-- [x] 1.3 Inspect current GitHub metadata, Pages configuration, and workflow behavior so later cleanup is grounded in actual repository state
-
-## 2. OpenSpec and governance normalization
-
-- [x] 2.1 Align OpenSpec migration artifacts, repository structure references, and governance docs so OpenSpec is the only canonical workflow
-- [x] 2.2 Rewrite contributor-facing workflow guidance to remove legacy `specs/` paths and define a closure-oriented development process
-- [x] 2.3 Define the repository cleanup policy for low-value docs, non-mutating CI, and authoritative project-level guidance files
-
-## 3. AI instruction and tooling baseline
-
-- [x] 3.1 Curate `AGENTS.md` and create a project-level `CLAUDE.md` that capture Tiny-LLM-specific workflow, constraints, and review expectations
-- [x] 3.2 Add concise project-level Copilot instructions and align them with OpenSpec, review, subagent, and autopilot usage guidance
-- [x] 3.3 Standardize the developer tooling baseline for `clangd` + `compile_commands.json`, lightweight hooks, and optional MCP/plugin usage
-
-## 4. Workflow and engineering configuration simplification
-
-- [x] 4.1 Redesign CI so it validates formatting, buildability, and tests without mutating tracked files or auto-committing changes
-- [x] 4.2 Simplify Pages and Release workflows, triggers, and supporting config to match a lower-noise archive-ready maintenance model
-- [x] 4.3 Rationalize root engineering config such as `.gitignore`, local setup guidance, and related repository-quality files
-
-## 5. Documentation and public-surface redesign
-
-- [x] 5.1 Rewrite `README.md` and `README.zh-CN.md` around the final project positioning and remove stale roadmap or structure claims
-- [x] 5.2 Prune or merge low-value docs, changelog surfaces, and supporting pages so the documentation tree becomes smaller and higher-signal
-- [x] 5.3 Reposition GitHub Pages as a focused showcase/onboarding surface with stronger value proposition, architecture framing, and calls to action
-
-## 6. Metadata alignment, bug remediation, and closure
-
-- [x] 6.1 Update GitHub repository description, homepage URL, and topics with `gh` after README and Pages messaging are finalized
-- [x] 6.2 Re-audit code/spec/doc drift and fix real defects or inconsistencies surfaced by the normalization work
-- [x] 6.3 Re-run formatting, build, tests, and site validation, then resolve any regressions introduced by the cleanup
-- [x] 6.4 Write the final lightweight closure playbook and prepare the change for archive once the repository is coherent
diff --git a/openspec/changes/harden-gguf-contracts/design.md b/openspec/changes/harden-gguf-contracts/design.md
deleted file mode 100644
index 49f62a3..0000000
--- a/openspec/changes/harden-gguf-contracts/design.md
+++ /dev/null
@@ -1,63 +0,0 @@
-## Context
-
-The repository is in final hardening mode. For this phase, honest failure is better than partial runtime optimism. The current GGUF host-side path violates that principle in three ways:
-
-1. integer sizes from GGUF metadata/tensor descriptors are trusted too long
-2. runtime tensor validation happens after CUDA allocation starts
-3. schema mapping mixes valid configuration keys with unrelated metadata fallbacks
-
-These problems are tightly coupled and live behind one shallow seam: `GGUFParser` + `ModelLoader::loadGGUF`.
-
-## Goals / Non-Goals
-
-**Goals:**
-- Fail malformed or oversized GGUF inputs with `Result<T>` errors, not host exceptions.
-- Validate runtime-required tensors before any CUDA allocation.
-- Keep the GGUF host-side seam smaller and more honest.
-- Add regression coverage for hostile and incomplete GGUF fixtures.
-
-**Non-Goals:**
-- Full GGUF runtime support for every quantization format.
-- Reworking CUDA kernels or broader inference-engine execution flow.
-- Changing binary model loading behavior.
-
-## Decisions
-
-### 1. Add explicit overflow guards in GGUF size math
-
-`GGUFTensorInfo::numElements()`, `GGUFTensorInfo::calculateSize()`, and GGUF array readers will reject sizes that overflow `size_t` or exceed safe allocation math.
-
-Why:
-- This converts malicious/untrusted metadata into structured parse errors.
-- It keeps the parser as deep module: callers do not need to duplicate size-validation logic.
-
-### 2. Validate GGUF runtime completeness before CUDA allocation
-
-`ModelLoader::loadGGUF()` will build a required-tensor checklist from the extracted `ModelConfig` and return an error if required runtime tensors are missing or unsupported.
-
-Why:
-- Missing tensors are input-validation failures, not CUDA failures.
-- This concentrates loader policy in one place and removes fake-success zero placeholders from the public seam.
-
-### 3. Remove schema-invalid config fallback behavior
-
-`GGUFParser::extractModelConfig()` will stop treating unrelated metadata like `general.architecture` as numeric dimension fallbacks.
-
-Why:
-- `general.architecture` is architecture identity, not `hidden_dim`.
-- Keeping schema mapping strict improves locality and makes malformed GGUF behavior predictable.
-
-## Risks / Trade-offs
-
-- Some GGUF files that previously limped through with zero-filled placeholders will now fail early. This is intentional hardening.
-- Tests must use host-side fixtures that fail before CUDA allocation when the environment lacks a working GPU/runtime.
-
-## Verification Plan
-
-1. Add failing host-side tests for:
-   - tensor-size overflow guards
-   - oversized GGUF arrays
-   - invalid config fallback behavior
-   - incomplete GGUF runtime tensors returning `Result` errors without throwing
-2. Implement minimal production changes to satisfy those tests.
-3. Run the focused test target plus strongest available repository verification commands.
diff --git a/openspec/changes/harden-gguf-contracts/proposal.md b/openspec/changes/harden-gguf-contracts/proposal.md
deleted file mode 100644
index a5d59c1..0000000
--- a/openspec/changes/harden-gguf-contracts/proposal.md
+++ /dev/null
@@ -1,22 +0,0 @@
-## Why
-
-Tiny-LLM's GGUF host-side path is currently too forgiving and too shallow. The parser accepts untrusted sizes without enough overflow protection, the loader validates required runtime tensors only after it starts allocating CUDA memory, and malformed metadata can influence `ModelConfig` in ways that do not reflect the GGUF schema. In practice this means crafted or incomplete GGUF files can trigger exceptions, oversized allocations, or fake-success paths instead of returning a clean `Result<T>` error.
-
-## What Changes
-
-- Harden GGUF parsing against integer-overflow and oversized-allocation paths.
-- Make GGUF runtime loading validate required metadata and tensor presence before any CUDA allocation.
-- Remove misleading fallback behavior in GGUF-to-`ModelConfig` mapping.
-- Add regression tests for hostile/malformed GGUF inputs and incomplete runtime artifacts.
-- Align the inference-engine capability delta with the stricter GGUF contract.
-
-## Capabilities
-
-### Modified Capabilities
-- `inference-engine`: Tightens GGUF parsing and runtime-loading failure behavior so malformed or incomplete files fail explicitly instead of throwing or silently synthesizing invalid weights.
-
-## Impact
-
-- Affects `src/gguf_parser.cpp`, `src/model_loader.cpp`, and related tests.
-- Adds stricter failure behavior for malformed/incomplete GGUF inputs.
-- Improves alignment between `Result<T>`-based error handling and the actual GGUF host-side path.
diff --git a/openspec/changes/harden-gguf-contracts/specs/inference-engine/spec.md b/openspec/changes/harden-gguf-contracts/specs/inference-engine/spec.md
deleted file mode 100644
index ad788d4..0000000
--- a/openspec/changes/harden-gguf-contracts/specs/inference-engine/spec.md
+++ /dev/null
@@ -1,28 +0,0 @@
-## MODIFIED Requirements
-
-### Requirement: Model Loading
-
-The system SHALL parse and load model files with explicit validation of malformed, incomplete, or unsupported GGUF inputs before runtime allocation begins.
-
-1. The system SHALL parse GGUF file headers and configuration metadata.
-2. The system SHALL reject GGUF metadata, tensor dimensions, or array sizes that overflow safe allocation math.
-3. The system SHALL validate that required runtime tensors are present before allocating CUDA memory for GGUF runtime loading.
-4. The system SHALL return a structured error for corrupted, invalid, incomplete, or unsupported model files.
-5. The system SHALL provide a structured model representation including `ModelConfig` and `QuantizedWeight` structures.
-
-#### Scenario: Reject oversized GGUF tensor metadata
-- **GIVEN** a GGUF tensor descriptor or metadata array whose size computation would overflow
-- **WHEN** the parser reads the file
-- **THEN** parsing SHALL fail with a structured error
-- **AND** the parser SHALL NOT attempt an undersized allocation
-
-#### Scenario: Reject incomplete GGUF runtime tensor sets
-- **GIVEN** a GGUF file that parses successfully but omits tensors required for runtime inference
-- **WHEN** `ModelLoader::loadGGUF()` is called
-- **THEN** the loader SHALL return an error describing the missing or unsupported tensors
-- **AND** it SHALL fail before starting CUDA allocations for model weights
-
-#### Scenario: Ignore unrelated metadata fallbacks
-- **GIVEN** GGUF metadata that includes unrelated keys such as `general.architecture`
-- **WHEN** `extractModelConfig()` maps metadata into `ModelConfig`
-- **THEN** unrelated keys SHALL NOT override numeric model dimensions
diff --git a/openspec/changes/harden-gguf-contracts/tasks.md b/openspec/changes/harden-gguf-contracts/tasks.md
deleted file mode 100644
index 51634ac..0000000
--- a/openspec/changes/harden-gguf-contracts/tasks.md
+++ /dev/null
@@ -1,17 +0,0 @@
-## 1. GGUF parser overflow hardening
-
-- [ ] 1.1 Add failing tests for tensor-size overflow and oversized GGUF arrays
-- [ ] 1.2 Guard `numElements()`, `calculateSize()`, and array byte-count math against overflow
-- [ ] 1.3 Re-run the focused GGUF/parser tests
-
-## 2. GGUF config and runtime contract hardening
-
-- [ ] 2.1 Add failing tests for invalid metadata fallback and incomplete runtime tensor sets
-- [ ] 2.2 Make `extractModelConfig()` ignore unrelated metadata fallbacks
-- [ ] 2.3 Make `ModelLoader::loadGGUF()` validate required tensors before CUDA allocation and fail with `Result` errors
-- [ ] 2.4 Re-run the focused GGUF/model-loader tests
-
-## 3. Spec and verification alignment
-
-- [ ] 3.1 Update the inference-engine change delta to describe the stricter GGUF contract
-- [ ] 3.2 Run repository verification commands or strongest available substitutes and record environment limits
diff --git a/openspec/config.yaml b/openspec/config.yaml
deleted file mode 100644
index a94008c..0000000
--- a/openspec/config.yaml
+++ /dev/null
@@ -1,25 +0,0 @@
-schema: spec-driven
-
-context: |
-  Tech stack: C++17, CUDA C++17, CMake 3.18+
-  GPU: CUDA 11.0+, Compute Capability 7.0+ (Volta+)
-  Testing: GoogleTest v1.14.0, RapidCheck (property-based)
-  Logging: spdlog v1.12.0
-  Code Style: clang-format 18 (LLVM style, 100 col limit)
-  Package Manager: CMake FetchContent
-
-  Project: Tiny-LLM - A CUDA C++ library for LLM inference with W8A16 quantization.
-
-rules:
-  specs:
-  - Include test scenarios linked to correctness properties (P1-P9)
-  - "Use RFC 2119 keywords: SHALL/MUST (mandatory), SHOULD (recommended), MAY (optional)"
-  - Reference API schemas in openspec/schemas/api/ for interface contracts
-  design:
-  - Document CUDA kernel optimization decisions
-  - Specify memory layout and quantization approach
-  - Consider GPU memory constraints and kernel efficiency
-  tasks:
-  - Verify build with cmake before marking complete
-  - Run GoogleTest suite after implementation
-  - Ensure clang-format compliance
diff --git a/openspec/schemas/api/inference-engine.yaml b/openspec/schemas/api/inference-engine.yaml
deleted file mode 100644
index 70022af..0000000
--- a/openspec/schemas/api/inference-engine.yaml
+++ /dev/null
@@ -1,77 +0,0 @@
-# Tiny-LLM API Specification
-# Human-readable API definition for the inference engine
-
-## Core Types
-
-### ModelConfig
-Configuration for loading a Transformer model.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| vocab_size | int | Vocabulary size |
-| hidden_dim | int | Hidden dimension |
-| num_layers | int | Number of Transformer layers |
-| num_heads | int | Number of attention heads |
-| num_kv_heads | int | Number of KV heads (for GQA) |
-| head_dim | int | Dimension per head |
-| intermediate_dim | int | FFN intermediate dimension |
-| max_seq_len | int | Maximum sequence length |
-| rope_theta | float | RoPE theta |
-| rms_norm_eps | float | RMSNorm epsilon |
-
-### GenerationConfig
-Configuration for text generation.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| max_new_tokens | int | Maximum tokens to generate |
-| temperature | float | Sampling temperature |
-| top_k | int | Top-k sampling parameter |
-| top_p | float | Top-p (nucleus) sampling parameter |
-| eos_token_id | int | End-of-sequence token ID |
-
-## Public API
-
-### InferenceEngine::load(path, config) -> Result<InferenceEngine>
-Load a model from file path with given configuration.
-
-**Parameters:**
-- `path`: Model file path (string)
-- `config`: ModelConfig struct
-
-**Returns:**
-- `Result<InferenceEngine>`: Engine instance or error
-
-**Errors:**
-- File not found
-- Corrupted model file
-- GPU memory allocation failure
-- Invalid model dimensions
-
-### InferenceEngine::generate(tokens, config) -> vector<int>
-Generate tokens from a prompt.
-
-**Parameters:**
-- `tokens`: Input token IDs (vector<int>)
-- `config`: GenerationConfig struct
-
-**Returns:**
-- Generated token sequence including input tokens
-
-### InferenceEngine::prefill(tokens) -> void
-Process input tokens in parallel (prefill phase).
-
-### InferenceEngine::decodeStep(config) -> int
-Generate a single token (decode phase).
-
-**Returns:**
-- Next token ID
-
-## Error Types
-
-| Error | Description |
-|-------|-------------|
-| CudaException | CUDA runtime error with file and line |
-| ModelLoadError | Failed to load or validate model |
-| OutOfMemoryError | GPU memory exhausted |
-| InvalidModelError | Model file corrupted or invalid |
diff --git a/openspec/schemas/db/schema-v1.dbml b/openspec/schemas/db/schema-v1.dbml
deleted file mode 100644
index dfb0e2e..0000000
--- a/openspec/schemas/db/schema-v1.dbml
+++ /dev/null
@@ -1,178 +0,0 @@
-// Tiny-LLM Model Schema
-// DBML-style definition for model architecture and data structures
-// Version: 2.0.1 | Last Updated: 2026-04-17
-
-// =============================================================================
-// Core Configuration Models
-// =============================================================================
-
-Table model_config {
-  vocab_size int [not null, default: 32000, note: "Vocabulary size"]
-  hidden_dim int [not null, default: 4096, note: "Hidden dimension (d_model)"]
-  num_layers int [not null, default: 32, note: "Number of Transformer layers"]
-  num_heads int [not null, default: 32, note: "Number of attention heads"]
-  num_kv_heads int [not null, default: 32, note: "Number of KV heads (GQA)"]
-  head_dim int [not null, default: 128, note: "Dimension per attention head"]
-  intermediate_dim int [not null, default: 11008, note: "FFN intermediate dimension"]
-  max_seq_len int [not null, default: 2048, note: "Maximum sequence length"]
-  rope_theta float [not null, default: 10000.0, note: "RoPE theta parameter"]
-  rms_norm_eps float [not null, default: 1e-5, note: "RMSNorm epsilon"]
-  eos_token_id int [not null, default: 2, note: "End-of-sequence token ID"]
-  bos_token_id int [not null, default: 1, note: "Beginning-of-sequence token ID"]
-}
-
-Table quantization_params {
-  group_size int [not null, default: 128, note: "Elements per scale factor"]
-  symmetric bool [not null, default: true, note: "Symmetric quantization (no zero point)"]
-}
-
-// =============================================================================
-// Weight Tensor Models
-// =============================================================================
-
-Table quantized_weight {
-  id int [pk]
-  name varchar [not null, note: "Weight tensor name"]
-  rows int [not null, note: "Number of rows (output dimension)"]
-  cols int [not null, note: "Number of columns (input dimension)"]
-  group_size int [not null, default: 128, note: "Quantization group size"]
-
-  // Derived fields (computed)
-  scale_rows int [note: "ceil(rows/group_size)"]
-  scale_cols int [note: "Same as cols"]
-  weight_bytes bigint [note: "rows * cols * sizeof(int8)"]
-  scale_bytes bigint [note: "scale_rows * scale_cols * sizeof(fp16)"]
-  total_bytes bigint [note: "weight_bytes + scale_bytes"]
-}
-
-Table transformer_weights {
-  id int [pk]
-  layer_index int [not null, note: "Layer index in model"]
-
-  // Attention weights (all quantized)
-  wq_id int [ref: > quantized_weight.id, note: "Query projection [hidden_dim, hidden_dim]"]
-  wk_id int [ref: > quantized_weight.id, note: "Key projection [hidden_dim, kv_dim]"]
-  wv_id int [ref: > quantized_weight.id, note: "Value projection [hidden_dim, kv_dim]"]
-  wo_id int [ref: > quantized_weight.id, note: "Output projection [hidden_dim, hidden_dim]"]
-
-  // FFN weights (SwiGLU, all quantized)
-  w1_id int [ref: > quantized_weight.id, note: "Gate projection [hidden_dim, intermediate_dim]"]
-  w2_id int [ref: > quantized_weight.id, note: "Down projection [intermediate_dim, hidden_dim]"]
-  w3_id int [ref: > quantized_weight.id, note: "Up projection [hidden_dim, intermediate_dim]"]
-
-  // Normalization weights (FP16, not quantized)
-  rms_att_weight_dim int [not null, note: "RMS attention weight dimension [hidden_dim]"]
-  rms_ffn_weight_dim int [not null, note: "RMS FFN weight dimension [hidden_dim]"]
-}
-
-Table model_weights {
-  id int [pk]
-
-  // Token embedding (FP16)
-  token_embedding_rows int [not null, note: "vocab_size"]
-  token_embedding_cols int [not null, note: "hidden_dim"]
-
-  // Output
-  final_norm_weight_dim int [not null, note: "hidden_dim"]
-  lm_head_id int [ref: > quantized_weight.id, note: "Output projection [hidden_dim, vocab_size]"]
-}
-
-// =============================================================================
-// Runtime State Models
-// =============================================================================
-
-Table kv_cache_config {
-  num_layers int [not null, default: 32]
-  num_heads int [not null, default: 32]
-  head_dim int [not null, default: 128]
-  max_seq_len int [not null, default: 2048]
-  max_batch_size int [not null, default: 1]
-}
-
-Table kv_cache_slot {
-  slot_id int [pk]
-  seq_len int [not null, default: 0, note: "Current sequence length"]
-  is_active bool [not null, default: false, note: "Slot is in use"]
-
-  // Memory layout: [num_layers, 2, max_seq_len, num_heads, head_dim]
-  // 2 = K and V tensors
-  k_cache_ptr bigint [note: "GPU pointer to K cache"]
-  v_cache_ptr bigint [note: "GPU pointer to V cache"]
-}
-
-Table generation_config {
-  max_new_tokens int [not null, default: 256]
-  temperature float [not null, default: 1.0]
-  top_k int [not null, default: 50]
-  top_p float [not null, default: 0.9]
-  do_sample bool [not null, default: false, note: "false = greedy"]
-  repetition_penalty float [not null, default: 1.0]
-}
-
-Table generation_stats {
-  prefill_time_ms float [default: 0.0]
-  decode_time_ms float [default: 0.0]
-  prompt_tokens int [default: 0]
-  tokens_generated int [default: 0]
-  tokens_per_second float [default: 0.0]
-  peak_memory_bytes bigint [default: 0]
-}
-
-// =============================================================================
-// Memory Layout Specifications
-// =============================================================================
-
-// KV Cache Memory Layout (FP16):
-// Shape: [num_layers, 2, max_batch_size, max_seq_len, num_heads, head_dim]
-// Total elements: num_layers * 2 * max_batch_size * max_seq_len * num_heads * head_dim
-// Total bytes: total_elements * sizeof(half) = total_elements * 2
-
-// Weight Memory Layout:
-// - QuantizedWeight: INT8 weights + FP16 scales
-// - Weights: [rows, cols] int8
-// - Scales: [ceil(rows/group_size), cols] fp16
-
-// Example for Llama-2-7B (hidden_dim=4096, num_layers=32, intermediate_dim=11008):
-// Per-layer attention: 4 * 4096 * 4096 = 67M parameters -> 67MB INT8 + 0.5MB scales
-// Per-layer FFN: 3 * 4096 * 11008 = 135M parameters -> 135MB INT8 + 1MB scales
-// Total per layer: ~202MB INT8 + ~1.5MB scales = ~203.5MB
-// Full model (32 layers): ~6.5GB INT8 (vs ~13GB FP16)
-
-// =============================================================================
-// GGUF File Format Schema
-// =============================================================================
-
-Table gguf_header {
-  magic varchar [not null, note: "GGUF magic number"]
-  version int [not null, note: "Format version"]
-  tensor_count bigint [not null, note: "Number of tensors"]
-  metadata_kv_count bigint [not null, note: "Number of metadata key-value pairs"]
-}
-
-Table gguf_metadata {
-  key varchar [pk, not null]
-  value_type varchar [not null, note: "String, Float, Int, Bool, Array, etc."]
-  value text [not null, note: "JSON-encoded value"]
-}
-
-Table gguf_tensor_info {
-  name varchar [pk, not null, note: "Tensor name"]
-  n_dims int [not null, note: "Number of dimensions"]
-  dims array [not null, note: "Dimension sizes"]
-  dtype varchar [not null, note: "Data type (F16, Q8_0, etc.)"]
-  offset bigint [not null, note: "Offset in file"]
-}
-
-// =============================================================================
-// Indexes for Query Optimization
-// =============================================================================
-
-// Primary lookup paths:
-// 1. Model config -> Model weights -> Transformer weights per layer
-// 2. Generation config -> Generation stats
-// 3. KV cache config -> KV cache slots by is_active
-
-// Notes:
-// - All GPU memory allocations use RAII pattern (DeviceBuffer)
-// - Error handling via Result<T> monad (no exceptions for control flow)
-// - Thread-safe: single-owner model, concurrent KV cache slot allocation
diff --git a/openspec/specs/inference-engine/spec.md b/openspec/specs/inference-engine/spec.md
deleted file mode 100644
index 4e54f58..0000000
--- a/openspec/specs/inference-engine/spec.md
+++ /dev/null
@@ -1,245 +0,0 @@
-# Inference Engine Capability
-
-> **Version:** 3.0.0 | **Date:** 2026-04-23 | **Status:** Active
-
-## Purpose
-
-A lightweight LLM inference engine implementing W8A16 quantization, KV Cache incremental decoding, and modular Transformer inference for CUDA-enabled GPUs. This capability provides high-performance text generation with ~50% memory reduction through INT8 weight quantization.
-
-## Terminology
-
-| Term | Description |
-|------|-------------|
-| W8A16 | Mixed precision: INT8 weights, FP16 activations |
-| KV Cache | Key-Value cache for autoregressive generation |
-| Warp Shuffle | CUDA warp-level data exchange instruction |
-| GQA | Grouped Query Attention |
-| GGUF | LLM model weight file format |
-
----
-
-## Requirements
-
-### REQ-1: Model Loading
-
-The system SHALL parse and load GGUF model files with the following capabilities:
-
-1. The system SHALL parse GGUF file headers and configuration metadata.
-2. The system SHALL read binary format quantized weights (INT8 + scales).
-3. The system SHALL allocate GPU memory and transfer weight data to the device.
-4. The system SHALL return a structured error for corrupted or invalid files.
-5. The system SHALL provide a structured model representation including `ModelConfig` and `QuantizedWeight` structures.
-
-#### Scenario: Load valid model file
-- **GIVEN** a valid GGUF model file
-- **WHEN** `InferenceEngine::load()` is called
-- **THEN** the engine SHALL be successfully created
-- **AND** weights SHALL be transferred to GPU memory
-
-#### Scenario: Handle corrupted model file
-- **GIVEN** a corrupted or invalid model file
-- **WHEN** `InferenceEngine::load()` is called
-- **THEN** an error SHALL be returned (not a crash)
-- **AND** the error message SHALL describe the issue
-
-#### Scenario: Scale dimension correctness (P8)
-- **GIVEN** per-group quantization scales
-- **WHEN** scales are applied to weights
-- **THEN** the output dimensions SHALL be correct
-
----
-
-### REQ-2: W8A16 Matrix Multiplication
-
-The system SHALL implement W8A16 quantized matrix multiplication optimized for CUDA:
-
-1. The system SHALL accept INT8 weights, FP16 activations, and per-group scales as input.
-2. The system SHALL perform register-level dequantization for optimal bandwidth utilization.
-3. The system SHALL use CUDA intrinsics and warp shuffle optimization.
-4. The system SHALL support configurable tile sizes (TILE_M × TILE_N × BLOCK_K).
-5. The system SHALL achieve relative error < 1% compared to FP16 baseline.
-
-#### Scenario: W8A16 MatMul precision (P1)
-- **GIVEN** INT8 weights and FP16 activations
-- **WHEN** W8A16 matmul is executed
-- **THEN** the relative error vs FP16 baseline SHALL be < 1%
-
-#### Scenario: Performance optimization
-- **GIVEN** a W8A16 matrix multiplication kernel
-- **WHEN** executed on a CUDA device
-- **THEN** the kernel SHALL use global memory coalesced access
-- **AND** the kernel SHALL use shared memory tiling
-- **AND** the kernel SHALL minimize synchronization points
-
----
-
-### REQ-3: KV Cache Management
-
-The system SHALL implement a KV Cache for efficient autoregressive generation:
-
-1. The system SHALL pre-allocate GPU memory pool for KV cache.
-2. The system SHALL allocate and release sequence slots dynamically.
-3. The system SHALL append KV pairs incrementally per-layer.
-4. The system SHALL track per-sequence usage and capacity.
-5. The system SHALL return an error on memory exhaustion.
-
-#### Scenario: Allocate and release sequence
-- **GIVEN** an initialized KV cache
-- **WHEN** a sequence is allocated via `allocateSequence(max_len)`
-- **THEN** memory SHALL be reserved for the sequence
-- **WHEN** the sequence is released via `releaseSequence(seq_id)`
-- **THEN** memory SHALL be freed and available for new sequences
-
-#### Scenario: KV cache invariants (P2)
-- **GIVEN** an active sequence in KV cache
-- **WHEN** KV pairs are appended via `appendKV(seq_id, layer_idx, k, v, n)`
-- **THEN** the cache size SHALL never exceed allocated capacity
-- **AND** sequence length SHALL be tracked correctly
-
-#### Scenario: Memory exhaustion
-- **GIVEN** limited GPU memory
-- **WHEN** allocation exceeds available memory
-- **THEN** an `OutOfMemoryError` SHALL be returned
-- **AND** existing allocations SHALL remain intact
-
----
-
-### REQ-4: Transformer Layer
-
-The system SHALL implement a complete Transformer layer with W8A16 quantization:
-
-1. The system SHALL compute Q, K, V projections using W8A16 matmul.
-2. The system SHALL apply causal masking for autoregressive generation.
-3. The system SHALL compute FFN using W8A16 matmul.
-4. The system SHALL apply RMSNorm with output RMS ≈ 1.
-5. The system SHALL apply residual connections.
-6. The system SHALL support incremental decoding mode.
-
-#### Scenario: Causal masking correctness (P3)
-- **GIVEN** attention computation in a Transformer layer
-- **WHEN** causal masking is applied
-- **THEN** future tokens SHALL be masked out correctly
-
-#### Scenario: RMSNorm output normalization (P4)
-- **GIVEN** an input tensor to RMSNorm
-- **WHEN** RMSNorm is applied
-- **THEN** the output RMS SHALL be approximately 1
-
-#### Scenario: Incremental decoding equivalence (P5)
-- **GIVEN** a sequence of tokens
-- **WHEN** incremental decoding processes tokens one-by-one
-- **THEN** the output SHALL be equivalent to processing all tokens at once
-
----
-
-### REQ-5: Token Generation
-
-The system SHALL implement token generation for autoregressive inference:
-
-1. The system SHALL process prefill phase in parallel.
-2. The system SHALL compute logits and support sampling strategies.
-3. The system SHALL update KV cache during generation.
-4. The system SHALL enforce configurable maximum generation length.
-5. The system SHALL detect EOS token for early stopping.
-6. The system SHALL report tokens/second statistics.
-
-#### Scenario: Greedy sampling (P6)
-- **GIVEN** logits from the model
-- **WHEN** greedy sampling is used
-- **THEN** the token with highest probability SHALL be selected
-
-#### Scenario: Generation length limit (P7)
-- **GIVEN** `max_new_tokens = N`
-- **WHEN** generation is executed
-- **THEN** the output length SHALL never exceed N tokens
-- **AND** EOS token SHALL stop generation early if encountered
-
----
-
-### REQ-6: Performance Optimization
-
-The system SHALL optimize for GPU execution efficiency:
-
-1. The system SHALL use global memory coalesced access patterns.
-2. The system SHALL use shared memory tiling for matrix operations.
-3. The system SHALL use optimized thread block dimensions.
-4. The system SHALL minimize synchronization points.
-5. The system SHALL support CUDA streams for overlapping operations.
-
-#### Scenario: Memory coalescing optimization
-- **GIVEN** a CUDA kernel accessing global memory
-- **WHEN** the kernel is executed
-- **THEN** memory access patterns SHALL be coalesced for optimal bandwidth
-
-#### Scenario: Shared memory tiling
-- **GIVEN** a matrix multiplication kernel
-- **WHEN** the kernel computes partial results
-- **THEN** shared memory tiling SHALL be used to reduce global memory access
-
----
-
-### REQ-7: Error Handling
-
-The system SHALL provide robust error handling:
-
-1. The system SHALL capture CUDA errors with file and line information.
-2. The system SHALL validate weight dimensions during loading.
-3. The system SHALL provide numerical validation options.
-4. The system SHALL report memory allocation failures.
-5. The system SHALL support profiling mode for timing analysis.
-
-#### Scenario: CUDA error recovery
-- **GIVEN** a CUDA operation that may fail
-- **WHEN** the operation fails
-- **THEN** a `CudaException` SHALL be thrown
-- **AND** the error SHALL include file and line information
-
-#### Scenario: Corrupted file does not crash (P9)
-- **GIVEN** a corrupted model file
-- **WHEN** the model loader attempts to load it
-- **THEN** the system SHALL NOT crash
-- **AND** an appropriate error SHALL be returned
-
----
-
-## Non-Functional Requirements
-
-| Category | Requirement |
-|----------|-------------|
-| Precision | W8A16 SHALL achieve 99%+ precision vs FP16 baseline |
-| Memory | INT8 SHALL reduce ~50% weight memory compared to FP16 |
-| Compatibility | The system SHALL support CUDA 11.0+, CMake 3.18+, C++17 |
-| GPU | The system SHALL require Compute Capability 7.0+ (Volta+) |
-
----
-
-## Correctness Properties
-
-| ID | Property | Validation Requirement |
-|----|----------|----------------------|
-| P1 | W8A16 relative error < 1% | REQ-2 Scenario 1 |
-| P2 | KV Cache invariants | REQ-3 Scenario 2 |
-| P3 | Causal masking correctness | REQ-4 Scenario 1 |
-| P4 | RMSNorm output RMS ≈ 1 | REQ-4 Scenario 2 |
-| P5 | Incremental decoding equivalent to full computation | REQ-4 Scenario 3 |
-| P6 | Greedy sampling = argmax | REQ-5 Scenario 1 |
-| P7 | Generation length ≤ max_new_tokens | REQ-5 Scenario 2 |
-| P8 | Scale dimension correctness | REQ-1 Scenario 3 |
-| P9 | Corrupted file does not crash | REQ-7 Scenario 2 |
-
----
-
-## API Reference
-
-See `openspec/schemas/api/inference-engine.yaml` for detailed API contracts.
-
----
-
-## Version History
-
-| Version | Date | Changes |
-|---------|------|---------|
-| 3.0.0 | 2026-04-23 | Migrated to OpenSpec format with RFC 2119 keywords |
-| 2.0.1 | 2026-04-16 | Fixed scale dimension calculation bug |
-| 2.0.0 | 2026-03-09 | KVCache API refactoring |
-| 1.0.0 | 2025-02-13 | Initial release |
diff --git a/tests/test_model_loader.cpp b/tests/test_model_loader.cpp
index 1c3b6f5..201d32d 100644
--- a/tests/test_model_loader.cpp
+++ b/tests/test_model_loader.cpp
@@ -47,7 +47,7 @@ class TempFile {
         write(&value, sizeof(T));
     }
 
-    void writeBytes(const std::vector<uint8_t> &bytes) {
+    void writeBytes(const std::vector<uint8_t> &bytes) const {
         std::ofstream file(path_, std::ios::binary);
         file.write(reinterpret_cast<const char *>(bytes.data()), bytes.size());
     }