Update to pixi env

.dockerignore

@@ -0,0 +1,60 @@
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.py[cod]
+*$py.class
+
+# Pixi
+.pixi/
+pixi.lock
+
+# Quarto build outputs (will be regenerated in container)
+.quarto/
+_site/
+src/_site/
+*/_book/
+*/_site/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# OS files
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+
+# IDE
+.vscode/
+.idea/
+*.sublime-*
+
+# Documentation
+README.md
+LICENSE
+*.md
+!pixi.toml
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+.travis.yml
+
+# Docker
+Dockerfile
+.dockerignore
+docker-compose.yml

.gemini/commands/speckit.analyze.toml

@@ -0,0 +1,188 @@
+description = "Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation."
+
+prompt = """
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+{{args}}
+"""

.gemini/commands/speckit.checklist.toml

@@ -0,0 +1,298 @@
+description = "Generate a custom checklist for the current feature based on user requirements."
+
+prompt = """
+---
+description: Generate a custom checklist for the current feature based on user requirements.
+---
+
+## Checklist Purpose: "Unit Tests for English"
+
+**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
+
+**NOT for verification/testing**:
+
+- ❌ NOT "Verify the button clicks correctly"
+- ❌ NOT "Test error handling works"
+- ❌ NOT "Confirm the API returns 200"
+- ❌ NOT checking if code/implementation matches the spec
+
+**FOR requirements quality validation**:
+
+- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
+- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
+- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
+- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
+- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
+
+**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Execution Steps
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
+   - All file paths must be absolute.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
+   - Be generated from the user's phrasing + extracted signals from spec/plan/tasks
+   - Only ask about information that materially changes checklist content
+   - Be skipped individually if already unambiguous in `$ARGUMENTS`
+   - Prefer precision over breadth
+
+   Generation algorithm:
+   1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
+   2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
+   3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
+   4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
+   5. Formulate questions chosen from these archetypes:
+      - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?")
+      - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
+      - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
+      - Audience framing (e.g., "Will this be used by the author only or peers during PR review?")
+      - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
+      - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
+
+   Question formatting rules:
+   - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
+   - Limit to A–E options maximum; omit table if a free-form answer is clearer
+   - Never ask the user to restate what they already said
+   - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
+
+   Defaults when interaction impossible:
+   - Depth: Standard
+   - Audience: Reviewer (PR) if code-related; Author otherwise
+   - Focus: Top 2 relevance clusters
+
+   Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
+
+3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
+   - Derive checklist theme (e.g., security, review, deploy, ux)
+   - Consolidate explicit must-have items mentioned by user
+   - Map focus selections to category scaffolding
+   - Infer any missing context from spec/plan/tasks (do NOT hallucinate)
+
+4. **Load feature context**: Read from FEATURE_DIR:
+   - spec.md: Feature requirements and scope
+   - plan.md (if exists): Technical details, dependencies
+   - tasks.md (if exists): Implementation tasks
+
+   **Context Loading Strategy**:
+   - Load only necessary portions relevant to active focus areas (avoid full-file dumping)
+   - Prefer summarizing long sections into concise scenario/requirement bullets
+   - Use progressive disclosure: add follow-on retrieval only if gaps detected
+   - If source docs are large, generate interim summary items instead of embedding raw text
+
+5. **Generate checklist** - Create "Unit Tests for Requirements":
+   - Create `FEATURE_DIR/checklists/` directory if it doesn't exist
+   - Generate unique checklist filename:
+     - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
+     - Format: `[domain].md`
+     - If file exists, append to existing file
+   - Number items sequentially starting from CHK001
+   - Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists)
+
+   **CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
+   Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
+   - **Completeness**: Are all necessary requirements present?
+   - **Clarity**: Are requirements unambiguous and specific?
+   - **Consistency**: Do requirements align with each other?
+   - **Measurability**: Can requirements be objectively verified?
+   - **Coverage**: Are all scenarios/edge cases addressed?
+
+   **Category Structure** - Group items by requirement quality dimensions:
+   - **Requirement Completeness** (Are all necessary requirements documented?)
+   - **Requirement Clarity** (Are requirements specific and unambiguous?)
+   - **Requirement Consistency** (Do requirements align without conflicts?)
+   - **Acceptance Criteria Quality** (Are success criteria measurable?)
+   - **Scenario Coverage** (Are all flows/cases addressed?)
+   - **Edge Case Coverage** (Are boundary conditions defined?)
+   - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?)
+   - **Dependencies & Assumptions** (Are they documented and validated?)
+   - **Ambiguities & Conflicts** (What needs clarification?)
+
+   **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**:
+
+   ❌ **WRONG** (Testing implementation):
+   - "Verify landing page displays 3 episode cards"
+   - "Test hover states work on desktop"
+   - "Confirm logo click navigates home"
+
+   ✅ **CORRECT** (Testing requirements quality):
+   - "Are the exact number and layout of featured episodes specified?" [Completeness]
+   - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
+   - "Are hover state requirements consistent across all interactive elements?" [Consistency]
+   - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage]
+   - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases]
+   - "Are loading states defined for asynchronous episode data?" [Completeness]
+   - "Does the spec define visual hierarchy for competing UI elements?" [Clarity]
+
+   **ITEM STRUCTURE**:
+   Each item should follow this pattern:
+   - Question format asking about requirement quality
+   - Focus on what's WRITTEN (or not written) in the spec/plan
+   - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.]
+   - Reference spec section `[Spec §X.Y]` when checking existing requirements
+   - Use `[Gap]` marker when checking for missing requirements
+
+   **EXAMPLES BY QUALITY DIMENSION**:
+
+   Completeness:
+   - "Are error handling requirements defined for all API failure modes? [Gap]"
+   - "Are accessibility requirements specified for all interactive elements? [Completeness]"
+   - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
+
+   Clarity:
+   - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
+   - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
+   - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
+
+   Consistency:
+   - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
+   - "Are card component requirements consistent between landing and detail pages? [Consistency]"
+
+   Coverage:
+   - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
+   - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
+   - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
+
+   Measurability:
+   - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
+   - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
+
+   **Scenario Classification & Coverage** (Requirements Quality Focus):
+   - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
+   - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?"
+   - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
+   - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]"
+
+   **Traceability Requirements**:
+   - MINIMUM: ≥80% of items MUST include at least one traceability reference
+   - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`
+   - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"
+
+   **Surface & Resolve Issues** (Requirements Quality Problems):
+   Ask questions about the requirements themselves:
+   - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
+   - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
+   - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
+   - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
+   - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
+
+   **Content Consolidation**:
+   - Soft cap: If raw candidate items > 40, prioritize by risk/impact
+   - Merge near-duplicates checking the same requirement aspect
+   - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
+
+   **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
+   - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
+   - ❌ References to code execution, user actions, system behavior
+   - ❌ "Displays correctly", "works properly", "functions as expected"
+   - ❌ "Click", "navigate", "render", "load", "execute"
+   - ❌ Test cases, test plans, QA procedures
+   - ❌ Implementation details (frameworks, APIs, algorithms)
+
+   **✅ REQUIRED PATTERNS** - These test requirements quality:
+   - ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
+   - ✅ "Is [vague term] quantified/clarified with specific criteria?"
+   - ✅ "Are requirements consistent between [section A] and [section B]?"
+   - ✅ "Can [requirement] be objectively measured/verified?"
+   - ✅ "Are [edge cases/scenarios] addressed in requirements?"
+   - ✅ "Does the spec define [missing aspect]?"
+
+6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
+
+7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize:
+   - Focus areas selected
+   - Depth level
+   - Actor/timing
+   - Any explicit user-specified must-have items incorporated
+
+**Important**: Each `/speckit.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows:
+
+- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
+- Simple, memorable filenames that indicate checklist purpose
+- Easy identification and navigation in the `checklists/` folder
+
+To avoid clutter, use descriptive types and clean up obsolete checklists when done.
+
+## Example Checklist Types & Sample Items
+
+**UX Requirements Quality:** `ux.md`
+
+Sample items (testing the requirements, NOT the implementation):
+
+- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
+- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
+- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
+- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
+- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
+- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"
+
+**API Requirements Quality:** `api.md`
+
+Sample items:
+
+- "Are error response formats specified for all failure scenarios? [Completeness]"
+- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
+- "Are authentication requirements consistent across all endpoints? [Consistency]"
+- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
+- "Is versioning strategy documented in requirements? [Gap]"
+
+**Performance Requirements Quality:** `performance.md`
+
+Sample items:
+
+- "Are performance requirements quantified with specific metrics? [Clarity]"
+- "Are performance targets defined for all critical user journeys? [Coverage]"
+- "Are performance requirements under different load conditions specified? [Completeness]"
+- "Can performance requirements be objectively measured? [Measurability]"
+- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"
+
+**Security Requirements Quality:** `security.md`
+
+Sample items:
+
+- "Are authentication requirements specified for all protected resources? [Coverage]"
+- "Are data protection requirements defined for sensitive information? [Completeness]"
+- "Is the threat model documented and requirements aligned to it? [Traceability]"
+- "Are security requirements consistent with compliance obligations? [Consistency]"
+- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
+
+## Anti-Examples: What NOT To Do
+
+**❌ WRONG - These test implementation, not requirements:**
+
+```markdown
+- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
+- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
+- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
+- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
+```
+
+**✅ CORRECT - These test requirements quality:**
+
+```markdown
+- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
+- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
+- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
+- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
+- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
+- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
+```
+
+**Key Differences:**
+
+- Wrong: Tests if the system works correctly
+- Correct: Tests if the requirements are written correctly
+- Wrong: Verification of behavior
+- Correct: Validation of requirement quality
+- Wrong: "Does it do X?"
+- Correct: "Is X clearly specified?"
+"""

.gemini/commands/speckit.clarify.toml

@@ -0,0 +1,185 @@
+description = "Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec."
+
+prompt = """
+---
+description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
+handoffs: 
+  - label: Build Technical Plan
+    agent: speckit.plan
+    prompt: Create a plan for the spec. I am building with...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
+
+Execution steps:
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
+   - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
+
+   Functional Scope & Behavior:
+   - Core user goals & success criteria
+   - Explicit out-of-scope declarations
+   - User roles / personas differentiation
+
+   Domain & Data Model:
+   - Entities, attributes, relationships
+   - Identity & uniqueness rules
+   - Lifecycle/state transitions
+   - Data volume / scale assumptions
+
+   Interaction & UX Flow:
+   - Critical user journeys / sequences
+   - Error/empty/loading states
+   - Accessibility or localization notes
+
+   Non-Functional Quality Attributes:
+   - Performance (latency, throughput targets)
+   - Scalability (horizontal/vertical, limits)
+   - Reliability & availability (uptime, recovery expectations)
+   - Observability (logging, metrics, tracing signals)
+   - Security & privacy (authN/Z, data protection, threat assumptions)
+   - Compliance / regulatory constraints (if any)
+
+   Integration & External Dependencies:
+   - External services/APIs and failure modes
+   - Data import/export formats
+   - Protocol/versioning assumptions
+
+   Edge Cases & Failure Handling:
+   - Negative scenarios
+   - Rate limiting / throttling
+   - Conflict resolution (e.g., concurrent edits)
+
+   Constraints & Tradeoffs:
+   - Technical constraints (language, storage, hosting)
+   - Explicit tradeoffs or rejected alternatives
+
+   Terminology & Consistency:
+   - Canonical glossary terms
+   - Avoided synonyms / deprecated terms
+
+   Completion Signals:
+   - Acceptance criteria testability
+   - Measurable Definition of Done style indicators
+
+   Misc / Placeholders:
+   - TODO markers / unresolved decisions
+   - Ambiguous adjectives ("robust", "intuitive") lacking quantification
+
+   For each category with Partial or Missing status, add a candidate question opportunity unless:
+   - Clarification would not materially change implementation or validation strategy
+   - Information is better deferred to planning phase (note internally)
+
+3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+    - Maximum of 10 total questions across the whole session.
+    - Each question must be answerable with EITHER:
+       - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
+       - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
+    - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
+    - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
+    - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
+    - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
+    - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
+
+4. Sequential questioning loop (interactive):
+    - Present EXACTLY ONE question at a time.
+    - For multiple‑choice questions:
+       - **Analyze all options** and determine the **most suitable option** based on:
+          - Best practices for the project type
+          - Common patterns in similar implementations
+          - Risk reduction (security, performance, maintainability)
+          - Alignment with any explicit project goals or constraints visible in the spec
+       - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
+       - Format as: `**Recommended:** Option [X] - <reasoning>`
+       - Then render all options as a Markdown table:
+
+       | Option | Description |
+       |--------|-------------|
+       | A | <Option A description> |
+       | B | <Option B description> |
+       | C | <Option C description> (add D/E as needed up to 5) |
+       | Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |
+
+       - After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
+    - For short‑answer style (no meaningful discrete options):
+       - Provide your **suggested answer** based on best practices and context.
+       - Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
+       - Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
+    - After the user answers:
+       - If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
+       - Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
+       - If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
+       - Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
+    - Stop asking further questions when:
+       - All critical ambiguities resolved early (remaining queued items become unnecessary), OR
+       - User signals completion ("done", "good", "no more"), OR
+       - You reach 5 asked questions.
+    - Never reveal future queued questions in advance.
+    - If no valid questions exist at start, immediately report no critical ambiguities.
+
+5. Integration after EACH accepted answer (incremental update approach):
+    - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
+    - For the first integrated answer in this session:
+       - Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
+       - Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
+    - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
+    - Then immediately apply the clarification to the most appropriate section(s):
+       - Functional ambiguity → Update or add a bullet in Functional Requirements.
+       - User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
+       - Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
+       - Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
+       - Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
+       - Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
+    - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
+    - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
+    - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
+    - Keep each inserted clarification minimal and testable (avoid narrative drift).
+
+6. Validation (performed after EACH write plus final pass):
+   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
+   - Total asked (accepted) questions ≤ 5.
+   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
+   - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
+   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
+   - Terminology consistency: same canonical term used across all updated sections.
+
+7. Write the updated spec back to `FEATURE_SPEC`.
+
+8. Report completion (after questioning loop ends or early termination):
+   - Number of questions asked & answered.
+   - Path to updated spec.
+   - Sections touched (list names).
+   - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
+   - If any Outstanding or Deferred remain, recommend whether to proceed to `/speckit.plan` or run `/speckit.clarify` again later post-plan.
+   - Suggested next command.
+
+Behavior rules:
+
+- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
+- If spec file missing, instruct user to run `/speckit.specify` first (do not create a new spec here).
+- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
+- Avoid speculative tech stack questions unless the absence blocks functional clarity.
+- Respect user early termination signals ("stop", "done", "proceed").
+- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
+- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
+
+Context for prioritization: {{args}}
+"""

.gemini/commands/speckit.constitution.toml

@@ -0,0 +1,86 @@
+description = "Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync."
+
+prompt = """
+---
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+handoffs: 
+  - label: Build Specification
+    agent: speckit.specify
+    prompt: Implement the feature specification based on the updated constitution. I want to build...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+Follow this execution flow:
+
+1. Load the existing constitution template at `.specify/memory/constitution.md`.
+   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2. Collect/derive values for placeholders:
+   - If user input (conversation) supplies a value, use it.
+   - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+   - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+   - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+     - MAJOR: Backward incompatible governance/principle removals or redefinitions.
+     - MINOR: New principle/section added or materially expanded guidance.
+     - PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+   - If version bump type ambiguous, propose reasoning before finalizing.
+
+3. Draft the updated constitution content:
+   - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+   - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+   - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4. Consistency propagation checklist (convert prior checklist into active validations):
+   - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+   - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+   - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+   - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
+
+5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
+   - Version change: old → new
+   - List of modified principles (old title → new title if renamed)
+   - Added sections
+   - Removed sections
+   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
+   - Follow-up TODOs if any placeholders intentionally deferred.
+
+6. Validation before final output:
+   - No remaining unexplained bracket tokens.
+   - Version line matches report.
+   - Dates ISO format YYYY-MM-DD.
+   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
+
+8. Output a final summary to the user with:
+   - New version and bump rationale.
+   - Any files flagged for manual follow-up.
+   - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+Formatting & Style Requirements:
+
+- Use Markdown headings exactly as in the template (do not demote/promote levels).
+- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
+- Keep a single blank line between sections.
+- Avoid trailing whitespace.
+
+If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
+
+If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
+
+Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
+"""

.gemini/commands/speckit.implement.toml

@@ -0,0 +1,139 @@
+description = "Execute the implementation plan by processing and executing all tasks defined in tasks.md"
+
+prompt = """
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
+   - Scan all checklist files in the checklists/ directory
+   - For each checklist, count:
+     - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
+     - Completed items: Lines matching `- [X]` or `- [x]`
+     - Incomplete items: Lines matching `- [ ]`
+   - Create a status table:
+
+     ```text
+     | Checklist | Total | Completed | Incomplete | Status |
+     |-----------|-------|-----------|------------|--------|
+     | ux.md     | 12    | 12        | 0          | ✓ PASS |
+     | test.md   | 8     | 5         | 3          | ✗ FAIL |
+     | security.md | 6   | 6         | 0          | ✓ PASS |
+     ```
+
+   - Calculate overall status:
+     - **PASS**: All checklists have 0 incomplete items
+     - **FAIL**: One or more checklists have incomplete items
+
+   - **If any checklist is incomplete**:
+     - Display the table with incomplete item counts
+     - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
+     - Wait for user response before continuing
+     - If user says "no" or "wait" or "stop", halt execution
+     - If user says "yes" or "proceed" or "continue", proceed to step 3
+
+   - **If all checklists are complete**:
+     - Display the table showing all checklists passed
+     - Automatically proceed to step 3
+
+3. Load and analyze the implementation context:
+   - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+   - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+   - **IF EXISTS**: Read data-model.md for entities and relationships
+   - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+   - **IF EXISTS**: Read research.md for technical decisions and constraints
+   - **IF EXISTS**: Read quickstart.md for integration scenarios
+
+4. **Project Setup Verification**:
+   - **REQUIRED**: Create/verify ignore files based on actual project setup:
+
+   **Detection & Creation Logic**:
+   - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
+
+     ```sh
+     git rev-parse --git-dir 2>/dev/null
+     ```
+
+   - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
+   - Check if .eslintrc* exists → create/verify .eslintignore
+   - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns
+   - Check if .prettierrc* exists → create/verify .prettierignore
+   - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
+   - Check if terraform files (*.tf) exist → create/verify .terraformignore
+   - Check if .helmignore needed (helm charts present) → create/verify .helmignore
+
+   **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
+   **If ignore file missing**: Create with full pattern set for detected technology
+
+   **Common Patterns by Technology** (from plan.md tech stack):
+   - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
+   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
+   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
+   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
+   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
+   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
+   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
+   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
+   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
+   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
+   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `Makefile`, `config.log`, `.idea/`, `*.log`, `.env*`
+   - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
+   - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
+   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
+
+   **Tool-Specific Patterns**:
+   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
+   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
+   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
+   - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
+
+5. Parse tasks.md structure and extract:
+   - **Task phases**: Setup, Tests, Core, Integration, Polish
+   - **Task dependencies**: Sequential vs parallel execution rules
+   - **Task details**: ID, description, file paths, parallel markers [P]
+   - **Execution flow**: Order and dependency requirements
+
+6. Execute implementation following the task plan:
+   - **Phase-by-phase execution**: Complete each phase before moving to the next
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together  
+   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
+   - **File-based coordination**: Tasks affecting the same files must run sequentially
+   - **Validation checkpoints**: Verify each phase completion before proceeding
+
+7. Implementation execution rules:
+   - **Setup first**: Initialize project structure, dependencies, configuration
+   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
+   - **Core development**: Implement models, services, CLI commands, endpoints
+   - **Integration work**: Database connections, middleware, logging, external services
+   - **Polish and validation**: Unit tests, performance optimization, documentation
+
+8. Progress tracking and error handling:
+   - Report progress after each completed task
+   - Halt execution if any non-parallel task fails
+   - For parallel tasks [P], continue with successful tasks, report failed ones
+   - Provide clear error messages with context for debugging
+   - Suggest next steps if implementation cannot proceed
+   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
+
+9. Completion validation:
+   - Verify all required tasks are completed
+   - Check that implemented features match the original specification
+   - Validate that tests pass and coverage meets requirements
+   - Confirm the implementation follows the technical plan
+   - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list.
+"""

.gemini/commands/speckit.plan.toml

@@ -0,0 +1,93 @@
+description = "Execute the implementation planning workflow using the plan template to generate design artifacts."
+
+prompt = """
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+handoffs: 
+  - label: Create Tasks
+    agent: speckit.tasks
+    prompt: Break the plan into tasks
+    send: true
+  - label: Create Checklist
+    agent: speckit.checklist
+    prompt: Create a checklist for the following domain...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+
+3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
+   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
+   - Fill Constitution Check section from constitution
+   - Evaluate gates (ERROR if violations unjustified)
+   - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
+   - Phase 1: Generate data-model.md, contracts/, quickstart.md
+   - Phase 1: Update agent context by running the agent script
+   - Re-evaluate Constitution Check post-design
+
+4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
+
+## Phases
+
+### Phase 0: Outline & Research
+
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+
+   ```text
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Design & Contracts
+
+**Prerequisites:** `research.md` complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Generate API contracts** from functional requirements:
+   - For each user action → endpoint
+   - Use standard REST/GraphQL patterns
+   - Output OpenAPI/GraphQL schema to `/contracts/`
+
+3. **Agent context update**:
+   - Run `.specify/scripts/bash/update-agent-context.sh gemini`
+   - These scripts detect which AI agent is in use
+   - Update the appropriate agent-specific context file
+   - Add only new technology from current plan
+   - Preserve manual additions between markers
+
+**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
+
+## Key rules
+
+- Use absolute paths
+- ERROR on gate failures or unresolved clarifications
+"""

.gemini/commands/speckit.specify.toml

@@ -0,0 +1,262 @@
+description = "Create or update the feature specification from a natural language feature description."
+
+prompt = """
+---
+description: Create or update the feature specification from a natural language feature description.
+handoffs: 
+  - label: Build Technical Plan
+    agent: speckit.plan
+    prompt: Create a plan for the spec. I am building with...
+  - label: Clarify Spec Requirements
+    agent: speckit.clarify
+    prompt: Clarify specification requirements
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{{args}}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Generate a concise short name** (2-4 words) for the branch:
+   - Analyze the feature description and extract the most meaningful keywords
+   - Create a 2-4 word short name that captures the essence of the feature
+   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
+   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
+   - Keep it concise but descriptive enough to understand the feature at a glance
+   - Examples:
+     - "I want to add user authentication" → "user-auth"
+     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
+     - "Create a dashboard for analytics" → "analytics-dashboard"
+     - "Fix payment processing timeout bug" → "fix-payment-timeout"
+
+2. **Check for existing branches before creating new one**:
+
+   a. First, fetch all remote branches to ensure we have the latest information:
+
+      ```bash
+      git fetch --all --prune
+      ```
+
+   b. Find the highest feature number across all sources for the short-name:
+      - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
+      - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
+      - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
+
+   c. Determine the next available number:
+      - Extract all numbers from all three sources
+      - Find the highest number N
+      - Use N+1 for the new branch number
+
+   d. Run the script `.specify/scripts/bash/create-new-feature.sh --json "{{args}}"` with the calculated number and short-name:
+      - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
+      - Bash example: `.specify/scripts/bash/create-new-feature.sh --json "{{args}}" --json --number 5 --short-name "user-auth" "Add user authentication"`
+      - PowerShell example: `.specify/scripts/bash/create-new-feature.sh --json "{{args}}" -Json -Number 5 -ShortName "user-auth" "Add user authentication"`
+
+   **IMPORTANT**:
+   - Check all three sources (remote branches, local branches, specs directories) to find the highest number
+   - Only match branches/directories with the exact short-name pattern
+   - If no existing branches/directories found with this short-name, start with number 1
+   - You must only ever run this script once per feature
+   - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
+   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot")
+
+3. Load `.specify/templates/spec-template.md` to understand required sections.
+
+4. Follow this execution flow:
+
+    1. Parse user description from Input
+       If empty: ERROR "No feature description provided"
+    2. Extract key concepts from description
+       Identify: actors, actions, data, constraints
+    3. For unclear aspects:
+       - Make informed guesses based on context and industry standards
+       - Only mark with [NEEDS CLARIFICATION: specific question] if:
+         - The choice significantly impacts feature scope or user experience
+         - Multiple reasonable interpretations exist with different implications
+         - No reasonable default exists
+       - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
+       - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
+    4. Fill User Scenarios & Testing section
+       If no clear user flow: ERROR "Cannot determine user scenarios"
+    5. Generate Functional Requirements
+       Each requirement must be testable
+       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+    6. Define Success Criteria
+       Create measurable, technology-agnostic outcomes
+       Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+       Each criterion must be verifiable without implementation details
+    7. Identify Key Entities (if data involved)
+    8. Return: SUCCESS (spec ready for planning)
+
+5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+
+6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+   a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
+
+      ```markdown
+      # Specification Quality Checklist: [FEATURE NAME]
+      
+      **Purpose**: Validate specification completeness and quality before proceeding to planning
+      **Created**: [DATE]
+      **Feature**: [Link to spec.md]
+      
+      ## Content Quality
+      
+      - [ ] No implementation details (languages, frameworks, APIs)
+      - [ ] Focused on user value and business needs
+      - [ ] Written for non-technical stakeholders
+      - [ ] All mandatory sections completed
+      
+      ## Requirement Completeness
+      
+      - [ ] No [NEEDS CLARIFICATION] markers remain
+      - [ ] Requirements are testable and unambiguous
+      - [ ] Success criteria are measurable
+      - [ ] Success criteria are technology-agnostic (no implementation details)
+      - [ ] All acceptance scenarios are defined
+      - [ ] Edge cases are identified
+      - [ ] Scope is clearly bounded
+      - [ ] Dependencies and assumptions identified
+      
+      ## Feature Readiness
+      
+      - [ ] All functional requirements have clear acceptance criteria
+      - [ ] User scenarios cover primary flows
+      - [ ] Feature meets measurable outcomes defined in Success Criteria
+      - [ ] No implementation details leak into specification
+      
+      ## Notes
+      
+      - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
+      ```
+
+   b. **Run Validation Check**: Review the spec against each checklist item:
+      - For each item, determine if it passes or fails
+      - Document specific issues found (quote relevant spec sections)
+
+   c. **Handle Validation Results**:
+
+      - **If all items pass**: Mark checklist complete and proceed to step 6
+
+      - **If items fail (excluding [NEEDS CLARIFICATION])**:
+        1. List the failing items and specific issues
+        2. Update the spec to address each issue
+        3. Re-run validation until all items pass (max 3 iterations)
+        4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
+
+      - **If [NEEDS CLARIFICATION] markers remain**:
+        1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
+        2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
+        3. For each clarification needed (max 3), present options to user in this format:
+
+           ```markdown
+           ## Question [N]: [Topic]
+           
+           **Context**: [Quote relevant spec section]
+           
+           **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
+           
+           **Suggested Answers**:
+           
+           | Option | Answer | Implications |
+           |--------|--------|--------------|
+           | A      | [First suggested answer] | [What this means for the feature] |
+           | B      | [Second suggested answer] | [What this means for the feature] |
+           | C      | [Third suggested answer] | [What this means for the feature] |
+           | Custom | Provide your own answer | [Explain how to provide custom input] |
+           
+           **Your choice**: _[Wait for user response]_
+           ```
+
+        4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
+           - Use consistent spacing with pipes aligned
+           - Each cell should have spaces around content: `| Content |` not `|Content|`
+           - Header separator must have at least 3 dashes: `|--------|`
+           - Test that the table renders correctly in markdown preview
+        5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+        6. Present all questions together before waiting for responses
+        7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+        8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+        9. Re-run validation after all clarifications are resolved
+
+   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
+
+7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
+
+**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
+
+## General Guidelines
+
+## Quick Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+
+When creating this spec from a user prompt:
+
+1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
+2. **Document assumptions**: Record reasonable defaults in the Assumptions section
+3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
+   - Significantly impact feature scope or user experience
+   - Have multiple reasonable interpretations with different implications
+   - Lack any reasonable default
+4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
+5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+6. **Common areas needing clarification** (only if no reasonable default exists):
+   - Feature scope and boundaries (include/exclude specific use cases)
+   - User types and permissions (if multiple conflicting interpretations possible)
+   - Security/compliance requirements (when legally/financially significant)
+
+**Examples of reasonable defaults** (don't ask about these):
+
+- Data retention: Industry-standard practices for the domain
+- Performance targets: Standard web/mobile app expectations unless specified
+- Error handling: User-friendly messages with appropriate fallbacks
+- Authentication method: Standard session-based or OAuth2 for web apps
+- Integration patterns: RESTful APIs unless specified otherwise
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+- "React components render efficiently" (framework-specific)
+- "Redis cache hit rate above 80%" (technology-specific)
+"""

.gemini/commands/speckit.tasks.toml

@@ -0,0 +1,141 @@
+description = "Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts."
+
+prompt = """
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+handoffs: 
+  - label: Analyze For Consistency
+    agent: speckit.analyze
+    prompt: Run a project analysis for consistency
+    send: true
+  - label: Implement Project
+    agent: speckit.implement
+    prompt: Start the implementation in phases
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load design documents**: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+   - Load plan.md and extract tech stack, libraries, project structure
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map endpoints to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - Generate tasks organized by user story (see Task Generation Rules below)
+   - Generate dependency graph showing user story completion order
+   - Create parallel execution examples per user story
+   - Validate task completeness (each user story has all needed tasks, independently testable)
+
+4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:
+   - Correct feature name from plan.md
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+   - Phase 3+: One phase per user story (in priority order from spec.md)
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict checklist format (see Task Generation Rules below)
+   - Clear file paths for each task
+   - Dependencies section showing story completion order
+   - Parallel execution examples per story
+   - Implementation strategy section (MVP first, incremental delivery)
+
+5. **Report**: Output path to generated tasks.md and summary:
+   - Total task count
+   - Task count per user story
+   - Parallel opportunities identified
+   - Independent test criteria for each story
+   - Suggested MVP scope (typically just User Story 1)
+   - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
+
+Context for task generation: {{args}}
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label  
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
+- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
+1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
+   - Each user story (P1, P2, P3...) gets its own phase
+   - Map all related components to their story:
+     - Models needed for that story
+     - Services needed for that story
+     - Endpoints/UI needed for that story
+     - If tests requested: Tests specific to that story
+   - Mark story dependencies (most stories should be independent)
+
+2. **From Contracts**:
+   - Map each contract/endpoint → to the user story it serves
+   - If tests requested: Each contract → contract test task [P] before implementation in that story's phase
+
+3. **From Data Model**:
+   - Map each entity to the user story(ies) that need it
+   - If entity serves multiple stories: Put in earliest story or Setup phase
+   - Relationships → service layer tasks in appropriate story phase
+
+4. **From Setup/Infrastructure**:
+   - Shared infrastructure → Setup phase (Phase 1)
+   - Foundational/blocking tasks → Foundational phase (Phase 2)
+   - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns
+"""

.gemini/commands/speckit.taskstoissues.toml

@@ -0,0 +1,34 @@
+description = "Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts."
+
+prompt = """
+---
+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+tools: ['github/github-mcp-server/issue_write']
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
+1. From the executed script, extract the path to **tasks**.
+1. Get the Git remote by running:
+
+```bash
+git config --get remote.origin.url
+```
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
+
+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL
+"""

.gitignore

@@ -1,5 +1,37 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# Pixi
+.pixi/
+pixi.lock
+
+# Quarto
 /.quarto/
+/_site/
+src/_site/
+
+# Jupyter
+.ipynb_checkpoints/
 
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# OS
 .DS_Store
-.venv/**
-src/_site/
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Quarto
+*/_book/
+*/_site/

.specify/memory/constitution.md

@@ -0,0 +1,50 @@
+# [PROJECT_NAME] Constitution
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Library-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. CLI Interface -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+
+### [PRINCIPLE_3_NAME]
+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+
+### [PRINCIPLE_4_NAME]
+<!-- Example: IV. Integration Testing -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+
+### [PRINCIPLE_5_NAME]
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
+[PRINCIPLE_5_DESCRIPTION]
+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+
+## [SECTION_2_NAME]
+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+
+[SECTION_2_CONTENT]
+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+
+## [SECTION_3_NAME]
+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+
+[SECTION_3_CONTENT]
+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+
+## Governance
+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
+
+[GOVERNANCE_RULES]
+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->

.specify/scripts/bash/check-prerequisites.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-tasks     Require tasks.md to exist (for implementation phase)
+#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.sh --json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.sh --json --require-tasks --include-tasks
+  
+  # Get feature paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+  
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths and validate branch
+eval $(get_feature_paths)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+if $PATHS_ONLY; then
+    if $JSON_MODE; then
+        # Minimal JSON paths payload (no validation performed)
+        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "BRANCH: $CURRENT_BRANCH"
+        echo "FEATURE_DIR: $FEATURE_DIR"
+        echo "FEATURE_SPEC: $FEATURE_SPEC"
+        echo "IMPL_PLAN: $IMPL_PLAN"
+        echo "TASKS: $TASKS"
+    fi
+    exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d "$FEATURE_DIR" ]]; then
+    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+    echo "Run /speckit.specify first to create the feature structure." >&2
+    exit 1
+fi
+
+if [[ ! -f "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.plan first to create the implementation plan." >&2
+    exit 1
+fi
+
+# Check for tasks.md if required
+if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
+    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.tasks first to create the task list." >&2
+    exit 1
+fi
+
+# Build list of available documents
+docs=()
+
+# Always check these optional docs
+[[ -f "$RESEARCH" ]] && docs+=("research.md")
+[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
+
+# Check contracts directory (only if it exists and has files)
+if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+    docs+=("contracts/")
+fi
+
+[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
+
+# Include tasks.md if requested and it exists
+if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
+    docs+=("tasks.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+    # Build JSON array of documents
+    if [[ ${#docs[@]} -eq 0 ]]; then
+        json_docs="[]"
+    else
+        json_docs=$(printf '"%s",' "${docs[@]}")
+        json_docs="[${json_docs%,}]"
+    fi
+    
+    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
+else
+    # Text output
+    echo "FEATURE_DIR:$FEATURE_DIR"
+    echo "AVAILABLE_DOCS:"
+    
+    # Show status of each potential document
+    check_file "$RESEARCH" "research.md"
+    check_file "$DATA_MODEL" "data-model.md"
+    check_dir "$CONTRACTS_DIR" "contracts/"
+    check_file "$QUICKSTART" "quickstart.md"
+    
+    if $INCLUDE_TASKS; then
+        check_file "$TASKS" "tasks.md"
+    fi
+fi

.specify/scripts/bash/common.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# Common functions and variables for all scripts
+
+# Get repository root, with fallback for non-git repositories
+get_repo_root() {
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        git rev-parse --show-toplevel
+    else
+        # Fall back to script location for non-git repos
+        local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+        (cd "$script_dir/../../.." && pwd)
+    fi
+}
+
+# Get current branch, with fallback for non-git repositories
+get_current_branch() {
+    # First check if SPECIFY_FEATURE environment variable is set
+    if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
+        echo "$SPECIFY_FEATURE"
+        return
+    fi
+
+    # Then check git if available
+    if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
+        git rev-parse --abbrev-ref HEAD
+        return
+    fi
+
+    # For non-git repos, try to find the latest feature directory
+    local repo_root=$(get_repo_root)
+    local specs_dir="$repo_root/specs"
+
+    if [[ -d "$specs_dir" ]]; then
+        local latest_feature=""
+        local highest=0
+
+        for dir in "$specs_dir"/*; do
+            if [[ -d "$dir" ]]; then
+                local dirname=$(basename "$dir")
+                if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
+                    local number=${BASH_REMATCH[1]}
+                    number=$((10#$number))
+                    if [[ "$number" -gt "$highest" ]]; then
+                        highest=$number
+                        latest_feature=$dirname
+                    fi
+                fi
+            fi
+        done
+
+        if [[ -n "$latest_feature" ]]; then
+            echo "$latest_feature"
+            return
+        fi
+    fi
+
+    echo "main"  # Final fallback
+}
+
+# Check if we have git available
+has_git() {
+    git rev-parse --show-toplevel >/dev/null 2>&1
+}
+
+check_feature_branch() {
+    local branch="$1"
+    local has_git_repo="$2"
+
+    # For non-git repos, we can't enforce branch naming but still provide output
+    if [[ "$has_git_repo" != "true" ]]; then
+        echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
+        return 0
+    fi
+
+    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
+        echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
+        echo "Feature branches should be named like: 001-feature-name" >&2
+        return 1
+    fi
+
+    return 0
+}
+
+get_feature_dir() { echo "$1/specs/$2"; }
+
+# Find feature directory by numeric prefix instead of exact branch match
+# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
+find_feature_dir_by_prefix() {
+    local repo_root="$1"
+    local branch_name="$2"
+    local specs_dir="$repo_root/specs"
+
+    # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
+    if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
+        # If branch doesn't have numeric prefix, fall back to exact match
+        echo "$specs_dir/$branch_name"
+        return
+    fi
+
+    local prefix="${BASH_REMATCH[1]}"
+
+    # Search for directories in specs/ that start with this prefix
+    local matches=()
+    if [[ -d "$specs_dir" ]]; then
+        for dir in "$specs_dir"/"$prefix"-*; do
+            if [[ -d "$dir" ]]; then
+                matches+=("$(basename "$dir")")
+            fi
+        done
+    fi
+
+    # Handle results
+    if [[ ${#matches[@]} -eq 0 ]]; then
+        # No match found - return the branch name path (will fail later with clear error)
+        echo "$specs_dir/$branch_name"
+    elif [[ ${#matches[@]} -eq 1 ]]; then
+        # Exactly one match - perfect!
+        echo "$specs_dir/${matches[0]}"
+    else
+        # Multiple matches - this shouldn't happen with proper naming convention
+        echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
+        echo "Please ensure only one spec directory exists per numeric prefix." >&2
+        echo "$specs_dir/$branch_name"  # Return something to avoid breaking the script
+    fi
+}
+
+get_feature_paths() {
+    local repo_root=$(get_repo_root)
+    local current_branch=$(get_current_branch)
+    local has_git_repo="false"
+
+    if has_git; then
+        has_git_repo="true"
+    fi
+
+    # Use prefix-based lookup to support multiple branches per spec
+    local feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch")
+
+    cat <<EOF
+REPO_ROOT='$repo_root'
+CURRENT_BRANCH='$current_branch'
+HAS_GIT='$has_git_repo'
+FEATURE_DIR='$feature_dir'
+FEATURE_SPEC='$feature_dir/spec.md'
+IMPL_PLAN='$feature_dir/plan.md'
+TASKS='$feature_dir/tasks.md'
+RESEARCH='$feature_dir/research.md'
+DATA_MODEL='$feature_dir/data-model.md'
+QUICKSTART='$feature_dir/quickstart.md'
+CONTRACTS_DIR='$feature_dir/contracts'
+EOF
+}
+
+check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+

.specify/scripts/bash/create-new-feature.sh

@@ -0,0 +1,297 @@
+#!/usr/bin/env bash
+
+set -e
+
+JSON_MODE=false
+SHORT_NAME=""
+BRANCH_NUMBER=""
+ARGS=()
+i=1
+while [ $i -le $# ]; do
+    arg="${!i}"
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --short-name)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            # Check if the next argument is another option (starts with --)
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            SHORT_NAME="$next_arg"
+            ;;
+        --number)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            BRANCH_NUMBER="$next_arg"
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>"
+            echo ""
+            echo "Options:"
+            echo "  --json              Output in JSON format"
+            echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
+            echo "  --number N          Specify branch number manually (overrides auto-detection)"
+            echo "  --help, -h          Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  $0 'Add user authentication system' --short-name 'user-auth'"
+            echo "  $0 'Implement OAuth2 integration for API' --number 5"
+            exit 0
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+    i=$((i + 1))
+done
+
+FEATURE_DESCRIPTION="${ARGS[*]}"
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>" >&2
+    exit 1
+fi
+
+# Function to find the repository root by searching for existing project markers
+find_repo_root() {
+    local dir="$1"
+    while [ "$dir" != "/" ]; do
+        if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
+            echo "$dir"
+            return 0
+        fi
+        dir="$(dirname "$dir")"
+    done
+    return 1
+}
+
+# Function to get highest number from specs directory
+get_highest_from_specs() {
+    local specs_dir="$1"
+    local highest=0
+    
+    if [ -d "$specs_dir" ]; then
+        for dir in "$specs_dir"/*; do
+            [ -d "$dir" ] || continue
+            dirname=$(basename "$dir")
+            number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
+            number=$((10#$number))
+            if [ "$number" -gt "$highest" ]; then
+                highest=$number
+            fi
+        done
+    fi
+    
+    echo "$highest"
+}
+
+# Function to get highest number from git branches
+get_highest_from_branches() {
+    local highest=0
+    
+    # Get all branches (local and remote)
+    branches=$(git branch -a 2>/dev/null || echo "")
+    
+    if [ -n "$branches" ]; then
+        while IFS= read -r branch; do
+            # Clean branch name: remove leading markers and remote prefixes
+            clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
+            
+            # Extract feature number if branch matches pattern ###-*
+            if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then
+                number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")
+                number=$((10#$number))
+                if [ "$number" -gt "$highest" ]; then
+                    highest=$number
+                fi
+            fi
+        done <<< "$branches"
+    fi
+    
+    echo "$highest"
+}
+
+# Function to check existing branches (local and remote) and return next available number
+check_existing_branches() {
+    local specs_dir="$1"
+
+    # Fetch all remotes to get latest branch info (suppress errors if no remotes)
+    git fetch --all --prune 2>/dev/null || true
+
+    # Get highest number from ALL branches (not just matching short name)
+    local highest_branch=$(get_highest_from_branches)
+
+    # Get highest number from ALL specs (not just matching short name)
+    local highest_spec=$(get_highest_from_specs "$specs_dir")
+
+    # Take the maximum of both
+    local max_num=$highest_branch
+    if [ "$highest_spec" -gt "$max_num" ]; then
+        max_num=$highest_spec
+    fi
+
+    # Return next number
+    echo $((max_num + 1))
+}
+
+# Function to clean and format a branch name
+clean_branch_name() {
+    local name="$1"
+    echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
+}
+
+# Resolve repository root. Prefer git information when available, but fall back
+# to searching for repository markers so the workflow still functions in repositories that
+# were initialised with --no-git.
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    REPO_ROOT=$(git rev-parse --show-toplevel)
+    HAS_GIT=true
+else
+    REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
+    if [ -z "$REPO_ROOT" ]; then
+        echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
+        exit 1
+    fi
+    HAS_GIT=false
+fi
+
+cd "$REPO_ROOT"
+
+SPECS_DIR="$REPO_ROOT/specs"
+mkdir -p "$SPECS_DIR"
+
+# Function to generate branch name with stop word filtering and length filtering
+generate_branch_name() {
+    local description="$1"
+    
+    # Common stop words to filter out
+    local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
+    
+    # Convert to lowercase and split into words
+    local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
+    
+    # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
+    local meaningful_words=()
+    for word in $clean_name; do
+        # Skip empty words
+        [ -z "$word" ] && continue
+        
+        # Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms)
+        if ! echo "$word" | grep -qiE "$stop_words"; then
+            if [ ${#word} -ge 3 ]; then
+                meaningful_words+=("$word")
+            elif echo "$description" | grep -q "\b${word^^}\b"; then
+                # Keep short words if they appear as uppercase in original (likely acronyms)
+                meaningful_words+=("$word")
+            fi
+        fi
+    done
+    
+    # If we have meaningful words, use first 3-4 of them
+    if [ ${#meaningful_words[@]} -gt 0 ]; then
+        local max_words=3
+        if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
+        
+        local result=""
+        local count=0
+        for word in "${meaningful_words[@]}"; do
+            if [ $count -ge $max_words ]; then break; fi
+            if [ -n "$result" ]; then result="$result-"; fi
+            result="$result$word"
+            count=$((count + 1))
+        done
+        echo "$result"
+    else
+        # Fallback to original logic if no meaningful words found
+        local cleaned=$(clean_branch_name "$description")
+        echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
+    fi
+}
+
+# Generate branch name
+if [ -n "$SHORT_NAME" ]; then
+    # Use provided short name, just clean it up
+    BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
+else
+    # Generate from description with smart filtering
+    BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
+fi
+
+# Determine branch number
+if [ -z "$BRANCH_NUMBER" ]; then
+    if [ "$HAS_GIT" = true ]; then
+        # Check existing branches on remotes
+        BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
+    else
+        # Fall back to local directory check
+        HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+        BRANCH_NUMBER=$((HIGHEST + 1))
+    fi
+fi
+
+# Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
+FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
+BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+
+# GitHub enforces a 244-byte limit on branch names
+# Validate and truncate if necessary
+MAX_BRANCH_LENGTH=244
+if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
+    # Calculate how much we need to trim from suffix
+    # Account for: feature number (3) + hyphen (1) = 4 chars
+    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 4))
+    
+    # Truncate suffix at word boundary if possible
+    TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
+    # Remove trailing hyphen if truncation created one
+    TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
+    
+    ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
+    BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
+    
+    >&2 echo "[specify] Warning: Branch name exceeded GitHub's 244-byte limit"
+    >&2 echo "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)"
+    >&2 echo "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"
+fi
+
+if [ "$HAS_GIT" = true ]; then
+    git checkout -b "$BRANCH_NAME"
+else
+    >&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
+fi
+
+FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
+mkdir -p "$FEATURE_DIR"
+
+TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md"
+SPEC_FILE="$FEATURE_DIR/spec.md"
+if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
+
+# Set the SPECIFY_FEATURE environment variable for the current session
+export SPECIFY_FEATURE="$BRANCH_NAME"
+
+if $JSON_MODE; then
+    printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
+else
+    echo "BRANCH_NAME: $BRANCH_NAME"
+    echo "SPEC_FILE: $SPEC_FILE"
+    echo "FEATURE_NUM: $FEATURE_NUM"
+    echo "SPECIFY_FEATURE environment variable set to: $BRANCH_NAME"
+fi

.specify/scripts/bash/setup-plan.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+ARGS=()
+
+for arg in "$@"; do
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json]"
+            echo "  --json    Output results in JSON format"
+            echo "  --help    Show this help message"
+            exit 0 
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+done
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+eval $(get_feature_paths)
+
+# Check if we're on a proper feature branch (only for git repos)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# Ensure the feature directory exists
+mkdir -p "$FEATURE_DIR"
+
+# Copy plan template if it exists
+TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
+if [[ -f "$TEMPLATE" ]]; then
+    cp "$TEMPLATE" "$IMPL_PLAN"
+    echo "Copied plan template to $IMPL_PLAN"
+else
+    echo "Warning: Plan template not found at $TEMPLATE"
+    # Create a basic plan file if template doesn't exist
+    touch "$IMPL_PLAN"
+fi
+
+# Output results
+if $JSON_MODE; then
+    printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
+        "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT"
+else
+    echo "FEATURE_SPEC: $FEATURE_SPEC"
+    echo "IMPL_PLAN: $IMPL_PLAN" 
+    echo "SPECS_DIR: $FEATURE_DIR"
+    echo "BRANCH: $CURRENT_BRANCH"
+    echo "HAS_GIT: $HAS_GIT"
+fi
+

.specify/scripts/bash/update-agent-context.sh

@@ -0,0 +1,799 @@
+#!/usr/bin/env bash
+
+# Update agent context files with information from plan.md
+#
+# This script maintains AI agent context files by parsing feature specifications 
+# and updating agent-specific configuration files with project information.
+#
+# MAIN FUNCTIONS:
+# 1. Environment Validation
+#    - Verifies git repository structure and branch information
+#    - Checks for required plan.md files and templates
+#    - Validates file permissions and accessibility
+#
+# 2. Plan Data Extraction
+#    - Parses plan.md files to extract project metadata
+#    - Identifies language/version, frameworks, databases, and project types
+#    - Handles missing or incomplete specification data gracefully
+#
+# 3. Agent File Management
+#    - Creates new agent context files from templates when needed
+#    - Updates existing agent files with new project information
+#    - Preserves manual additions and custom configurations
+#    - Supports multiple AI agent formats and directory structures
+#
+# 4. Content Generation
+#    - Generates language-specific build/test commands
+#    - Creates appropriate project directory structures
+#    - Updates technology stacks and recent changes sections
+#    - Maintains consistent formatting and timestamps
+#
+# 5. Multi-Agent Support
+#    - Handles agent-specific file paths and naming conventions
+#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, or Amazon Q Developer CLI
+#    - Can update single agents or all existing agent files
+#    - Creates default Claude file if no agent files exist
+#
+# Usage: ./update-agent-context.sh [agent_type]
+# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|shai|q|bob|qoder
+# Leave empty to update all existing agent files
+
+set -e
+
+# Enable strict error handling
+set -u
+set -o pipefail
+
+#==============================================================================
+# Configuration and Global Variables
+#==============================================================================
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+eval $(get_feature_paths)
+
+NEW_PLAN="$IMPL_PLAN"  # Alias for compatibility with existing code
+AGENT_TYPE="${1:-}"
+
+# Agent-specific file paths  
+CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
+GEMINI_FILE="$REPO_ROOT/GEMINI.md"
+COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md"
+CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
+QWEN_FILE="$REPO_ROOT/QWEN.md"
+AGENTS_FILE="$REPO_ROOT/AGENTS.md"
+WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
+KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
+AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
+ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
+CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
+QODER_FILE="$REPO_ROOT/QODER.md"
+AMP_FILE="$REPO_ROOT/AGENTS.md"
+SHAI_FILE="$REPO_ROOT/SHAI.md"
+Q_FILE="$REPO_ROOT/AGENTS.md"
+BOB_FILE="$REPO_ROOT/AGENTS.md"
+
+# Template file
+TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
+
+# Global variables for parsed plan data
+NEW_LANG=""
+NEW_FRAMEWORK=""
+NEW_DB=""
+NEW_PROJECT_TYPE=""
+
+#==============================================================================
+# Utility Functions
+#==============================================================================
+
+log_info() {
+    echo "INFO: $1"
+}
+
+log_success() {
+    echo "✓ $1"
+}
+
+log_error() {
+    echo "ERROR: $1" >&2
+}
+
+log_warning() {
+    echo "WARNING: $1" >&2
+}
+
+# Cleanup function for temporary files
+cleanup() {
+    local exit_code=$?
+    rm -f /tmp/agent_update_*_$$
+    rm -f /tmp/manual_additions_$$
+    exit $exit_code
+}
+
+# Set up cleanup trap
+trap cleanup EXIT INT TERM
+
+#==============================================================================
+# Validation Functions
+#==============================================================================
+
+validate_environment() {
+    # Check if we have a current branch/feature (git or non-git)
+    if [[ -z "$CURRENT_BRANCH" ]]; then
+        log_error "Unable to determine current feature"
+        if [[ "$HAS_GIT" == "true" ]]; then
+            log_info "Make sure you're on a feature branch"
+        else
+            log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if plan.md exists
+    if [[ ! -f "$NEW_PLAN" ]]; then
+        log_error "No plan.md found at $NEW_PLAN"
+        log_info "Make sure you're working on a feature with a corresponding spec directory"
+        if [[ "$HAS_GIT" != "true" ]]; then
+            log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if template exists (needed for new files)
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_warning "Template file not found at $TEMPLATE_FILE"
+        log_warning "Creating new agent files will fail"
+    fi
+}
+
+#==============================================================================
+# Plan Parsing Functions
+#==============================================================================
+
+extract_plan_field() {
+    local field_pattern="$1"
+    local plan_file="$2"
+    
+    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
+        head -1 | \
+        sed "s|^\*\*${field_pattern}\*\*: ||" | \
+        sed 's/^[ \t]*//;s/[ \t]*$//' | \
+        grep -v "NEEDS CLARIFICATION" | \
+        grep -v "^N/A$" || echo ""
+}
+
+parse_plan_data() {
+    local plan_file="$1"
+    
+    if [[ ! -f "$plan_file" ]]; then
+        log_error "Plan file not found: $plan_file"
+        return 1
+    fi
+    
+    if [[ ! -r "$plan_file" ]]; then
+        log_error "Plan file is not readable: $plan_file"
+        return 1
+    fi
+    
+    log_info "Parsing plan data from $plan_file"
+    
+    NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
+    NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
+    NEW_DB=$(extract_plan_field "Storage" "$plan_file")
+    NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
+    
+    # Log what we found
+    if [[ -n "$NEW_LANG" ]]; then
+        log_info "Found language: $NEW_LANG"
+    else
+        log_warning "No language information found in plan"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        log_info "Found framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        log_info "Found database: $NEW_DB"
+    fi
+    
+    if [[ -n "$NEW_PROJECT_TYPE" ]]; then
+        log_info "Found project type: $NEW_PROJECT_TYPE"
+    fi
+}
+
+format_technology_stack() {
+    local lang="$1"
+    local framework="$2"
+    local parts=()
+    
+    # Add non-empty parts
+    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
+    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
+    
+    # Join with proper formatting
+    if [[ ${#parts[@]} -eq 0 ]]; then
+        echo ""
+    elif [[ ${#parts[@]} -eq 1 ]]; then
+        echo "${parts[0]}"
+    else
+        # Join multiple parts with " + "
+        local result="${parts[0]}"
+        for ((i=1; i<${#parts[@]}; i++)); do
+            result="$result + ${parts[i]}"
+        done
+        echo "$result"
+    fi
+}
+
+#==============================================================================
+# Template and Content Generation Functions
+#==============================================================================
+
+get_project_structure() {
+    local project_type="$1"
+    
+    if [[ "$project_type" == *"web"* ]]; then
+        echo "backend/\\nfrontend/\\ntests/"
+    else
+        echo "src/\\ntests/"
+    fi
+}
+
+get_commands_for_language() {
+    local lang="$1"
+    
+    case "$lang" in
+        *"Python"*)
+            echo "cd src && pytest && ruff check ."
+            ;;
+        *"Rust"*)
+            echo "cargo test && cargo clippy"
+            ;;
+        *"JavaScript"*|*"TypeScript"*)
+            echo "npm test \\&\\& npm run lint"
+            ;;
+        *)
+            echo "# Add commands for $lang"
+            ;;
+    esac
+}
+
+get_language_conventions() {
+    local lang="$1"
+    echo "$lang: Follow standard conventions"
+}
+
+create_new_agent_file() {
+    local target_file="$1"
+    local temp_file="$2"
+    local project_name="$3"
+    local current_date="$4"
+    
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_error "Template not found at $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    if [[ ! -r "$TEMPLATE_FILE" ]]; then
+        log_error "Template file is not readable: $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    log_info "Creating new agent context file from template..."
+    
+    if ! cp "$TEMPLATE_FILE" "$temp_file"; then
+        log_error "Failed to copy template file"
+        return 1
+    fi
+    
+    # Replace template placeholders
+    local project_structure
+    project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
+    
+    local commands
+    commands=$(get_commands_for_language "$NEW_LANG")
+    
+    local language_conventions
+    language_conventions=$(get_language_conventions "$NEW_LANG")
+    
+    # Perform substitutions with error checking using safer approach
+    # Escape special characters for sed by using a different delimiter or escaping
+    local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    
+    # Build technology stack and recent change strings conditionally
+    local tech_stack
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
+    elif [[ -n "$escaped_lang" ]]; then
+        tech_stack="- $escaped_lang ($escaped_branch)"
+    elif [[ -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_framework ($escaped_branch)"
+    else
+        tech_stack="- ($escaped_branch)"
+    fi
+
+    local recent_change
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
+    elif [[ -n "$escaped_lang" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang"
+    elif [[ -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_framework"
+    else
+        recent_change="- $escaped_branch: Added"
+    fi
+
+    local substitutions=(
+        "s|\[PROJECT NAME\]|$project_name|"
+        "s|\[DATE\]|$current_date|"
+        "s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
+        "s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
+        "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
+        "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
+        "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
+    )
+    
+    for substitution in "${substitutions[@]}"; do
+        if ! sed -i.bak -e "$substitution" "$temp_file"; then
+            log_error "Failed to perform substitution: $substitution"
+            rm -f "$temp_file" "$temp_file.bak"
+            return 1
+        fi
+    done
+    
+    # Convert \n sequences to actual newlines
+    newline=$(printf '\n')
+    sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
+    
+    # Clean up backup files
+    rm -f "$temp_file.bak" "$temp_file.bak2"
+    
+    return 0
+}
+
+
+
+
+update_existing_agent_file() {
+    local target_file="$1"
+    local current_date="$2"
+    
+    log_info "Updating existing agent context file..."
+    
+    # Use a single temporary file for atomic update
+    local temp_file
+    temp_file=$(mktemp) || {
+        log_error "Failed to create temporary file"
+        return 1
+    }
+    
+    # Process the file in one pass
+    local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
+    local new_tech_entries=()
+    local new_change_entry=""
+    
+    # Prepare new technology entries
+    if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
+        new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
+        new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
+    fi
+    
+    # Prepare new change entry
+    if [[ -n "$tech_stack" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
+    elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
+    fi
+    
+    # Check if sections exist in the file
+    local has_active_technologies=0
+    local has_recent_changes=0
+    
+    if grep -q "^## Active Technologies" "$target_file" 2>/dev/null; then
+        has_active_technologies=1
+    fi
+    
+    if grep -q "^## Recent Changes" "$target_file" 2>/dev/null; then
+        has_recent_changes=1
+    fi
+    
+    # Process file line by line
+    local in_tech_section=false
+    local in_changes_section=false
+    local tech_entries_added=false
+    local changes_entries_added=false
+    local existing_changes_count=0
+    local file_ended=false
+    
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        # Handle Active Technologies section
+        if [[ "$line" == "## Active Technologies" ]]; then
+            echo "$line" >> "$temp_file"
+            in_tech_section=true
+            continue
+        elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            # Add new tech entries before closing the section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            in_tech_section=false
+            continue
+        elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
+            # Add new tech entries before empty line in tech section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            continue
+        fi
+        
+        # Handle Recent Changes section
+        if [[ "$line" == "## Recent Changes" ]]; then
+            echo "$line" >> "$temp_file"
+            # Add new change entry right after the heading
+            if [[ -n "$new_change_entry" ]]; then
+                echo "$new_change_entry" >> "$temp_file"
+            fi
+            in_changes_section=true
+            changes_entries_added=true
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            echo "$line" >> "$temp_file"
+            in_changes_section=false
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
+            # Keep only first 2 existing changes
+            if [[ $existing_changes_count -lt 2 ]]; then
+                echo "$line" >> "$temp_file"
+                ((existing_changes_count++))
+            fi
+            continue
+        fi
+        
+        # Update timestamp
+        if [[ "$line" =~ \*\*Last\ updated\*\*:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
+            echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
+        else
+            echo "$line" >> "$temp_file"
+        fi
+    done < "$target_file"
+    
+    # Post-loop check: if we're still in the Active Technologies section and haven't added new entries
+    if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    # If sections don't exist, add them at the end of the file
+    if [[ $has_active_technologies -eq 0 ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        echo "" >> "$temp_file"
+        echo "## Active Technologies" >> "$temp_file"
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    if [[ $has_recent_changes -eq 0 ]] && [[ -n "$new_change_entry" ]]; then
+        echo "" >> "$temp_file"
+        echo "## Recent Changes" >> "$temp_file"
+        echo "$new_change_entry" >> "$temp_file"
+        changes_entries_added=true
+    fi
+    
+    # Move temp file to target atomically
+    if ! mv "$temp_file" "$target_file"; then
+        log_error "Failed to update target file"
+        rm -f "$temp_file"
+        return 1
+    fi
+    
+    return 0
+}
+#==============================================================================
+# Main Agent File Update Function
+#==============================================================================
+
+update_agent_file() {
+    local target_file="$1"
+    local agent_name="$2"
+    
+    if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
+        log_error "update_agent_file requires target_file and agent_name parameters"
+        return 1
+    fi
+    
+    log_info "Updating $agent_name context file: $target_file"
+    
+    local project_name
+    project_name=$(basename "$REPO_ROOT")
+    local current_date
+    current_date=$(date +%Y-%m-%d)
+    
+    # Create directory if it doesn't exist
+    local target_dir
+    target_dir=$(dirname "$target_file")
+    if [[ ! -d "$target_dir" ]]; then
+        if ! mkdir -p "$target_dir"; then
+            log_error "Failed to create directory: $target_dir"
+            return 1
+        fi
+    fi
+    
+    if [[ ! -f "$target_file" ]]; then
+        # Create new file from template
+        local temp_file
+        temp_file=$(mktemp) || {
+            log_error "Failed to create temporary file"
+            return 1
+        }
+        
+        if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
+            if mv "$temp_file" "$target_file"; then
+                log_success "Created new $agent_name context file"
+            else
+                log_error "Failed to move temporary file to $target_file"
+                rm -f "$temp_file"
+                return 1
+            fi
+        else
+            log_error "Failed to create new agent file"
+            rm -f "$temp_file"
+            return 1
+        fi
+    else
+        # Update existing file
+        if [[ ! -r "$target_file" ]]; then
+            log_error "Cannot read existing file: $target_file"
+            return 1
+        fi
+        
+        if [[ ! -w "$target_file" ]]; then
+            log_error "Cannot write to existing file: $target_file"
+            return 1
+        fi
+        
+        if update_existing_agent_file "$target_file" "$current_date"; then
+            log_success "Updated existing $agent_name context file"
+        else
+            log_error "Failed to update existing agent file"
+            return 1
+        fi
+    fi
+    
+    return 0
+}
+
+#==============================================================================
+# Agent Selection and Processing
+#==============================================================================
+
+update_specific_agent() {
+    local agent_type="$1"
+    
+    case "$agent_type" in
+        claude)
+            update_agent_file "$CLAUDE_FILE" "Claude Code"
+            ;;
+        gemini)
+            update_agent_file "$GEMINI_FILE" "Gemini CLI"
+            ;;
+        copilot)
+            update_agent_file "$COPILOT_FILE" "GitHub Copilot"
+            ;;
+        cursor-agent)
+            update_agent_file "$CURSOR_FILE" "Cursor IDE"
+            ;;
+        qwen)
+            update_agent_file "$QWEN_FILE" "Qwen Code"
+            ;;
+        opencode)
+            update_agent_file "$AGENTS_FILE" "opencode"
+            ;;
+        codex)
+            update_agent_file "$AGENTS_FILE" "Codex CLI"
+            ;;
+        windsurf)
+            update_agent_file "$WINDSURF_FILE" "Windsurf"
+            ;;
+        kilocode)
+            update_agent_file "$KILOCODE_FILE" "Kilo Code"
+            ;;
+        auggie)
+            update_agent_file "$AUGGIE_FILE" "Auggie CLI"
+            ;;
+        roo)
+            update_agent_file "$ROO_FILE" "Roo Code"
+            ;;
+        codebuddy)
+            update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
+            ;;
+        qoder)
+            update_agent_file "$QODER_FILE" "Qoder CLI"
+            ;;
+        amp)
+            update_agent_file "$AMP_FILE" "Amp"
+            ;;
+        shai)
+            update_agent_file "$SHAI_FILE" "SHAI"
+            ;;
+        q)
+            update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
+            ;;
+        bob)
+            update_agent_file "$BOB_FILE" "IBM Bob"
+            ;;
+        *)
+            log_error "Unknown agent type '$agent_type'"
+            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|amp|shai|q|bob|qoder"
+            exit 1
+            ;;
+    esac
+}
+
+update_all_existing_agents() {
+    local found_agent=false
+    
+    # Check each possible agent file and update if it exists
+    if [[ -f "$CLAUDE_FILE" ]]; then
+        update_agent_file "$CLAUDE_FILE" "Claude Code"
+        found_agent=true
+    fi
+    
+    if [[ -f "$GEMINI_FILE" ]]; then
+        update_agent_file "$GEMINI_FILE" "Gemini CLI"
+        found_agent=true
+    fi
+    
+    if [[ -f "$COPILOT_FILE" ]]; then
+        update_agent_file "$COPILOT_FILE" "GitHub Copilot"
+        found_agent=true
+    fi
+    
+    if [[ -f "$CURSOR_FILE" ]]; then
+        update_agent_file "$CURSOR_FILE" "Cursor IDE"
+        found_agent=true
+    fi
+    
+    if [[ -f "$QWEN_FILE" ]]; then
+        update_agent_file "$QWEN_FILE" "Qwen Code"
+        found_agent=true
+    fi
+    
+    if [[ -f "$AGENTS_FILE" ]]; then
+        update_agent_file "$AGENTS_FILE" "Codex/opencode"
+        found_agent=true
+    fi
+    
+    if [[ -f "$WINDSURF_FILE" ]]; then
+        update_agent_file "$WINDSURF_FILE" "Windsurf"
+        found_agent=true
+    fi
+    
+    if [[ -f "$KILOCODE_FILE" ]]; then
+        update_agent_file "$KILOCODE_FILE" "Kilo Code"
+        found_agent=true
+    fi
+
+    if [[ -f "$AUGGIE_FILE" ]]; then
+        update_agent_file "$AUGGIE_FILE" "Auggie CLI"
+        found_agent=true
+    fi
+    
+    if [[ -f "$ROO_FILE" ]]; then
+        update_agent_file "$ROO_FILE" "Roo Code"
+        found_agent=true
+    fi
+
+    if [[ -f "$CODEBUDDY_FILE" ]]; then
+        update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
+        found_agent=true
+    fi
+
+    if [[ -f "$SHAI_FILE" ]]; then
+        update_agent_file "$SHAI_FILE" "SHAI"
+        found_agent=true
+    fi
+
+    if [[ -f "$QODER_FILE" ]]; then
+        update_agent_file "$QODER_FILE" "Qoder CLI"
+        found_agent=true
+    fi
+
+    if [[ -f "$Q_FILE" ]]; then
+        update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
+        found_agent=true
+    fi
+    
+    if [[ -f "$BOB_FILE" ]]; then
+        update_agent_file "$BOB_FILE" "IBM Bob"
+        found_agent=true
+    fi
+    
+    # If no agent files exist, create a default Claude file
+    if [[ "$found_agent" == false ]]; then
+        log_info "No existing agent files found, creating default Claude file..."
+        update_agent_file "$CLAUDE_FILE" "Claude Code"
+    fi
+}
+print_summary() {
+    echo
+    log_info "Summary of changes:"
+    
+    if [[ -n "$NEW_LANG" ]]; then
+        echo "  - Added language: $NEW_LANG"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        echo "  - Added framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        echo "  - Added database: $NEW_DB"
+    fi
+    
+    echo
+
+    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|codebuddy|shai|q|bob|qoder]"
+}
+
+#==============================================================================
+# Main Execution
+#==============================================================================
+
+main() {
+    # Validate environment before proceeding
+    validate_environment
+    
+    log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
+    
+    # Parse the plan file to extract project information
+    if ! parse_plan_data "$NEW_PLAN"; then
+        log_error "Failed to parse plan data"
+        exit 1
+    fi
+    
+    # Process based on agent type argument
+    local success=true
+    
+    if [[ -z "$AGENT_TYPE" ]]; then
+        # No specific agent provided - update all existing agent files
+        log_info "No agent specified, updating all existing agent files..."
+        if ! update_all_existing_agents; then
+            success=false
+        fi
+    else
+        # Specific agent provided - update only that agent
+        log_info "Updating specific agent: $AGENT_TYPE"
+        if ! update_specific_agent "$AGENT_TYPE"; then
+            success=false
+        fi
+    fi
+    
+    # Print summary
+    print_summary
+    
+    if [[ "$success" == true ]]; then
+        log_success "Agent context update completed successfully"
+        exit 0
+    else
+        log_error "Agent context update completed with errors"
+        exit 1
+    fi
+}
+
+# Execute main function if script is run directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi
+

.specify/templates/agent-file-template.md

@@ -0,0 +1,28 @@
+# [PROJECT NAME] Development Guidelines
+
+Auto-generated from all feature plans. Last updated: [DATE]
+
+## Active Technologies
+
+[EXTRACTED FROM ALL PLAN.MD FILES]
+
+## Project Structure
+
+```text
+[ACTUAL STRUCTURE FROM PLANS]
+```
+
+## Commands
+
+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
+
+## Code Style
+
+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
+
+## Recent Changes
+
+[LAST 3 FEATURES AND WHAT THEY ADDED]
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

.specify/templates/checklist-template.md

@@ -0,0 +1,40 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+  
+  The /speckit.checklist command MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+  
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference

.specify/templates/plan-template.md

@@ -0,0 +1,104 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [single/web/mobile - determines source structure]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on constitution file]
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

.specify/templates/spec-template.md

@@ -0,0 +1,115 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]

.specify/templates/tasks-template.md

@@ -0,0 +1,251 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+  
+  The /speckit.tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+  
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+  
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence

Dockerfile

@@ -3,16 +3,19 @@ ARG QUARTO_VERSION="1.4.550"
 # Use the Quarto base image
 FROM ghcr.io/quarto-dev/quarto:${QUARTO_VERSION} AS builder
 
-COPY src /app
+# Copy project files
+COPY . /app
 WORKDIR /app
 
-# Install Python requirements
+# Install pixi
 USER root
-RUN apt-get update && apt-get install -y python3 python3-pip
-COPY requirements.txt /app/
-RUN pip3 install -r requirements.txt
+RUN curl -fsSL https://pixi.sh/install.sh | bash
+ENV PATH="/root/.pixi/bin:$PATH"
 
-RUN quarto render .
+# Install dependencies and render the site
+RUN pixi install
+RUN pixi run render
 
+# Expose port and serve the site using pixi
 EXPOSE 7860
-CMD ["python3", "-m", "http.server", "7860", "--directory", "_site"]
+CMD ["pixi", "run", "serve"]

docs/content-plan.md

@@ -0,0 +1,148 @@
+# 12-Month Content Plan for Kashi Coding Handbook
+
+## "Modern Python: From Packages to Production AI"
+
+---
+
+## Q1 2026: Modern Python Foundation (Jan-Mar)
+
+**Theme:** Setting up the modern Python development stack
+
+### January: Package Management Evolution
+
+**Post 1: "Beyond pip: Package Management with pixi.sh"**
+
+- Why conda-forge matters for data science/AI
+- Installing pixi and basic commands
+- Creating reproducible environments
+- Comparison with Poetry, PDM, uv
+- When to use each tool
+- GitHub repo: `pixi-starter-templates`
+
+**Post 2: "Multi-Project Workspace with pixi"**
+
+- Managing multiple related projects
+- Shared dependencies across projects
+- Lock files and reproducibility
+- Integration with Docker
+- GitHub repo: `pixi-monorepo-example`
+
+### February: Professional CLI Development
+
+**Post 3: "Building CLI Tools with Typer"**
+
+- Type hints-driven interfaces
+- Commands, options, and arguments
+- Auto-generated documentation
+- Testing CLI applications with pytest
+- GitHub repo: `typer-starter-kit`
+
+**Post 4: "Advanced CLI Patterns: Progress Bars, Config Files, and Plugins"**
+
+- Rich integration for beautiful output
+- Configuration management (TOML, YAML)
+- Plugin architecture
+- Distributing CLI tools
+- GitHub repo: `advanced-cli-patterns`
+
+### March: Docker & Containerization
+
+**Post 5: "Docker for Python Development"**
+
+- Multi-stage builds for Python apps
+- Managing dependencies in containers
+- Docker Compose for development stacks
+- Volume mounting and hot reload
+- GitHub repo: `python-docker-templates`
+
+**Post 6: "Containerizing AI Applications"**
+
+- GPU support in Docker
+- Model serving containers
+- Environment variables and secrets
+- Your TrueNAS/Coolify setup as case study
+- GitHub repo: `ai-docker-stack`
+
+---
+
+## Q2 2026: LLM Applications & Foundations (Apr-Jun)
+
+**Theme:** Building blocks for AI applications
+
+### April: LangChain Fundamentals
+
+**Post 7: "Building Your First RAG Application with LangChain"**
+
+- Document loaders and text splitters
+- Vector stores (using Supabase pgvector!)
+- Retrieval chains
+- Basic prompt engineering
+- GitHub repo: `langchain-rag-starter`
+
+**Post 8: "LangChain Memory Systems"**
+
+- Conversation memory patterns
+- Message history with Supabase
+- Context window management
+- When to use which memory type
+- GitHub repo: `langchain-memory-examples`
+
+### May: MCP (Model Context Protocol)
+
+**Post 9: "Building Your First MCP Server"**
+
+- MCP architecture overview
+- Database connector server (your actual work!)
+- Tool creation and registration
+- Testing MCP servers
+- GitHub repo: `mcp-starter-pack`
+
+**Post 10: "Advanced MCP: Custom Tools and Integrations"**
+
+- File system access tools
+- API integration tools
+- Docker container management tools
+- Connecting MCP to LangChain agents
+- GitHub repo: `mcp-advanced-tools`
+
+### June: Agent Observability
+
+**Post 11: "Observability for LLM Applications"**
+
+- Logging strategies for LLM calls
+- Token counting and cost tracking
+- LangSmith integration
+- Debugging agent decisions
+- GitHub repo: `llm-observability-toolkit`
+
+**Post 12: "Testing Non-Deterministic Systems"**
+
+- Testing strategies for LLM apps
+- Assertion patterns for AI outputs
+- Evaluation frameworks
+- CI/CD for AI applications
+- GitHub repo: `ai-testing-patterns`
+
+---
+
+## Q3 2026: Multi-Agent Systems & Robotics (Jul-Sep)
+
+**Theme:** Orchestrating multiple agents and physical systems
+
+### July: CrewAI Deep Dive
+
+**Post 13: "Building Multi-Agent Systems with CrewAI"**
+
+- Agent roles and goals
+- Task delegation patterns
+- Sequential vs hierarchical crews
+- Real-world example: research automation
+- GitHub repo: `crewai-examples`
+
+**Post 14: "CrewAI Advanced Patterns"**
+
+- Custom tools for agents
+- Inter-agent communication
+- Error handling and recovery
+- Observability for CrewAI (connects to Post 11)
+- GitHub repo: `crewai-advanced`

docs/docker-ai.md

@@ -0,0 +1,487 @@
+# Docker AI: Deploying Local LLMs and MCP Servers
+
+This guide covers the latest ways to use Docker for deploying local Large Language Model (LLM) models and Model Context Protocol (MCP) servers.
+
+## Table of Contents
+
+- [Docker Compose Models](#docker-compose-models)
+- [Docker Model Runner](#docker-model-runner)
+- [Docker MCP Toolkit](#docker-mcp-toolkit)
+- [Common Use Cases](#common-use-cases)
+
+---
+
+## Docker Compose Models
+
+Docker Compose v2.38+ introduces a standardized way to define AI model dependencies using the `models` top-level element in your Compose files.
+
+### Prerequisites
+
+- Docker Compose v2.38 or later
+- Docker Model Runner (DMR) or compatible cloud providers
+- For DMR: See [requirements](https://docs.docker.com/ai/model-runner/#requirements)
+
+### Basic Model Definition
+
+Define models in your `docker-compose.yml`:
+
+```yaml
+services:
+  chat-app:
+    image: my-chat-app
+    models:
+      - llm
+
+models:
+  llm:
+    model: ai/smollm2
+```
+
+This configuration:
+- Defines a service `chat-app` that uses a model named `llm`
+- References the `ai/smollm2` model image from Docker Hub
+
+### Model Configuration Options
+
+Configure models with various runtime parameters:
+
+```yaml
+models:
+  llm:
+    model: ai/smollm2
+    context_size: 1024
+    runtime_flags:
+      - "--a-flag"
+      - "--another-flag=42"
+```
+
+**Key configuration options:**
+
+- **`model`** (required): OCI artifact identifier for the model
+- **`context_size`**: Maximum token context size (keep as small as feasible for your needs)
+- **`runtime_flags`**: Command-line flags passed to the inference engine (e.g., [llama.cpp parameters](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md))
+- **`x-*`**: Platform-specific extension attributes
+
+### Service Model Binding
+
+#### Short Syntax
+
+The simplest way to bind models to services:
+
+```yaml
+services:
+  app:
+    image: my-app
+    models:
+      - llm
+      - embedding-model
+
+models:
+  llm:
+    model: ai/smollm2
+  embedding-model:
+    model: ai/all-minilm
+```
+
+Auto-generated environment variables:
+- `LLM_URL` - URL to access the LLM model
+- `LLM_MODEL` - Model identifier
+- `EMBEDDING_MODEL_URL` - URL to access the embedding model
+- `EMBEDDING_MODEL_MODEL` - Model identifier
+
+#### Long Syntax
+
+Customize environment variable names:
+
+```yaml
+services:
+  app:
+    image: my-app
+    models:
+      llm:
+        endpoint_var: AI_MODEL_URL
+        model_var: AI_MODEL_NAME
+      embedding-model:
+        endpoint_var: EMBEDDING_URL
+        model_var: EMBEDDING_NAME
+
+models:
+  llm:
+    model: ai/smollm2
+  embedding-model:
+    model: ai/all-minilm
+```
+
+### Platform Portability
+
+#### Docker Model Runner
+
+When Docker Model Runner is enabled locally:
+
+```yaml
+services:
+  chat-app:
+    image: my-chat-app
+    models:
+      llm:
+        endpoint_var: AI_MODEL_URL
+        model_var: AI_MODEL_NAME
+
+models:
+  llm:
+    model: ai/smollm2
+    context_size: 4096
+    runtime_flags:
+      - "--no-prefill-assistant"
+```
+
+Docker Model Runner will:
+- Pull and run the model locally
+- Provide endpoint URLs
+- Inject environment variables into the service
+
+#### Cloud Providers
+
+The same Compose file works on cloud providers:
+
+```yaml
+services:
+  chat-app:
+    image: my-chat-app
+    models:
+      - llm
+
+models:
+  llm:
+    model: ai/smollm2
+    # Cloud-specific configurations
+    x-cloud-options:
+      - "cloud.instance-type=gpu-small"
+      - "cloud.region=us-west-2"
+```
+
+Cloud providers may:
+- Use managed AI services
+- Apply cloud-specific optimizations
+- Provide monitoring and logging
+- Handle model versioning automatically
+
+### Common Runtime Configurations
+
+#### Development Mode
+
+```yaml
+models:
+  dev_model:
+    model: ai/model
+    context_size: 4096
+    runtime_flags:
+      - "--verbose"
+      - "--verbose-prompt"
+      - "--log-prefix"
+      - "--log-timestamps"
+      - "--log-colors"
+```
+
+#### Conservative (Disabled Reasoning)
+
+```yaml
+models:
+  conservative_model:
+    model: ai/model
+    context_size: 4096
+    runtime_flags:
+      - "--temp"
+      - "0.1"
+      - "--top-k"
+      - "1"
+      - "--reasoning-budget"
+      - "0"
+```
+
+#### Creative (High Randomness)
+
+```yaml
+models:
+  creative_model:
+    model: ai/model
+    context_size: 4096
+    runtime_flags:
+      - "--temp"
+      - "1"
+      - "--top-p"
+      - "0.9"
+```
+
+#### Highly Deterministic
+
+```yaml
+models:
+  deterministic_model:
+    model: ai/model
+    context_size: 4096
+    runtime_flags:
+      - "--temp"
+      - "0"
+      - "--top-k"
+      - "1"
+```
+
+#### Concurrent Processing
+
+```yaml
+models:
+  concurrent_model:
+    model: ai/model
+    context_size: 2048
+    runtime_flags:
+      - "--threads"
+      - "8"
+      - "--mlock"  # Lock memory to prevent swapping
+```
+
+---
+
+## Docker Model Runner
+
+Docker Model Runner (DMR) enables running AI models locally with minimal setup. It integrates seamlessly with Docker Compose models.
+
+### Key Features
+
+- **Local model execution**: Run models on your local machine
+- **GPU support**: Leverage local GPU resources
+- **Automatic model pulling**: Models are pulled from Docker Hub as needed
+- **OpenAI-compatible API**: Expose models via standard API endpoints
+
+### Use Cases
+
+- **Development and testing**: Test AI applications locally before cloud deployment
+- **Privacy-sensitive workloads**: Keep data on-premises
+- **Offline development**: Work without internet connectivity
+- **Cost optimization**: Avoid cloud inference costs
+
+---
+
+## Docker MCP Toolkit
+
+The Docker MCP (Model Context Protocol) Toolkit provides a secure, standardized way to connect AI agents to external tools and data sources.
+
+### What is MCP?
+
+Model Context Protocol (MCP) is an open, client-server protocol that standardizes how applications provide context and functionality to Large Language Models. It allows AI agents to:
+
+- Interact with external tools and APIs
+- Access databases and services
+- Execute code in isolated environments
+- Retrieve real-world data
+
+### Docker MCP Components
+
+#### 1. MCP Gateway
+
+The [Docker MCP Gateway](https://github.com/docker/mcp-gateway/) is the core open-source component that:
+
+- Manages MCP containers
+- Provides a unified endpoint for AI applications
+- Mediates between agents and MCP servers
+- Enables dynamic MCP discovery and configuration
+
+#### 2. MCP Catalog
+
+The [Docker MCP Catalog](https://hub.docker.com/mcp) is a curated collection of trusted, containerized MCP servers including:
+
+- **270+ curated servers** from publishers like Stripe, Elastic, Grafana
+- **Publisher trust levels**: Distinguish between official, verified, and community servers
+- **Commit pinning**: Each server tied to specific Git commits for verifiability
+- **AI-audited updates**: Automated reviews of code changes
+
+#### 3. MCP Toolkit (Docker Desktop)
+
+A management interface in Docker Desktop for:
+
+- Discovering MCP servers
+- Configuring and managing servers
+- One-click deployment
+- Centralized authentication
+
+### Dynamic MCPs: Smart Search and Tool Composition
+
+Recent enhancements enable agents to dynamically discover and configure MCP servers:
+
+#### Smart Search Features
+
+**`mcp-find`**: Find MCP servers by name or description
+```
+Agent: "Find MCP servers for web searching"
+→ Returns: DuckDuckGo MCP, Brave Search MCP, etc.
+```
+
+**`mcp-add`**: Add MCP servers to the current session
+```
+Agent: "Add the DuckDuckGo MCP server"
+→ Server is pulled, configured, and made available
+```
+
+#### Benefits of Dynamic MCPs
+
+1. **No manual configuration**: Agents discover and add tools as needed
+2. **Reduced token usage**: Only load tools when required
+3. **Autonomous operation**: Agents manage their own tool ecosystem
+4. **Secure sandbox**: Tool composition happens in isolated environments
+
+### Security Features
+
+Docker MCP Toolkit implements multiple security layers:
+
+1. **Containerization**: Strong isolation limits blast radius
+2. **Commit pinning**: Precise attribution and verification
+3. **Automated auditing**: AI-powered code reviews
+4. **Publisher trust levels**: Clear indicators of server origin
+5. **Isolated execution**: MCP servers run in separate containers
+
+### Using MCP with Docker Compose
+
+Example `docker-compose.yml` for MCP servers:
+
+```yaml
+services:
+  mcp-gateway:
+    image: docker/mcp-gateway:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - mcp-data:/data
+    environment:
+      - MCP_CATALOG_URL=https://hub.docker.com/mcp
+
+  my-app:
+    image: my-ai-app
+    depends_on:
+      - mcp-gateway
+    environment:
+      - MCP_GATEWAY_URL=http://mcp-gateway:3000
+
+volumes:
+  mcp-data:
+```
+
+### Submitting MCP Servers
+
+To contribute MCP servers to the Docker MCP Catalog:
+
+1. Follow the [submission guidance](https://github.com/docker/mcp-registry/blob/main/CONTRIBUTING.md)
+2. Submit to the [MCP Registry](https://github.com/docker/mcp-registry)
+3. Servers undergo automated and manual review
+4. Approved servers appear in the catalog with appropriate trust levels
+
+---
+
+## Common Use Cases
+
+### 1. Local AI Development Environment
+
+```yaml
+services:
+  dev-app:
+    build: .
+    models:
+      - llm
+      - embeddings
+    depends_on:
+      - mcp-gateway
+
+  mcp-gateway:
+    image: docker/mcp-gateway:latest
+    ports:
+      - "3000:3000"
+
+models:
+  llm:
+    model: ai/smollm2
+    context_size: 4096
+    runtime_flags:
+      - "--verbose"
+      - "--log-colors"
+  
+  embeddings:
+    model: ai/all-minilm
+```
+
+### 2. Multi-Model AI Application
+
+```yaml
+services:
+  chat-service:
+    image: my-chat-service
+    models:
+      chat-model:
+        endpoint_var: CHAT_MODEL_URL
+        model_var: CHAT_MODEL_NAME
+      
+  code-service:
+    image: my-code-service
+    models:
+      code-model:
+        endpoint_var: CODE_MODEL_URL
+        model_var: CODE_MODEL_NAME
+
+models:
+  chat-model:
+    model: ai/smollm2
+    context_size: 2048
+    runtime_flags:
+      - "--temp"
+      - "0.7"
+  
+  code-model:
+    model: ai/codellama
+    context_size: 4096
+    runtime_flags:
+      - "--temp"
+      - "0.2"
+```
+
+### 3. AI Agent with Dynamic MCP Tools
+
+```yaml
+services:
+  ai-agent:
+    image: my-ai-agent
+    environment:
+      - MCP_GATEWAY_URL=http://mcp-gateway:3000
+      - ENABLE_DYNAMIC_MCPS=true
+    depends_on:
+      - mcp-gateway
+      - llm-service
+    models:
+      - agent-llm
+
+  mcp-gateway:
+    image: docker/mcp-gateway:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./mcp-catalog.yml:/config/catalog.yml
+
+models:
+  agent-llm:
+    model: ai/smollm2
+    context_size: 4096
+```
+
+---
+
+## Additional Resources
+
+- [Docker AI Documentation](https://docs.docker.com/ai/)
+- [Docker Compose Models Reference](https://docs.docker.com/ai/compose/models-and-compose/)
+- [Docker Model Runner](https://docs.docker.com/ai/model-runner/)
+- [Docker MCP Gateway (GitHub)](https://github.com/docker/mcp-gateway/)
+- [Docker MCP Catalog](https://hub.docker.com/mcp)
+- [MCP Registry](https://github.com/docker/mcp-registry)
+- [Dynamic MCPs Blog Post](https://www.docker.com/blog/dynamic-mcps-stop-hardcoding-your-agents-world/)
+- [MCP Security Blog Post](https://www.docker.com/blog/enhancing-mcp-trust-with-the-docker-mcp-catalog/)
+
+---
+
+**Last Updated**: December 2024

docs/learning-path.md

@@ -0,0 +1,1716 @@
+# Learning Path: Building AI-Powered CLI Tools with Python
+
+A structured learning path for developers with basic Python knowledge who want to build AI-powered CLI tools using modern development practices.
+
+## 🎯 Prerequisites
+
+**What You Should Know:**
+- Basic Python syntax (variables, functions, loops, conditionals)
+- How to run Python scripts from the command line
+- Basic understanding of files and directories
+- Familiarity with text editors or IDEs
+
+**What You'll Learn:**
+- Building professional CLI applications
+- Integrating AI/LLM capabilities
+- Modern Python package management with pixi
+- AI-assisted development with GitHub Copilot
+- Package publishing and distribution
+
+---
+
+## 📚 Learning Phases
+
+### Phase 1: Foundation Setup (Week 1)
+
+#### 1.1 Development Environment Setup
+
+**Install Required Tools:**
+
+```bash
+# Install pixi (cross-platform package manager)
+curl -fsSL https://pixi.sh/install.sh | bash
+
+# Verify installation
+pixi --version
+
+# Install Git (if not already installed)
+# Linux: sudo apt install git
+# macOS: brew install git
+# Windows: Download from git-scm.com
+```
+
+**Set Up GitHub Copilot:**
+1. Install VS Code or your preferred IDE
+2. Install GitHub Copilot extension
+3. Sign in with your GitHub account (requires Copilot subscription)
+4. Complete the Copilot quickstart tutorial
+
+**Resources:**
+- [Pixi Documentation](https://pixi.sh/latest/)
+- [GitHub Copilot Getting Started](https://docs.github.com/en/copilot/getting-started-with-github-copilot)
+- [VS Code Python Setup](https://code.visualstudio.com/docs/python/python-tutorial)
+
+#### 1.2 Understanding Modern Python Project Structure
+
+**Learn About:**
+- Project organization (src layout vs flat layout)
+- Virtual environments and dependency isolation
+- Configuration files (`pyproject.toml`, `pixi.toml`)
+- Version control with Git
+
+**Hands-On Exercise:**
+Create a simple "Hello World" project with pixi:
+
+```bash
+# Create new project
+pixi init my-first-cli
+cd my-first-cli
+
+# Add Python dependency
+pixi add python
+
+# Create a simple script
+mkdir src
+echo 'print("Hello from pixi!")' > src/hello.py
+
+# Run it
+pixi run python src/hello.py
+```
+
+**Use Copilot to:**
+- Generate a `.gitignore` file for Python projects
+- Create a basic `README.md` template
+- Write docstrings for your functions
+
+---
+
+### Phase 2: CLI Development Fundamentals (Week 2-3)
+
+#### 2.1 Building Your First CLI with Typer
+
+**Learning Objectives:**
+- Understand command-line argument parsing with type hints
+- Create commands, options, and flags using Python types
+- Handle user input and validation
+- Display formatted output with Rich integration
+
+**Project: Simple File Organizer CLI**
+
+> **Note**: This is a simplified version for learning CLI basics. For a comprehensive, production-ready example that integrates Docker AI, MCP servers, and multi-agent systems, see the [FileOrganizer project](projects/FileOrganizer.md) in Phase 7.
+
+```bash
+# Initialize project with pixi
+pixi init file-organizer-cli
+cd file-organizer-cli
+
+# Add dependencies
+pixi add python typer rich
+
+# Create project structure
+mkdir -p src/file_organizer
+touch src/file_organizer/__init__.py
+touch src/file_organizer/cli.py
+```
+
+**Example CLI Structure (use Copilot to help generate):**
+
+```python
+# src/file_organizer/cli.py
+import typer
+from pathlib import Path
+from rich.console import Console
+from typing import Optional
+
+app = typer.Typer(help="File organizer CLI tool")
+console = Console()
+
+@app.command()
+def organize(
+    directory: Path = typer.Argument(..., help="Directory to organize", exists=True),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes without executing"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output")
+):
+    """Organize files in DIRECTORY by extension."""
+    if verbose:
+        console.print(f"[blue]Organizing files in: {directory}[/blue]")
+    
+    # Use Copilot to generate the organization logic
+    if dry_run:
+        console.print("[yellow]DRY RUN - No changes will be made[/yellow]")
+    
+    pass
+
+@app.command()
+def stats(directory: Path = typer.Argument(..., exists=True)):
+    """Show statistics about files in DIRECTORY."""
+    # Use Copilot to generate statistics logic
+    pass
+
+if __name__ == '__main__':
+    app()
+```
+
+**Copilot Prompts to Try:**
+- "Create a function to organize files by extension using pathlib"
+- "Add error handling for file operations with try-except"
+- "Generate help text and docstrings for CLI commands"
+- "Add progress bar using rich library for file processing"
+
+**Resources:**
+- [Typer Documentation](https://typer.tiangolo.com/)
+- [Typer Tutorial](https://typer.tiangolo.com/tutorial/)
+- [Rich Documentation](https://rich.readthedocs.io/)
+
+#### 2.2 Configuration and Settings Management
+
+**Learn About:**
+- Reading configuration files (YAML, TOML, JSON)
+- Environment variables
+- User preferences and defaults
+- Configuration validation with Pydantic
+
+**Add to Your Project:**
+
+```bash
+# Add configuration dependencies
+pixi add pydantic pyyaml python-dotenv
+```
+
+**Use Copilot to Generate:**
+- Configuration schema with Pydantic
+- Config file loader functions
+- Environment variable handling
+
+---
+
+### Phase 3: AI Integration Basics (Week 4-5)
+
+#### 3.1 Understanding HuggingFace and LLM APIs
+
+**Learning Objectives:**
+- API authentication and token management
+- Using HuggingFace Inference API and local models
+- Making API requests with transformers and huggingface_hub
+- Handling streaming responses
+- Error handling and rate limiting
+
+**Project: Add AI Capabilities to Your CLI**
+
+```bash
+# Add AI dependencies
+pixi add transformers huggingface-hub python-dotenv
+
+# For local inference (optional)
+pixi add torch
+
+# Create .env file for API keys
+echo "HUGGINGFACE_TOKEN=your-token-here" > .env
+echo ".env" >> .gitignore
+```
+
+**Simple AI Integration Example:**
+
+```python
+# src/file_organizer/ai_helper.py
+from huggingface_hub import InferenceClient
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+def suggest_organization_strategy(file_list: list[str]) -> str:
+    """Use AI to suggest file organization strategy."""
+    client = InferenceClient(token=os.getenv("HUGGINGFACE_TOKEN"))
+    
+    prompt = f"""Given these files: {', '.join(file_list)}
+    
+Suggest an intelligent organization strategy. Group related files and explain your reasoning.
+Respond in JSON format."""
+    
+    # Use a free model like Mistral or Llama
+    response = client.text_generation(
+        prompt,
+        model="mistralai/Mistral-7B-Instruct-v0.2",
+        max_new_tokens=500,
+        temperature=0.7
+    )
+    
+    return response
+
+# Alternative: Using local models with transformers
+from transformers import pipeline
+
+def analyze_file_content_local(content: str) -> str:
+    """Analyze file content using a local model."""
+    # Use Copilot to complete this function
+    # Prompt: "Create a function that uses a local HuggingFace model 
+    # to analyze and categorize file content"
+    
+    classifier = pipeline(
+        "text-classification",
+        model="distilbert-base-uncased-finetuned-sst-2-english"
+    )
+    
+    result = classifier(content[:512])  # Truncate for model limits
+    return result
+```
+
+**Copilot Exercises:**
+- "Create a function to summarize file contents using HuggingFace models"
+- "Add retry logic for API failures with exponential backoff"
+- "Implement streaming response handler for long-form generation"
+- "Create a model selector that chooses between local and API inference"
+
+**Resources:**
+- [HuggingFace Hub Documentation](https://huggingface.co/docs/huggingface_hub/)
+- [Transformers Documentation](https://huggingface.co/docs/transformers/)
+- [HuggingFace Inference API](https://huggingface.co/docs/api-inference/)
+- [Free Models on HuggingFace](https://huggingface.co/models)
+
+**Popular Models to Try:**
+- **Text Generation**: `mistralai/Mistral-7B-Instruct-v0.2`, `meta-llama/Llama-2-7b-chat-hf`
+- **Summarization**: `facebook/bart-large-cnn`, `google/pegasus-xsum`
+- **Classification**: `distilbert-base-uncased`, `roberta-base`
+- **Embeddings**: `sentence-transformers/all-MiniLM-L6-v2`
+
+**Local vs API Inference:**
+
+```python
+# src/file_organizer/inference.py
+from typing import Literal
+import os
+
+class AIHelper:
+    """Flexible AI helper supporting both local and API inference."""
+    
+    def __init__(self, mode: Literal["local", "api"] = "api"):
+        self.mode = mode
+        
+        if mode == "api":
+            from huggingface_hub import InferenceClient
+            self.client = InferenceClient(token=os.getenv("HUGGINGFACE_TOKEN"))
+        else:
+            from transformers import pipeline
+            # Load model once at initialization
+            self.pipeline = pipeline(
+                "text-generation",
+                model="distilgpt2",  # Smaller model for local use
+                device=-1  # CPU, use 0 for GPU
+            )
+    
+    def generate(self, prompt: str) -> str:
+        """Generate text using configured mode."""
+        if self.mode == "api":
+            return self.client.text_generation(
+                prompt,
+                model="mistralai/Mistral-7B-Instruct-v0.2",
+                max_new_tokens=500
+            )
+        else:
+            result = self.pipeline(prompt, max_new_tokens=100)
+            return result[0]['generated_text']
+
+# Usage in CLI
+# Use Copilot: "Add a --local flag to switch between API and local inference"
+```
+
+**When to Use Each:**
+- **API Inference**: Better quality, larger models, no local resources needed, requires internet
+- **Local Inference**: Privacy, offline use, no API costs, but requires more RAM/GPU
+- **vLLM Server**: Best of both worlds - local privacy with high performance and OpenAI-compatible API
+
+**Advanced: Serving Local Models with vLLM**
+
+vLLM is a high-performance inference engine that can serve local models with significantly better throughput and lower latency than standard transformers.
+
+```bash
+# Install vLLM (requires GPU for best performance)
+pixi add vllm
+
+# Or install with specific CUDA version
+pixi add "vllm[cuda12]"
+```
+
+**Starting a vLLM Server:**
+
+```bash
+# Start vLLM server with a model
+# This creates an OpenAI-compatible API endpoint
+vllm serve mistralai/Mistral-7B-Instruct-v0.2 \
+    --host 0.0.0.0 \
+    --port 8000 \
+    --max-model-len 4096
+
+# For smaller GPUs, use quantized models
+vllm serve TheBloke/Mistral-7B-Instruct-v0.2-GPTQ \
+    --quantization gptq \
+    --dtype half
+```
+
+**Using vLLM Server in Your CLI:**
+
+```python
+# src/file_organizer/vllm_client.py
+from openai import OpenAI
+from typing import Optional
+
+class vLLMClient:
+    """Client for vLLM server with OpenAI-compatible API."""
+    
+    def __init__(self, base_url: str = "http://localhost:8000/v1"):
+        # vLLM provides OpenAI-compatible endpoints
+        self.client = OpenAI(
+            base_url=base_url,
+            api_key="not-needed"  # vLLM doesn't require API key
+        )
+    
+    def generate(
+        self, 
+        prompt: str, 
+        model: str = "mistralai/Mistral-7B-Instruct-v0.2",
+        max_tokens: int = 500,
+        temperature: float = 0.7
+    ) -> str:
+        """Generate text using vLLM server."""
+        response = self.client.completions.create(
+            model=model,
+            prompt=prompt,
+            max_tokens=max_tokens,
+            temperature=temperature
+        )
+        return response.choices[0].text
+    
+    def chat_generate(
+        self,
+        messages: list[dict],
+        model: str = "mistralai/Mistral-7B-Instruct-v0.2",
+        max_tokens: int = 500
+    ) -> str:
+        """Generate using chat completion format."""
+        response = self.client.chat.completions.create(
+            model=model,
+            messages=messages,
+            max_tokens=max_tokens
+        )
+        return response.choices[0].message.content
+
+# Usage in your CLI
+def suggest_organization_with_vllm(file_list: list[str]) -> str:
+    """Use local vLLM server for suggestions."""
+    client = vLLMClient()
+    
+    messages = [
+        {"role": "system", "content": "You are a file organization assistant."},
+        {"role": "user", "content": f"Organize these files: {', '.join(file_list)}"}
+    ]
+    
+    return client.chat_generate(messages)
+```
+
+**Complete Inference Strategy:**
+
+```python
+# src/file_organizer/ai_strategy.py
+from typing import Literal
+import os
+from enum import Enum
+
+class InferenceMode(str, Enum):
+    """Available inference modes."""
+    API = "api"              # HuggingFace Inference API
+    LOCAL = "local"          # Direct transformers
+    VLLM = "vllm"           # vLLM server
+    AUTO = "auto"           # Auto-detect best option
+
+class UnifiedAIClient:
+    """Unified client supporting multiple inference backends."""
+    
+    def __init__(self, mode: InferenceMode = InferenceMode.AUTO):
+        self.mode = self._resolve_mode(mode)
+        self._setup_client()
+    
+    def _resolve_mode(self, mode: InferenceMode) -> InferenceMode:
+        """Auto-detect best available mode."""
+        if mode != InferenceMode.AUTO:
+            return mode
+        
+        # Check if vLLM server is running
+        try:
+            import requests
+            requests.get("http://localhost:8000/health", timeout=1)
+            return InferenceMode.VLLM
+        except:
+            pass
+        
+        # Check if HuggingFace token is available
+        if os.getenv("HUGGINGFACE_TOKEN"):
+            return InferenceMode.API
+        
+        # Fall back to local
+        return InferenceMode.LOCAL
+    
+    def _setup_client(self):
+        """Initialize the appropriate client."""
+        if self.mode == InferenceMode.VLLM:
+            from openai import OpenAI
+            self.client = OpenAI(
+                base_url="http://localhost:8000/v1",
+                api_key="not-needed"
+            )
+        elif self.mode == InferenceMode.API:
+            from huggingface_hub import InferenceClient
+            self.client = InferenceClient(token=os.getenv("HUGGINGFACE_TOKEN"))
+        else:  # LOCAL
+            from transformers import pipeline
+            self.client = pipeline("text-generation", model="distilgpt2")
+    
+    def generate(self, prompt: str, **kwargs) -> str:
+        """Generate text using configured backend."""
+        if self.mode == InferenceMode.VLLM:
+            response = self.client.completions.create(
+                model="mistralai/Mistral-7B-Instruct-v0.2",
+                prompt=prompt,
+                max_tokens=kwargs.get("max_tokens", 500)
+            )
+            return response.choices[0].text
+        
+        elif self.mode == InferenceMode.API:
+            return self.client.text_generation(
+                prompt,
+                model="mistralai/Mistral-7B-Instruct-v0.2",
+                max_new_tokens=kwargs.get("max_tokens", 500)
+            )
+        
+        else:  # LOCAL
+            result = self.client(prompt, max_new_tokens=kwargs.get("max_tokens", 100))
+            return result[0]['generated_text']
+
+# Use in CLI with Typer
+import typer
+
+@app.command()
+def organize(
+    directory: Path,
+    inference_mode: InferenceMode = typer.Option(
+        InferenceMode.AUTO,
+        "--mode",
+        help="Inference mode: api, local, vllm, or auto"
+    )
+):
+    """Organize files using AI."""
+    ai_client = UnifiedAIClient(mode=inference_mode)
+    # Use ai_client.generate() for suggestions
+```
+
+**vLLM Performance Tips:**
+
+1. **GPU Memory**: Use `--gpu-memory-utilization 0.9` to maximize GPU usage
+2. **Batch Size**: vLLM automatically batches requests for better throughput
+3. **Quantization**: Use GPTQ or AWQ quantized models for lower memory usage
+4. **Tensor Parallelism**: For multi-GPU: `--tensor-parallel-size 2`
+
+**Docker Compose for vLLM (Optional):**
+
+```yaml
+# docker-compose.vllm.yml
+version: '3.8'
+
+services:
+  vllm:
+    image: vllm/vllm-openai:latest
+    ports:
+      - "8000:8000"
+    environment:
+      - MODEL=mistralai/Mistral-7B-Instruct-v0.2
+      - MAX_MODEL_LEN=4096
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+    command: >
+      --host 0.0.0.0
+      --port 8000
+      --model ${MODEL}
+      --max-model-len ${MAX_MODEL_LEN}
+```
+
+**Comparison:**
+
+| Feature | HF API | Transformers | vLLM |
+|---------|--------|--------------|------|
+| Setup | Easy | Easy | Medium |
+| Speed | Fast | Slow | Very Fast |
+| Cost | Pay per use | Free | Free (local) |
+| GPU Required | No | Optional | Recommended |
+| Offline | No | Yes | Yes |
+| Batch Processing | Limited | Poor | Excellent |
+| Memory Efficient | N/A | No | Yes |
+| OpenAI Compatible | No | No | Yes |
+
+**Recommended Workflow:**
+1. **Development**: Use HuggingFace API for quick prototyping
+2. **Testing**: Use vLLM locally for faster iteration
+3. **Production**: Deploy vLLM server for best performance and privacy
+
+#### 3.2 Docker-Based Model Deployment
+
+Docker provides a modern, standardized way to deploy local LLM models with minimal configuration using Docker Compose v2.38+.
+
+**Why Use Docker for AI Models?**
+- **Consistent environments**: Same setup across development, testing, and production
+- **Easy deployment**: One command to start models and services
+- **Resource isolation**: Models run in containers with defined resource limits
+- **Portability**: Works locally with Docker Model Runner or on cloud providers
+- **Version control**: Pin specific model versions with OCI artifacts
+
+**Prerequisites:**
+
+```bash
+# Ensure Docker Compose v2.38 or later
+docker compose version
+
+# Enable Docker Model Runner in Docker Desktop settings
+# Or install separately: https://docs.docker.com/ai/model-runner/
+```
+
+**Basic Model Deployment with Docker Compose:**
+
+Create a `docker-compose.yml` for your CLI project:
+
+```yaml
+# docker-compose.yml
+services:
+  # Your CLI application
+  file-organizer:
+    build: .
+    models:
+      - llm  # Reference to the model defined below
+    environment:
+      # Auto-injected by Docker:
+      # LLM_URL - endpoint to access the model
+      # LLM_MODEL - model identifier
+    volumes:
+      - ./data:/app/data
+
+models:
+  llm:
+    model: ai/smollm2  # Model from Docker Hub
+    context_size: 4096
+    runtime_flags:
+      - "--verbose"
+      - "--log-colors"
+```
+
+**Using Models in Your Python CLI:**
+
+```python
+# src/file_organizer/docker_ai.py
+import os
+from openai import OpenAI
+
+class DockerModelClient:
+    """Client for Docker-deployed models with OpenAI-compatible API."""
+    
+    def __init__(self):
+        # Docker automatically injects these environment variables
+        model_url = os.getenv("LLM_URL")
+        model_name = os.getenv("LLM_MODEL")
+        
+        if not model_url:
+            raise ValueError("LLM_URL not set. Are you running with Docker Compose?")
+        
+        # Docker models provide OpenAI-compatible endpoints
+        self.client = OpenAI(
+            base_url=model_url,
+            api_key="not-needed"  # Docker models don't require API keys
+        )
+        self.model_name = model_name
+    
+    def generate(self, prompt: str, max_tokens: int = 500) -> str:
+        """Generate text using Docker-deployed model."""
+        response = self.client.completions.create(
+            model=self.model_name,
+            prompt=prompt,
+            max_tokens=max_tokens,
+            temperature=0.7
+        )
+        return response.choices[0].text
+    
+    def chat_generate(self, messages: list[dict], max_tokens: int = 500) -> str:
+        """Generate using chat completion format."""
+        response = self.client.chat.completions.create(
+            model=self.model_name,
+            messages=messages,
+            max_tokens=max_tokens
+        )
+        return response.choices[0].message.content
+
+# Usage in your CLI
+import typer
+
+@app.command()
+def organize(directory: Path):
+    """Organize files using Docker-deployed AI model."""
+    try:
+        ai_client = DockerModelClient()
+        # Use the model for suggestions
+        suggestion = ai_client.generate(f"Organize these files: {list(directory.iterdir())}")
+        console.print(suggestion)
+    except ValueError as e:
+        console.print(f"[red]Error: {e}[/red]")
+        console.print("[yellow]Run with: docker compose up[/yellow]")
+```
+
+**Multi-Model Setup:**
+
+Deploy multiple models for different tasks:
+
+```yaml
+services:
+  file-organizer:
+    build: .
+    models:
+      chat-model:
+        endpoint_var: CHAT_MODEL_URL
+        model_var: CHAT_MODEL_NAME
+      embeddings:
+        endpoint_var: EMBEDDING_URL
+        model_var: EMBEDDING_NAME
+
+models:
+  chat-model:
+    model: ai/smollm2
+    context_size: 4096
+    runtime_flags:
+      - "--temp"
+      - "0.7"
+  
+  embeddings:
+    model: ai/all-minilm
+    context_size: 512
+```
+
+**Model Configuration Presets:**
+
+```yaml
+# Development mode - verbose logging
+models:
+  dev_model:
+    model: ai/smollm2
+    context_size: 4096
+    runtime_flags:
+      - "--verbose"
+      - "--verbose-prompt"
+      - "--log-timestamps"
+      - "--log-colors"
+
+# Production mode - deterministic output
+models:
+  prod_model:
+    model: ai/smollm2
+    context_size: 4096
+    runtime_flags:
+      - "--temp"
+      - "0.1"  # Low temperature for consistency
+      - "--top-k"
+      - "1"
+
+# Creative mode - high randomness
+models:
+  creative_model:
+    model: ai/smollm2
+    context_size: 4096
+    runtime_flags:
+      - "--temp"
+      - "1.0"
+      - "--top-p"
+      - "0.9"
+```
+
+**Running Your Dockerized CLI:**
+
+```bash
+# Start models and services
+docker compose up -d
+
+# Check model status
+docker compose ps
+
+# View model logs
+docker compose logs llm
+
+# Run your CLI (models are available via environment variables)
+docker compose exec file-organizer python -m file_organizer organize ./data
+
+# Stop everything
+docker compose down
+```
+
+**Complete Example Dockerfile:**
+
+```dockerfile
+# Dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY pyproject.toml .
+RUN pip install -e .
+
+# Copy application code
+COPY src/ ./src/
+
+# The CLI will use environment variables injected by Docker Compose
+CMD ["python", "-m", "file_organizer.cli"]
+```
+
+**Benefits of Docker Deployment:**
+
+| Feature | Docker Compose | Manual Setup |
+|---------|----------------|-------------|
+| Setup Time | Minutes | Hours |
+| Consistency | ✅ Same everywhere | ❌ Varies by system |
+| Resource Control | ✅ Built-in limits | ⚠️ Manual config |
+| Multi-model | ✅ Easy | ❌ Complex |
+| Cloud Portability | ✅ Same config | ❌ Rewrite needed |
+| Version Control | ✅ Git-friendly | ⚠️ Documentation |
+
+**Cloud Deployment:**
+
+The same `docker-compose.yml` works on cloud providers with extensions:
+
+```yaml
+models:
+  llm:
+    model: ai/smollm2
+    context_size: 4096
+    # Cloud-specific options (provider-dependent)
+    x-cloud-options:
+      - "cloud.instance-type=gpu-small"
+      - "cloud.region=us-west-2"
+      - "cloud.auto-scaling=true"
+```
+
+**Resources:**
+- [Docker AI Documentation](https://docs.docker.com/ai/)
+- [Docker Compose Models Reference](https://docs.docker.com/ai/compose/models-and-compose/)
+- [Docker Model Runner](https://docs.docker.com/ai/model-runner/)
+- [Available Models on Docker Hub](https://hub.docker.com/search?q=ai%2F)
+
+#### 3.3 Docker MCP Toolkit: Secure Tool Integration
+
+The Model Context Protocol (MCP) provides a standardized way for AI agents to interact with external tools and data sources. Docker's MCP Toolkit makes this secure and easy.
+
+**What is MCP?**
+
+MCP is an open protocol that allows AI models to:
+- Execute code in isolated environments
+- Access databases and APIs securely
+- Use external tools (web search, calculators, etc.)
+- Retrieve real-world data
+
+**Why Docker MCP?**
+
+1. **Security**: Tools run in isolated containers
+2. **Trust**: Curated catalog with publisher verification
+3. **Simplicity**: One-click deployment from Docker Desktop
+4. **Dynamic Discovery**: Agents find and add tools as needed
+
+**Docker MCP Components:**
+
+```yaml
+# docker-compose.yml with MCP Gateway
+services:
+  # Your AI-powered CLI
+  file-organizer:
+    build: .
+    models:
+      - llm
+    environment:
+      - MCP_GATEWAY_URL=http://mcp-gateway:3000
+    depends_on:
+      - mcp-gateway
+  
+  # MCP Gateway - manages MCP servers
+  mcp-gateway:
+    image: docker/mcp-gateway:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - mcp-data:/data
+    environment:
+      - MCP_CATALOG_URL=https://hub.docker.com/mcp
+
+models:
+  llm:
+    model: ai/smollm2
+    context_size: 4096
+
+volumes:
+  mcp-data:
+```
+
+**Using MCP in Your CLI:**
+
+```python
+# src/file_organizer/mcp_client.py
+import os
+import requests
+from typing import Any
+
+class MCPClient:
+    """Client for Docker MCP Gateway."""
+    
+    def __init__(self):
+        self.gateway_url = os.getenv("MCP_GATEWAY_URL", "http://localhost:3000")
+    
+    def find_servers(self, query: str) -> list[dict]:
+        """Find MCP servers by name or description."""
+        response = requests.post(
+            f"{self.gateway_url}/mcp-find",
+            json={"query": query}
+        )
+        return response.json()["servers"]
+    
+    def add_server(self, server_name: str) -> dict:
+        """Add an MCP server to the current session."""
+        response = requests.post(
+            f"{self.gateway_url}/mcp-add",
+            json={"server": server_name}
+        )
+        return response.json()
+    
+    def call_tool(self, server: str, tool: str, params: dict) -> Any:
+        """Call a tool from an MCP server."""
+        response = requests.post(
+            f"{self.gateway_url}/mcp-call",
+            json={
+                "server": server,
+                "tool": tool,
+                "parameters": params
+            }
+        )
+        return response.json()["result"]
+
+# Example: Web search integration
+@app.command()
+def research(topic: str):
+    """Research a topic using web search MCP."""
+    mcp = MCPClient()
+    
+    # Find web search servers
+    servers = mcp.find_servers("web search")
+    console.print(f"Found {len(servers)} search servers")
+    
+    # Add DuckDuckGo MCP
+    mcp.add_server("duckduckgo-mcp")
+    
+    # Use the search tool
+    results = mcp.call_tool(
+        server="duckduckgo-mcp",
+        tool="search",
+        params={"query": topic, "max_results": 5}
+    )
+    
+    # Display results
+    for result in results:
+        console.print(f"[bold]{result['title']}[/bold]")
+        console.print(f"  {result['url']}")
+        console.print(f"  {result['snippet']}\n")
+```
+
+**Dynamic MCP Discovery:**
+
+Let AI agents discover and use tools automatically:
+
+```python
+# src/file_organizer/ai_agent.py
+from openai import OpenAI
+import json
+
+class AIAgentWithMCP:
+    """AI agent that can discover and use MCP tools."""
+    
+    def __init__(self):
+        self.llm = OpenAI(base_url=os.getenv("LLM_URL"), api_key="not-needed")
+        self.mcp = MCPClient()
+        self.available_tools = []
+    
+    def discover_tools(self, task_description: str):
+        """Ask LLM what tools are needed for a task."""
+        prompt = f"""Task: {task_description}
+        
+        What MCP tools would be helpful? Respond with JSON:
+        {{"tools": ["tool-name-1", "tool-name-2"]}}
+        """
+        
+        response = self.llm.completions.create(
+            model=os.getenv("LLM_MODEL"),
+            prompt=prompt,
+            max_tokens=200
+        )
+        
+        tools_needed = json.loads(response.choices[0].text)
+        
+        # Add each tool
+        for tool in tools_needed["tools"]:
+            servers = self.mcp.find_servers(tool)
+            if servers:
+                self.mcp.add_server(servers[0]["name"])
+                self.available_tools.append(servers[0])
+    
+    def execute_task(self, task: str):
+        """Execute a task using available tools."""
+        # First, discover what tools we need
+        self.discover_tools(task)
+        
+        # Then execute with those tools
+        # (Implementation depends on your specific use case)
+        pass
+
+# Usage
+@app.command()
+def smart_organize(directory: Path, strategy: str):
+    """Organize files using AI with dynamic tool discovery."""
+    agent = AIAgentWithMCP()
+    
+    task = f"Organize files in {directory} using strategy: {strategy}"
+    agent.execute_task(task)
+```
+
+**Available MCP Servers:**
+
+The [Docker MCP Catalog](https://hub.docker.com/mcp) includes 270+ servers:
+
+- **Web Search**: DuckDuckGo, Brave Search
+- **Databases**: PostgreSQL, MongoDB, Elasticsearch
+- **APIs**: Stripe, GitHub, Slack
+- **Monitoring**: Grafana, Prometheus
+- **File Systems**: Local files, S3, Google Drive
+- **Development**: Git, Docker, Kubernetes
+
+**Security Features:**
+
+1. **Container Isolation**: Each MCP server runs in its own container
+2. **Commit Pinning**: Servers tied to specific Git commits
+3. **Publisher Trust Levels**: Official, verified, and community servers
+4. **AI-Audited Updates**: Automated code review for changes
+5. **Resource Limits**: CPU and memory constraints per server
+
+**Complete Example with MCP:**
+
+```yaml
+# docker-compose.yml - Full AI CLI with MCP
+services:
+  file-organizer:
+    build: .
+    models:
+      - llm
+    environment:
+      - MCP_GATEWAY_URL=http://mcp-gateway:3000
+      - ENABLE_DYNAMIC_MCPS=true
+    depends_on:
+      - mcp-gateway
+    volumes:
+      - ./data:/app/data
+  
+  mcp-gateway:
+    image: docker/mcp-gateway:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - mcp-data:/data
+      - ./mcp-config.yml:/config/catalog.yml
+
+models:
+  llm:
+    model: ai/smollm2
+    context_size: 4096
+    runtime_flags:
+      - "--temp"
+      - "0.7"
+
+volumes:
+  mcp-data:
+```
+
+**MCP Best Practices:**
+
+1. **Start with trusted servers**: Use official and verified publishers
+2. **Enable only needed tools**: Reduce attack surface
+3. **Monitor MCP usage**: Track which tools are called
+4. **Set resource limits**: Prevent runaway processes
+5. **Review permissions**: Understand what each MCP can access
+
+**Resources:**
+- [Docker MCP Gateway (GitHub)](https://github.com/docker/mcp-gateway/)
+- [Docker MCP Catalog](https://hub.docker.com/mcp)
+- [MCP Registry](https://github.com/docker/mcp-registry)
+- [Dynamic MCPs Blog](https://www.docker.com/blog/dynamic-mcps-stop-hardcoding-your-agents-world/)
+- [MCP Security Blog](https://www.docker.com/blog/enhancing-mcp-trust-with-the-docker-mcp-catalog/)
+
+#### 3.4 Prompt Engineering for CLI Tools
+
+**Learn About:**
+- Crafting effective prompts for different model types
+- Understanding model-specific prompt formats (Mistral, Llama, etc.)
+- System vs user messages (for chat models)
+- Few-shot learning examples
+- Prompt templates and variables
+
+**Hands-On:**
+Create a prompt template system:
+
+```python
+# src/file_organizer/prompts.py
+
+# For instruction-tuned models like Mistral
+MISTRAL_ORGANIZATION_PROMPT = """[INST] You are a helpful file organization assistant.
+
+Given the following list of files:
+{file_list}
+
+Suggest an intelligent organization strategy that:
+1. Groups related files together
+2. Creates meaningful folder names
+3. Explains the reasoning
+
+Respond in JSON format with this structure:
+{{
+  "strategy": "description",
+  "folders": [
+    {{"name": "folder_name", "files": ["file1", "file2"], "reason": "why"}}
+  ]
+}} [/INST]"""
+
+# For Llama-2 chat models
+LLAMA_SYSTEM_PROMPT = """You are a helpful file organization assistant. 
+Always respond in valid JSON format."""
+
+def format_llama_prompt(user_message: str) -> str:
+    """Format prompt for Llama-2 chat models."""
+    return f"""<s>[INST] <<SYS>>
+{LLAMA_SYSTEM_PROMPT}
+<</SYS>>
+
+{user_message} [/INST]"""
+
+# For general models without special formatting
+GENERIC_PROMPT_TEMPLATE = """Task: Organize the following files intelligently.
+
+Files: {file_list}
+
+Instructions:
+- Group related files together
+- Suggest meaningful folder names
+- Explain your reasoning
+- Output as JSON
+
+Response:"""
+
+# Use Copilot to generate more prompt templates for different tasks
+```
+
+**Model-Specific Considerations:**
+
+```python
+# src/file_organizer/model_config.py
+
+MODEL_CONFIGS = {
+    "mistralai/Mistral-7B-Instruct-v0.2": {
+        "max_tokens": 8192,
+        "prompt_format": "mistral",
+        "temperature": 0.7,
+        "use_case": "general instruction following"
+    },
+    "meta-llama/Llama-2-7b-chat-hf": {
+        "max_tokens": 4096,
+        "prompt_format": "llama2",
+        "temperature": 0.7,
+        "use_case": "conversational tasks"
+    },
+    "facebook/bart-large-cnn": {
+        "max_tokens": 1024,
+        "prompt_format": "none",
+        "use_case": "summarization only"
+    }
+}
+
+def get_model_config(model_name: str) -> dict:
+    """Get configuration for a specific model."""
+    return MODEL_CONFIGS.get(model_name, {})
+```
+
+**Copilot Prompts:**
+- "Create a function to format prompts based on model type"
+- "Generate few-shot examples for file categorization"
+- "Build a prompt validator that checks token limits"
+- "Create a prompt optimization function that reduces token usage"
+
+---
+
+### Phase 4: Advanced CLI Features (Week 6-7)
+
+#### 4.1 Interactive CLI Elements
+
+**Add Dependencies:**
+
+```bash
+pixi add questionary rich typer
+```
+
+**Learn to Build:**
+- Interactive prompts and menus
+- Progress bars and spinners
+- Tables and formatted output
+- Color-coded messages
+
+**Example with Copilot:**
+
+```python
+# Ask Copilot: "Create an interactive menu using questionary 
+# to select file organization options"
+
+import questionary
+from rich.progress import track
+
+def interactive_organize():
+    # Copilot will help generate this
+    pass
+```
+
+#### 4.2 Batch Processing and Async Operations
+
+**Learn About:**
+- Processing multiple files efficiently
+- Async/await for concurrent API calls
+- Rate limiting and throttling
+- Progress tracking for long operations
+
+```bash
+# Add async dependencies
+pixi add aiohttp asyncio
+```
+
+**Copilot Exercise:**
+- "Create an async function to process multiple files with OpenAI API"
+- "Add rate limiting to prevent API quota exhaustion"
+- "Implement a queue system for batch processing"
+
+---
+
+### Phase 5: Testing and Quality (Week 8)
+
+#### 5.1 Writing Tests
+
+**Add Testing Dependencies:**
+
+```bash
+pixi add pytest pytest-cov pytest-asyncio pytest-mock
+```
+
+**Learn to Test:**
+- Unit tests for individual functions
+- Integration tests for CLI commands
+- Mocking API calls
+- Test coverage reporting
+
+**Example Test Structure:**
+
+```python
+# tests/test_cli.py
+import pytest
+from typer.testing import CliRunner
+from file_organizer.cli import app
+
+runner = CliRunner()
+
+def test_organize_command():
+    # Use Copilot to generate test cases
+    result = runner.invoke(app, ['organize', 'test_dir', '--dry-run'])
+    assert result.exit_code == 0
+    assert "DRY RUN" in result.stdout
+
+def test_organize_with_verbose():
+    result = runner.invoke(app, ['organize', 'test_dir', '--verbose'])
+    assert result.exit_code == 0
+    
+def test_stats_command():
+    result = runner.invoke(app, ['stats', 'test_dir'])
+    assert result.exit_code == 0
+```
+
+**Copilot Prompts:**
+- "Generate pytest fixtures for mocking HuggingFace Inference API"
+- "Create test cases for error handling with API timeouts"
+- "Write integration tests for the organize command"
+- "Mock transformers pipeline for local model testing"
+
+**Example Mocking HuggingFace:**
+
+```python
+# tests/conftest.py
+import pytest
+from unittest.mock import Mock, patch
+
+@pytest.fixture
+def mock_hf_client():
+    """Mock HuggingFace InferenceClient."""
+    with patch('huggingface_hub.InferenceClient') as mock:
+        mock_instance = Mock()
+        mock_instance.text_generation.return_value = '{"strategy": "test"}'
+        mock.return_value = mock_instance
+        yield mock_instance
+
+@pytest.fixture
+def mock_transformers_pipeline():
+    """Mock transformers pipeline for local models."""
+    with patch('transformers.pipeline') as mock:
+        mock_pipeline = Mock()
+        mock_pipeline.return_value = [{"label": "POSITIVE", "score": 0.99}]
+        mock.return_value = mock_pipeline
+        yield mock_pipeline
+```
+
+#### 5.2 Code Quality Tools
+
+```bash
+# Add quality tools
+pixi add ruff mypy black isort
+```
+
+**Set Up:**
+- Linting with ruff
+- Type checking with mypy
+- Code formatting with black
+- Import sorting with isort
+
+**Create `pyproject.toml` configuration (use Copilot):**
+
+```toml
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[tool.black]
+line-length = 100
+```
+
+---
+
+### Phase 6: Package Publishing with Pixi (Week 9)
+
+#### 6.1 Preparing for Publication
+
+**Project Structure:**
+
+```
+my-cli-tool/
+├── pixi.toml              # Pixi configuration
+├── pyproject.toml         # Python package metadata
+├── README.md              # Documentation
+├── LICENSE                # License file
+├── src/
+│   └── my_cli_tool/
+│       ├── __init__.py
+│       ├── cli.py
+│       └── ...
+├── tests/
+│   └── test_*.py
+└── docs/
+    └── ...
+```
+
+**Configure `pyproject.toml` for Publishing:**
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "my-cli-tool"
+version = "0.1.0"
+description = "AI-powered file organization CLI"
+authors = [{name = "Your Name", email = "you@example.com"}]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.9",
+    "rich>=13.0",
+    "transformers>=4.30",
+    "huggingface-hub>=0.16",
+]
+
+[project.scripts]
+my-cli = "my_cli_tool.cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/yourusername/my-cli-tool"
+Documentation = "https://my-cli-tool.readthedocs.io"
+```
+
+**Use Copilot to:**
+- Generate comprehensive README with usage examples
+- Create CHANGELOG.md
+- Write contributing guidelines
+- Generate documentation
+
+#### 6.2 Building and Publishing
+
+**Build Package:**
+
+```bash
+# Add build tools
+pixi add hatchling build twine
+
+# Build the package
+pixi run python -m build
+
+# This creates:
+# - dist/my_cli_tool-0.1.0.tar.gz
+# - dist/my_cli_tool-0.1.0-py3-none-any.whl
+```
+
+**Publish to PyPI:**
+
+```bash
+# Test on TestPyPI first
+pixi run twine upload --repository testpypi dist/*
+
+# Then publish to PyPI
+pixi run twine upload dist/*
+```
+
+**Publish as Pixi Package:**
+
+```bash
+# Create pixi.toml with package metadata
+pixi project init --name my-cli-tool
+
+# Add to pixi.toml:
+[project]
+name = "my-cli-tool"
+version = "0.1.0"
+description = "AI-powered file organization CLI"
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-64", "win-64"]
+
+[dependencies]
+python = ">=3.11"
+typer = ">=0.9"
+rich = ">=13.0"
+
+[tasks]
+start = "my-cli"
+```
+
+**Resources:**
+- [Python Packaging Guide](https://packaging.python.org/)
+- [Pixi Publishing Guide](https://pixi.sh/latest/advanced/publishing/)
+- [Semantic Versioning](https://semver.org/)
+
+---
+
+### Phase 7: Real-World Project (Week 10-12)
+
+#### 7.1 Choose a Project from the Ideas List
+
+**Comprehensive Example Project:**
+
+**[FileOrganizer](projects/FileOrganizer.md)** - AI-Powered File Organization CLI
+   - **What it demonstrates**: Complete integration of all concepts from this learning path
+   - **Key technologies**: Docker Model Runner, MCP servers, CrewAI multi-agent system, Typer CLI
+   - **Complexity**: Advanced
+   - **Best for**: Learners who have completed Phases 1-6 and want to see a production-ready example
+   - **Features**:
+     - Multi-agent system (Scanner, Classifier, Organizer, Deduplicator)
+     - Docker-based LLM deployment
+     - MCP server for file operations
+     - Research paper management with metadata extraction
+     - Comprehensive CLI with multiple commands
+   - **Learning outcomes**: See how Docker AI, MCP, multi-agent systems, and CLI development work together in a real project
+
+**Recommended Starter Projects:**
+
+1. **smart-csv** (Data & Analytics)
+   - Good for: Learning data manipulation
+   - Key skills: Pandas, CSV processing, LLM integration
+   - Complexity: Medium
+
+2. **smart-summarize** (Document Processing)
+   - Good for: Text processing and AI integration
+   - Key skills: File I/O, API integration, prompt engineering
+   - Complexity: Low-Medium
+
+3. **error-translator** (DevOps)
+   - Good for: String processing and knowledge retrieval
+   - Key skills: Pattern matching, API usage, caching
+   - Complexity: Medium
+
+4. **task-prioritizer** (Productivity)
+   - Good for: Building practical tools
+   - Key skills: Data structures, AI reasoning, persistence
+   - Complexity: Medium
+
+> **💡 Tip**: Start with one of the simpler projects (2-4) to build confidence, then tackle FileOrganizer to see how all the concepts integrate in a production-ready application.
+
+#### 7.2 Development Workflow with GitHub Copilot
+
+**Step-by-Step Process:**
+
+1. **Planning Phase:**
+   - Use Copilot Chat to brainstorm features
+   - Generate project structure
+   - Create initial documentation
+
+2. **Implementation Phase:**
+   - Use Copilot for boilerplate code
+   - Ask Copilot to explain unfamiliar concepts
+   - Generate test cases alongside code
+
+3. **Refinement Phase:**
+   - Use Copilot to suggest optimizations
+   - Generate documentation and examples
+   - Create user guides
+
+**Effective Copilot Prompts:**
+
+```python
+# In comments, be specific:
+# "Create a function that reads a CSV file, analyzes column types,
+# and returns a dictionary with column names as keys and suggested
+# data types as values. Handle errors gracefully."
+
+# Use descriptive function names:
+def analyze_csv_column_types(filepath: str) -> dict[str, str]:
+    # Copilot will suggest implementation
+    pass
+
+# Ask for explanations:
+# "Explain how to use asyncio to make concurrent API calls with rate limiting"
+```
+
+#### 7.3 Project Milestones
+
+**Week 10: MVP (Minimum Viable Product)**
+- [ ] Core functionality working
+- [ ] Basic CLI interface
+- [ ] Simple AI integration
+- [ ] README with usage examples
+
+**Week 11: Enhancement**
+- [ ] Add configuration system
+- [ ] Implement error handling
+- [ ] Add progress indicators
+- [ ] Write tests (>70% coverage)
+
+**Week 12: Polish & Publish**
+- [ ] Complete documentation
+- [ ] Add examples and tutorials
+- [ ] Set up CI/CD (GitHub Actions)
+- [ ] Publish to PyPI
+- [ ] Share on GitHub/social media
+
+---
+
+## 🛠️ Essential Pixi Commands Reference
+
+```bash
+# Project initialization
+pixi init my-project
+pixi init --channel conda-forge --channel bioconda
+
+# Dependency management
+pixi add package-name              # Add runtime dependency
+pixi add --dev pytest              # Add dev dependency
+pixi add "package>=1.0,<2.0"       # Version constraints
+pixi remove package-name           # Remove dependency
+pixi update                        # Update all dependencies
+
+# Environment management
+pixi shell                         # Activate environment
+pixi run python script.py          # Run command in environment
+pixi run --environment prod start  # Run in specific environment
+
+# Task management
+pixi task add start "python -m my_cli"
+pixi task add test "pytest tests/"
+pixi task add lint "ruff check src/"
+pixi run start                     # Run defined task
+
+# Multi-environment setup
+[feature.dev.dependencies]
+pytest = "*"
+ruff = "*"
+
+[environments]
+default = ["dev"]
+prod = []
+```
+
+---
+
+## 🎓 Learning Resources
+
+### Documentation
+- [Pixi Official Docs](https://pixi.sh/latest/)
+- [Python Packaging Guide](https://packaging.python.org/)
+- [Click Documentation](https://click.palletsprojects.com/)
+- [OpenAI API Reference](https://platform.openai.com/docs/)
+- [Docker AI Documentation](https://docs.docker.com/ai/)
+- [Docker Compose Models Reference](https://docs.docker.com/ai/compose/models-and-compose/)
+- [Docker MCP Gateway](https://github.com/docker/mcp-gateway/)
+- [Docker MCP Catalog](https://hub.docker.com/mcp)
+
+### Tutorials & Courses
+- [Real Python: Building CLI Applications](https://realpython.com/command-line-interfaces-python-argparse/)
+- [GitHub Copilot Learning Path](https://github.com/skills/copilot)
+- [LangChain Tutorials](https://python.langchain.com/docs/tutorials/)
+
+### Example Projects
+- [Typer Examples](https://github.com/tiangolo/typer/tree/master/docs_src)
+- [Rich Examples](https://github.com/Textualize/rich/tree/master/examples)
+- [AI CLI Tools on GitHub](https://github.com/topics/ai-cli)
+
+### Community
+- [Python Discord](https://discord.gg/python)
+- [r/Python](https://reddit.com/r/Python)
+- [Pixi GitHub Discussions](https://github.com/prefix-dev/pixi/discussions)
+
+---
+
+## 💡 Tips for Success
+
+### Using GitHub Copilot Effectively
+
+1. **Write Clear Comments:**
+   ```python
+   # Create a function that takes a list of file paths,
+   # sends them to GPT-4 for analysis, and returns
+   # a structured JSON response with organization suggestions
+   ```
+
+2. **Use Descriptive Names:**
+   - Good: `analyze_and_categorize_files()`
+   - Bad: `process()`
+
+3. **Break Down Complex Tasks:**
+   - Don't ask Copilot to generate entire applications
+   - Build incrementally, function by function
+
+4. **Review and Understand:**
+   - Always review Copilot's suggestions
+   - Understand the code before accepting it
+   - Test thoroughly
+
+5. **Use Copilot Chat for:**
+   - Explaining error messages
+   - Suggesting alternative approaches
+   - Generating test cases
+   - Writing documentation
+
+### Pixi Best Practices
+
+1. **Use Feature Flags:**
+   ```toml
+   [feature.ai]
+   dependencies = {openai = "*", anthropic = "*"}
+   
+   [feature.dev]
+   dependencies = {pytest = "*", ruff = "*"}
+   
+   [environments]
+   default = ["ai"]
+   dev = ["ai", "dev"]
+   ```
+
+2. **Define Tasks:**
+   ```toml
+   [tasks]
+   dev = "python -m my_cli --debug"
+   test = "pytest tests/ -v"
+   lint = "ruff check src/"
+   format = "black src/ tests/"
+   ```
+
+3. **Lock Dependencies:**
+   - Commit `pixi.lock` to version control
+   - Ensures reproducible builds
+
+4. **Use Channels Wisely:**
+   - Start with `conda-forge`
+   - Add specialized channels as needed
+
+### Development Workflow
+
+1. **Start Small:**
+   - Build the simplest version first
+   - Add features incrementally
+   - Test each addition
+
+2. **Iterate Based on Feedback:**
+   - Share early with friends/colleagues
+   - Gather feedback
+   - Improve based on real usage
+
+3. **Document as You Go:**
+   - Write docstrings immediately
+   - Update README with new features
+   - Keep CHANGELOG current
+
+4. **Test Continuously:**
+   - Write tests alongside code
+   - Run tests before committing
+   - Aim for >80% coverage
+
+---
+
+## 🎯 Success Metrics
+
+By the end of this learning path, you should be able to:
+
+- ✅ Set up a Python project with pixi
+- ✅ Build a CLI application with commands and options
+- ✅ Integrate AI/LLM capabilities effectively
+- ✅ Write tests and maintain code quality
+- ✅ Publish a package to PyPI
+- ✅ Use GitHub Copilot to accelerate development
+- ✅ Build one complete AI-powered CLI tool
+
+---
+
+## 📅 Next Steps
+
+After completing this learning path:
+
+1. **Build More Projects:**
+   - Try different project ideas from the list
+   - Experiment with different AI models
+   - Contribute to open-source CLI tools
+
+2. **Advanced Topics:**
+   - Plugin architectures
+   - Multi-command CLIs
+   - Database integration
+   - Web dashboards for CLI tools
+   - CI/CD automation
+
+3. **Share Your Work:**
+   - Write blog posts about your projects
+   - Create video tutorials
+   - Contribute to the community
+   - Help others learn
+
+---
+
+*Last Updated: 2024-12-04*

docs/projects/DataCrew.md

@@ -0,0 +1,571 @@
+# Course Project: DataCrew
+
+**A CLI tool that uses local LLMs and multi-agent systems to transform spreadsheets into intelligent PDF reports.**
+
+---
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        DataCrew CLI                              │
+├─────────────────────────────────────────────────────────────────┤
+│  $ datacrew ingest sales_2024.xlsx                              │
+│  $ datacrew ask "What were the top 5 products by revenue?"      │
+│  $ datacrew report "Q4 Executive Summary" --output report.pdf   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Architecture
+
+```
+CSV/XLSX ──► SQLite ──► MCP Server ──► Multi-Agent Crew ──► PDF Report
+                              │
+                              ▼
+                    Docker Model Runner
+                      (Local LLM)
+```
+
+### Data Flow
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│   CSV/XLSX   │────►│    SQLite    │────►│  MCP Server  │
+│    Files     │     │   Database   │     │   (Tools)    │
+└──────────────┘     └──────────────┘     └──────┬───────┘
+                                                  │
+                                                  ▼
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│  PDF Report  │◄────│  Agent Crew  │◄────│  Local LLM   │
+│   Output     │     │  (CrewAI)    │     │   (Docker)   │
+└──────────────┘     └──────────────┘     └──────────────┘
+```
+
+---
+
+## Agent System
+
+| Agent | Role | Tools | Output |
+|-------|------|-------|--------|
+| **Data Analyst** | Understands schema, writes SQL queries | MCP Database Tools | Query results, data summaries |
+| **Insights Agent** | Interprets results, finds patterns | Python Analysis, Statistics | Key findings, trends, anomalies |
+| **Report Writer** | Creates narrative sections | LLM Generation | Executive summary, section text |
+| **PDF Composer** | Formats and assembles final report | ReportLab/WeasyPrint | Formatted PDF document |
+
+### Agent Workflow
+
+```
+User Request: "Generate Q4 Executive Summary"
+                    │
+                    ▼
+         ┌─────────────────────┐
+         │    Data Analyst     │
+         │  "What data do we   │
+         │   need for Q4?"     │
+         └──────────┬──────────┘
+                    │ SQL Queries
+                    ▼
+         ┌─────────────────────┐
+         │   Insights Agent    │
+         │  "What patterns     │
+         │   emerge from       │
+         │   this data?"       │
+         └──────────┬──────────┘
+                    │ Key Findings
+                    ▼
+         ┌─────────────────────┐
+         │   Report Writer     │
+         │  "Write narrative   │
+         │   sections for      │
+         │   each finding"     │
+         └──────────┬──────────┘
+                    │ Text Sections
+                    ▼
+         ┌─────────────────────┐
+         │   PDF Composer      │
+         │  "Assemble into     │
+         │   formatted PDF"    │
+         └──────────┬──────────┘
+                    │
+                    ▼
+              report.pdf
+```
+
+---
+
+## CLI Commands
+
+### `datacrew ingest`
+
+Ingest CSV or XLSX files into the local SQLite database.
+
+```bash
+# Ingest a single file
+datacrew ingest sales_2024.xlsx
+
+# Ingest with custom table name
+datacrew ingest sales_2024.xlsx --table quarterly_sales
+
+# Ingest multiple files
+datacrew ingest data/*.csv
+
+# Ingest with schema inference options
+datacrew ingest sales.csv --infer-types --date-columns "order_date,ship_date"
+```
+
+**Options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--table` | Custom table name | Filename (sanitized) |
+| `--if-exists` | Behavior if table exists: `fail`, `replace`, `append` | `fail` |
+| `--infer-types` | Automatically infer column types | `true` |
+| `--date-columns` | Comma-separated list of date columns | Auto-detect |
+| `--db` | Database file path | `./data/datacrew.db` |
+
+### `datacrew ask`
+
+Query the database using natural language.
+
+```bash
+# Simple query
+datacrew ask "What were the top 5 products by revenue?"
+
+# Query with output format
+datacrew ask "Show monthly sales trends" --format table
+
+# Query with export
+datacrew ask "List all customers from California" --export customers_ca.csv
+
+# Interactive mode
+datacrew ask --interactive
+```
+
+**Options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--format` | Output format: `table`, `json`, `csv`, `markdown` | `table` |
+| `--export` | Export results to file | None |
+| `--explain` | Show generated SQL query | `false` |
+| `--interactive` | Enter interactive query mode | `false` |
+| `--limit` | Maximum rows to return | `100` |
+
+### `datacrew report`
+
+Generate PDF reports using the multi-agent system.
+
+```bash
+# Generate a report
+datacrew report "Q4 Executive Summary"
+
+# Specify output file
+datacrew report "Q4 Executive Summary" --output reports/q4_summary.pdf
+
+# Use a template
+datacrew report "Monthly Sales" --template executive
+
+# Include specific analyses
+datacrew report "Product Analysis" --include trends,comparisons,recommendations
+```
+
+**Options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--output`, `-o` | Output PDF file path | `./report.pdf` |
+| `--template` | Report template: `executive`, `detailed`, `minimal` | `executive` |
+| `--include` | Analyses to include | All |
+| `--date-range` | Date range for analysis | All data |
+| `--verbose`, `-v` | Show agent reasoning | `false` |
+
+### `datacrew config`
+
+Manage configuration settings.
+
+```bash
+# Show current config
+datacrew config show
+
+# Set LLM model
+datacrew config set llm.model "llama3.2:3b"
+
+# Set database path
+datacrew config set database.path "./data/mydata.db"
+
+# Reset to defaults
+datacrew config reset
+```
+
+### `datacrew schema`
+
+Inspect database schema.
+
+```bash
+# List all tables
+datacrew schema list
+
+# Show table details
+datacrew schema describe sales
+
+# Show sample data
+datacrew schema sample sales --rows 5
+```
+
+---
+
+## Configuration
+
+Configuration is stored in `~/.config/datacrew/config.toml` or `./datacrew.toml` in the project directory.
+
+```toml
+[datacrew]
+version = "1.0.0"
+
+[database]
+path = "./data/datacrew.db"
+echo = false
+
+[llm]
+provider = "docker"           # docker, ollama, openai
+model = "llama3.2:3b"
+temperature = 0.7
+max_tokens = 4096
+base_url = "http://localhost:11434"
+
+[llm.docker]
+runtime = "nvidia"            # nvidia, cpu
+memory_limit = "8g"
+
+[agents]
+verbose = false
+max_iterations = 10
+
+[agents.analyst]
+role = "Data Analyst"
+goal = "Analyze data and write accurate SQL queries"
+
+[agents.insights]
+role = "Insights Specialist"
+goal = "Find meaningful patterns and trends in data"
+
+[agents.writer]
+role = "Report Writer"
+goal = "Create clear, compelling narrative content"
+
+[agents.composer]
+role = "PDF Composer"
+goal = "Assemble professional PDF reports"
+
+[reports]
+output_dir = "./reports"
+default_template = "executive"
+
+[reports.templates.executive]
+include_charts = true
+include_recommendations = true
+max_pages = 10
+
+[reports.templates.detailed]
+include_charts = true
+include_recommendations = true
+include_raw_data = true
+max_pages = 50
+
+[observability]
+enabled = true
+provider = "langfuse"         # langfuse, langsmith, console
+trace_agents = true
+log_tokens = true
+```
+
+---
+
+## Docker Stack
+
+### docker-compose.yml
+
+```yaml
+version: "3.9"
+
+services:
+  # Local LLM via Docker Model Runner
+  llm:
+    image: ollama/ollama:latest
+    runtime: nvidia
+    environment:
+      - OLLAMA_HOST=0.0.0.0
+    volumes:
+      - ollama_data:/root/.ollama
+    ports:
+      - "11434:11434"
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:11434/api/tags"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  # MCP Server for database access
+  mcp-server:
+    build:
+      context: ./src/datacrew/mcp
+      dockerfile: Dockerfile
+    environment:
+      - DATABASE_PATH=/data/datacrew.db
+      - MCP_PORT=3000
+    volumes:
+      - ./data:/data
+    ports:
+      - "3000:3000"
+    depends_on:
+      - llm
+
+  # Main application (for containerized usage)
+  datacrew:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    environment:
+      - LLM_BASE_URL=http://llm:11434
+      - MCP_SERVER_URL=http://mcp-server:3000
+      - DATABASE_PATH=/data/datacrew.db
+    volumes:
+      - ./data:/data
+      - ./reports:/reports
+      - ./input:/input:ro
+    depends_on:
+      llm:
+        condition: service_healthy
+      mcp-server:
+        condition: service_started
+    profiles:
+      - cli
+
+volumes:
+  ollama_data:
+```
+
+### Running the Stack
+
+```bash
+# Start LLM and MCP server
+docker compose up -d llm mcp-server
+
+# Pull the model (first time only)
+docker compose exec llm ollama pull llama3.2:3b
+
+# Run DataCrew commands
+docker compose run --rm datacrew ingest /input/sales.xlsx
+docker compose run --rm datacrew ask "What is total revenue?"
+docker compose run --rm datacrew report "Sales Summary" -o /reports/summary.pdf
+
+# Or run locally with Docker backend
+datacrew ingest sales.xlsx
+datacrew ask "What is total revenue?"
+datacrew report "Sales Summary"
+```
+
+---
+
+## Project Structure
+
+```
+datacrew/
+├── pyproject.toml              # pixi/uv project config
+├── pixi.lock
+├── docker-compose.yml          # Full stack orchestration
+├── Dockerfile
+├── datacrew.toml               # Default configuration
+├── README.md
+│
+├── src/
+│   └── datacrew/
+│       ├── __init__.py
+│       ├── __main__.py         # Entry point
+│       ├── cli.py              # Typer CLI commands
+│       ├── config.py           # TOML configuration loader
+│       │
+│       ├── ingestion/          # CSV/XLSX → SQLite
+│       │   ├── __init__.py
+│       │   ├── readers.py      # File readers (pandas, openpyxl)
+│       │   ├── schema.py       # Schema inference
+│       │   └── database.py     # SQLite operations
+│       │
+│       ├── query/              # Natural language queries
+│       │   ├── __init__.py
+│       │   ├── nl2sql.py       # NL to SQL conversion
+│       │   ├── executor.py     # Query execution
+│       │   └── formatter.py    # Result formatting
+│       │
+│       ├── agents/             # CrewAI agents
+│       │   ├── __init__.py
+│       │   ├── crew.py         # Crew orchestration
+│       │   ├── analyst.py      # Data Analyst agent
+│       │   ├── insights.py     # Insights Specialist agent
+│       │   ├── writer.py       # Report Writer agent
+│       │   └── composer.py     # PDF Composer agent
+│       │
+│       ├── tools/              # Agent tools
+│       │   ├── __init__.py
+│       │   ├── sql_tools.py    # SQL execution tools
+│       │   ├── analysis.py     # Statistical analysis tools
+│       │   └── charts.py       # Chart generation tools
+│       │
+│       ├── mcp/                # MCP server
+│       │   ├── __init__.py
+│       │   ├── server.py       # MCP server implementation
+│       │   ├── tools.py        # MCP tool definitions
+│       │   └── Dockerfile      # MCP server container
+│       │
+│       ├── reports/            # PDF generation
+│       │   ├── __init__.py
+│       │   ├── generator.py    # Report generation orchestrator
+│       │   ├── pdf.py          # PDF creation (WeasyPrint)
+│       │   ├── charts.py       # Chart rendering
+│       │   └── templates/      # HTML/CSS templates
+│       │       ├── executive.html
+│       │       ├── detailed.html
+│       │       ├── minimal.html
+│       │       └── styles.css
+│       │
+│       ├── llm/                # LLM integration
+│       │   ├── __init__.py
+│       │   ├── client.py       # LLM client (Docker/Ollama/OpenAI)
+│       │   └── prompts.py      # Prompt templates
+│       │
+│       └── observability/      # Logging & tracing
+│           ├── __init__.py
+│           ├── tracing.py      # Distributed tracing
+│           └── metrics.py      # Token/cost tracking
+│
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py             # Pytest fixtures
+│   ├── test_cli.py
+│   ├── test_ingestion.py
+│   ├── test_query.py
+│   ├── test_agents.py
+│   ├── test_reports.py
+│   └── fixtures/
+│       ├── sample_sales.csv
+│       ├── sample_products.xlsx
+│       └── expected_outputs/
+│
+├── data/                       # Local data directory
+│   └── .gitkeep
+│
+├── reports/                    # Generated reports
+│   └── .gitkeep
+│
+└── docs/                       # Documentation (Quarto)
+    ├── _quarto.yml
+    ├── index.qmd
+    └── chapters/
+```
+
+---
+
+## Technology Stack
+
+| Category | Tools |
+|----------|-------|
+| **Package Management** | pixi, uv |
+| **CLI Framework** | Typer, Rich |
+| **Local LLM** | Docker Model Runner, Ollama |
+| **LLM Framework** | LangChain |
+| **Multi-Agent** | CrewAI |
+| **MCP** | Docker MCP Toolkit |
+| **Database** | SQLite |
+| **Data Processing** | pandas, openpyxl |
+| **PDF Generation** | WeasyPrint |
+| **Charts** | matplotlib, plotly |
+| **Observability** | Langfuse, OpenTelemetry |
+| **Testing** | pytest, DeepEval |
+| **Containerization** | Docker, Docker Compose |
+
+---
+
+## Example Usage
+
+### End-to-End Workflow
+
+```bash
+# 1. Start the Docker stack
+docker compose up -d
+
+# 2. Ingest your data
+datacrew ingest quarterly_sales_2024.xlsx
+datacrew ingest product_catalog.csv
+datacrew ingest customer_data.csv
+
+# 3. Explore with natural language queries
+datacrew ask "How many records are in each table?"
+datacrew ask "What are the top 10 products by revenue in Q4?"
+datacrew ask "Show me the monthly sales trend for 2024"
+
+# 4. Generate a comprehensive report
+datacrew report "2024 Annual Sales Analysis" \
+  --template detailed \
+  --output reports/annual_2024.pdf \
+  --include trends,top_products,regional_breakdown,recommendations \
+  --verbose
+
+# 5. View agent reasoning (verbose mode)
+# [Data Analyst] Analyzing schema... found 3 tables
+# [Data Analyst] Executing: SELECT strftime('%Y-%m', order_date) as month, SUM(revenue) ...
+# [Insights Agent] Identified trend: 23% YoY growth in Q4
+# [Insights Agent] Anomaly detected: December spike in electronics category
+# [Report Writer] Generating executive summary...
+# [PDF Composer] Assembling 12-page report...
+# ✓ Report saved to reports/annual_2024.pdf
+```
+
+### Sample Report Output
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    2024 Annual Sales Analysis                  │
+│                      Executive Summary                         │
+├────────────────────────────────────────────────────────────────┤
+│                                                                │
+│  Key Findings:                                                 │
+│  • Total revenue: $4.2M (+23% YoY)                            │
+│  • Top product category: Electronics (38% of revenue)         │
+│  • Strongest region: West Coast (42% of sales)                │
+│  • Customer retention rate: 78%                                │
+│                                                                │
+│  [Monthly Revenue Trend Chart]                                 │
+│                                                                │
+│  Recommendations:                                              │
+│  1. Expand electronics inventory for Q1 2025                  │
+│  2. Increase marketing spend in Midwest region                │
+│  3. Launch loyalty program to improve retention               │
+│                                                                │
+└────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Learning Outcomes
+
+By building DataCrew, learners will be able to:
+
+1. ✅ Set up modern Python projects with pixi and reproducible environments
+2. ✅ Build professional CLI tools with Typer and Rich
+3. ✅ Run local LLMs using Docker Model Runner
+4. ✅ Ingest and query data from spreadsheets using natural language
+5. ✅ Build MCP servers to connect AI agents to data sources
+6. ✅ Design multi-agent systems with CrewAI
+7. ✅ Generate PDF reports programmatically
+8. ✅ Implement observability for AI applications
+9. ✅ Test non-deterministic systems effectively
+10. ✅ Deploy self-hosted AI applications with Docker Compose

docs/projects/FileOrganizer.md

@@ -0,0 +1,706 @@
+# Course Project: FileOrganizer
+
+**A CLI tool that uses local LLMs and AI agents to intelligently organize files, with special focus on research paper management.**
+
+---
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     FileOrganizer CLI                            │
+├─────────────────────────────────────────────────────────────────┤
+│  $ fileorg scan ~/Downloads                                     │
+│  $ fileorg organize ~/Papers --strategy=by-topic                │
+│  $ fileorg deduplicate ~/Research --similarity=0.9              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Architecture
+
+```
+Files ──► Content Analysis ──► AI Classification ──► Organized Structure
+              │                        │
+              ▼                        ▼
+        PDF Extraction          Docker Model Runner
+        Metadata Tools            (Local LLM)
+              │                        │
+              └────────►MCP◄───────────┘
+```
+
+### Data Flow
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│  Files/PDFs  │────►│   Content    │────►│  MCP Server  │
+│   (Input)    │     │  Extraction  │     │   (Tools)    │
+└──────────────┘     └──────────────┘     └──────┬───────┘
+                                                  │
+                                                  ▼
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│  Organized   │◄────│  Agent Crew  │◄────│  Local LLM   │
+│  Structure   │     │  (CrewAI)    │     │   (Docker)   │
+└──────────────┘     └──────────────┘     └──────────────┘
+```
+
+---
+
+## Agent System
+
+| Agent | Role | Tools | Output |
+|-------|------|-------|--------|
+| **Scanner Agent** | Discovers files, extracts metadata | File I/O, PDF extraction, hash generation | File inventory, metadata catalog |
+| **Classifier Agent** | Categorizes files by content and context | LLM analysis, embeddings, similarity | Category assignments, topic tags |
+| **Organizer Agent** | Creates folder structure and moves files | File operations, naming strategies | Organized directory tree |
+| **Deduplicator Agent** | Finds and handles duplicate files | Hash comparison, content similarity | Duplicate reports, cleanup actions |
+
+### Agent Workflow
+
+```
+User Request: "Organize research papers by topic"
+                    │
+                    ▼
+         ┌─────────────────────┐
+         │   Scanner Agent     │
+         │  "What files do we  │
+         │   have and what     │
+         │   are they about?"  │
+         └──────────┬──────────┘
+                    │ File Inventory
+                    ▼
+         ┌─────────────────────┐
+         │  Classifier Agent   │
+         │  "What topics and   │
+         │   categories emerge │
+         │   from the content?"│
+         └──────────┬──────────┘
+                    │ Categories
+                    ▼
+         ┌─────────────────────┐
+         │  Organizer Agent    │
+         │  "Create folder     │
+         │   structure and     │
+         │   move files"       │
+         └──────────┬──────────┘
+                    │ Organization Plan
+                    ▼
+         ┌─────────────────────┐
+         │ Deduplicator Agent  │
+         │  "Find and handle   │
+         │   duplicate files"  │
+         └──────────┬──────────┘
+                    │
+                    ▼
+          Organized Directory
+```
+
+---
+
+## CLI Commands
+
+### `fileorg scan`
+
+Scan a directory and analyze its contents.
+
+```bash
+# Scan a directory
+fileorg scan ~/Downloads
+
+# Scan with detailed analysis
+fileorg scan ~/Papers --analyze-content
+
+# Scan and export inventory
+fileorg scan ~/Research --export inventory.json
+
+# Scan specific file types
+fileorg scan ~/Documents --types pdf,docx,txt
+```
+
+**Options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--analyze-content` | Extract and analyze file contents | `false` |
+| `--export` | Export inventory to JSON/CSV | None |
+| `--types` | Comma-separated file extensions to scan | All |
+| `--recursive` | Scan subdirectories | `true` |
+| `--max-depth` | Maximum directory depth | `10` |
+
+### `fileorg organize`
+
+Organize files using AI-powered strategies.
+
+```bash
+# Organize by topic (AI-powered)
+fileorg organize ~/Papers --strategy=by-topic
+
+# Organize by date
+fileorg organize ~/Photos --strategy=by-date --format="%Y/%m"
+
+# Organize with custom naming
+fileorg organize ~/Papers --rename --pattern="{year}_{author}_{title}"
+
+# Dry run to preview changes
+fileorg organize ~/Downloads --dry-run
+
+# Interactive mode
+fileorg organize ~/Research --interactive
+```
+
+**Options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--strategy` | Organization strategy: `by-topic`, `by-date`, `by-type`, `by-author`, `smart` | `smart` |
+| `--rename` | Rename files intelligently | `false` |
+| `--pattern` | Naming pattern for renamed files | `{original}` |
+| `--dry-run` | Preview changes without executing | `false` |
+| `--interactive` | Confirm each action | `false` |
+| `--output` | Output directory | Same as input |
+
+### `fileorg deduplicate`
+
+Find and handle duplicate files.
+
+```bash
+# Find duplicates by hash
+fileorg deduplicate ~/Downloads
+
+# Find similar files (content-based)
+fileorg deduplicate ~/Papers --similarity=0.9
+
+# Auto-delete duplicates (keep newest)
+fileorg deduplicate ~/Photos --auto-delete --keep=newest
+
+# Move duplicates to folder
+fileorg deduplicate ~/Documents --move-to=./duplicates
+```
+
+**Options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--similarity` | Similarity threshold (0.0-1.0) for content matching | `1.0` (exact) |
+| `--method` | Detection method: `hash`, `content`, `metadata` | `hash` |
+| `--auto-delete` | Automatically delete duplicates | `false` |
+| `--keep` | Which to keep: `newest`, `oldest`, `largest`, `smallest` | `newest` |
+| `--move-to` | Move duplicates to directory instead of deleting | None |
+
+### `fileorg research`
+
+Special commands for research paper management.
+
+```bash
+# Extract metadata from PDFs
+fileorg research extract ~/Papers
+
+# Generate bibliography
+fileorg research bibliography ~/Papers --format=bibtex --output=refs.bib
+
+# Find related papers
+fileorg research related "attention mechanisms" --in ~/Papers
+
+# Create reading list
+fileorg research reading-list ~/Papers --topic "transformers" --order=citations
+```
+
+**Options:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--format` | Bibliography format: `bibtex`, `apa`, `mla` | `bibtex` |
+| `--output` | Output file path | `stdout` |
+| `--order` | Sort order: `date`, `citations`, `relevance` | `relevance` |
+
+### `fileorg config`
+
+Manage configuration settings.
+
+```bash
+# Show current config
+fileorg config show
+
+# Set LLM model
+fileorg config set llm.model "llama3.2:3b"
+
+# Set default strategy
+fileorg config set organize.default_strategy "by-topic"
+
+# Reset to defaults
+fileorg config reset
+```
+
+### `fileorg stats`
+
+Show statistics about files and organization.
+
+```bash
+# Show directory statistics
+fileorg stats ~/Papers
+
+# Show organization suggestions
+fileorg stats ~/Downloads --suggest
+
+# Export statistics
+fileorg stats ~/Research --export stats.json
+```
+
+---
+
+## Configuration
+
+Configuration is stored in `~/.config/fileorg/config.toml` or `./fileorg.toml` in the project directory.
+
+```toml
+[fileorg]
+version = "1.0.0"
+
+[llm]
+provider = "docker"           # docker, ollama, openai
+model = "llama3.2:3b"
+temperature = 0.7
+max_tokens = 4096
+base_url = "http://localhost:11434"
+
+[llm.docker]
+runtime = "nvidia"            # nvidia, cpu
+memory_limit = "8g"
+
+[agents]
+verbose = false
+max_iterations = 10
+
+[agents.scanner]
+role = "File Scanner"
+goal = "Discover and catalog all files with metadata"
+
+[agents.classifier]
+role = "Content Classifier"
+goal = "Categorize files by content and context"
+
+[agents.organizer]
+role = "File Organizer"
+goal = "Create optimal folder structure and organize files"
+
+[agents.deduplicator]
+role = "Duplicate Detector"
+goal = "Find and handle duplicate files efficiently"
+
+[organize]
+default_strategy = "smart"
+create_backups = true
+backup_dir = "./.fileorg_backup"
+
+[organize.naming]
+sanitize = true
+max_length = 255
+replace_spaces = "_"
+
+[research]
+extract_metadata = true
+auto_rename = true
+naming_pattern = "{year}_{author}_{title}"
+generate_bibliography = true
+
+[deduplication]
+default_method = "hash"
+similarity_threshold = 0.95
+auto_delete = false
+keep_strategy = "newest"
+
+[pdf]
+extract_text = true
+extract_metadata = true
+ocr_enabled = false           # Enable OCR for scanned PDFs
+
+[observability]
+enabled = true
+provider = "langfuse"         # langfuse, langsmith, console
+trace_agents = true
+log_tokens = true
+```
+
+---
+
+## Docker Stack
+
+### docker-compose.yml
+
+```yaml
+version: "3.9"
+
+services:
+  # Local LLM via Docker Model Runner
+  llm:
+    image: ollama/ollama:latest
+    runtime: nvidia
+    environment:
+      - OLLAMA_HOST=0.0.0.0
+    volumes:
+      - ollama_data:/root/.ollama
+    ports:
+      - "11434:11434"
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:11434/api/tags"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  # MCP Server for file operations and PDF tools
+  mcp-server:
+    build:
+      context: ./src/fileorg/mcp
+      dockerfile: Dockerfile
+    environment:
+      - MCP_PORT=3000
+    volumes:
+      - ./workspace:/workspace
+    ports:
+      - "3000:3000"
+    depends_on:
+      - llm
+
+  # Main application (for containerized usage)
+  fileorg:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    environment:
+      - LLM_BASE_URL=http://llm:11434
+      - MCP_SERVER_URL=http://mcp-server:3000
+    volumes:
+      - ./workspace:/workspace
+      - ./config:/config:ro
+    depends_on:
+      llm:
+        condition: service_healthy
+      mcp-server:
+        condition: service_started
+    profiles:
+      - cli
+
+volumes:
+  ollama_data:
+```
+
+### Running the Stack
+
+```bash
+# Start LLM and MCP server
+docker compose up -d llm mcp-server
+
+# Pull the model (first time only)
+docker compose exec llm ollama pull llama3.2:3b
+
+# Run FileOrganizer commands
+docker compose run --rm fileorg scan /workspace/papers
+docker compose run --rm fileorg organize /workspace/papers --strategy=by-topic
+docker compose run --rm fileorg deduplicate /workspace/downloads
+
+# Or run locally with Docker backend
+fileorg scan ~/Papers
+fileorg organize ~/Papers --strategy=by-topic
+fileorg deduplicate ~/Downloads
+```
+
+---
+
+## Project Structure
+
+```
+fileorg/
+├── pyproject.toml              # pixi/uv project config
+├── pixi.lock
+├── docker-compose.yml          # Full stack orchestration
+├── Dockerfile
+├── fileorg.toml                # Default configuration
+├── README.md
+│
+├── src/
+│   └── fileorg/
+│       ├── __init__.py
+│       ├── __main__.py         # Entry point
+│       ├── cli.py              # Typer CLI commands
+│       ├── config.py           # TOML configuration loader
+│       │
+│       ├── scanner/            # File discovery and analysis
+│       │   ├── __init__.py
+│       │   ├── discovery.py    # File system traversal
+│       │   ├── metadata.py     # Metadata extraction
+│       │   ├── pdf_reader.py   # PDF text/metadata extraction
+│       │   └── hashing.py      # File hashing utilities
+│       │
+│       ├── classifier/         # Content classification
+│       │   ├── __init__.py
+│       │   ├── embeddings.py   # Generate embeddings
+│       │   ├── clustering.py   # Topic clustering
+│       │   ├── categorizer.py  # AI-powered categorization
+│       │   └── similarity.py   # Content similarity
+│       │
+│       ├── organizer/          # File organization
+│       │   ├── __init__.py
+│       │   ├── strategies.py   # Organization strategies
+│       │   ├── naming.py       # File naming logic
+│       │   ├── structure.py    # Directory structure creation
+│       │   └── mover.py        # Safe file operations
+│       │
+│       ├── deduplicator/       # Duplicate detection
+│       │   ├── __init__.py
+│       │   ├── hash_based.py   # Hash-based detection
+│       │   ├── content_based.py # Content similarity detection
+│       │   └── handler.py      # Duplicate handling
+│       │
+│       ├── research/           # Research paper tools
+│       │   ├── __init__.py
+│       │   ├── extractor.py    # PDF metadata extraction
+│       │   ├── bibliography.py # Bibliography generation
+│       │   ├── citation.py     # Citation parsing
+│       │   └── scholar.py      # Academic search integration
+│       │
+│       ├── agents/             # CrewAI agents
+│       │   ├── __init__.py
+│       │   ├── crew.py         # Crew orchestration
+│       │   ├── scanner.py      # Scanner agent
+│       │   ├── classifier.py   # Classifier agent
+│       │   ├── organizer.py    # Organizer agent
+│       │   └── deduplicator.py # Deduplicator agent
+│       │
+│       ├── tools/              # Agent tools
+│       │   ├── __init__.py
+│       │   ├── file_tools.py   # File operation tools
+│       │   ├── pdf_tools.py    # PDF processing tools
+│       │   ├── search_tools.py # Search and query tools
+│       │   └── analysis.py     # Content analysis tools
+│       │
+│       ├── mcp/                # MCP server
+│       │   ├── __init__.py
+│       │   ├── server.py       # MCP server implementation
+│       │   ├── tools.py        # MCP tool definitions
+│       │   └── Dockerfile      # MCP server container
+│       │
+│       ├── llm/                # LLM integration
+│       │   ├── __init__.py
+│       │   ├── client.py       # LLM client (Docker/Ollama/OpenAI)
+│       │   └── prompts.py      # Prompt templates
+│       │
+│       └── observability/      # Logging & tracing
+│           ├── __init__.py
+│           ├── tracing.py      # Distributed tracing
+│           └── metrics.py      # Token/cost tracking
+│
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py             # Pytest fixtures
+│   ├── test_cli.py
+│   ├── test_scanner.py
+│   ├── test_classifier.py
+│   ├── test_organizer.py
+│   ├── test_deduplicator.py
+│   ├── test_research.py
+│   └── fixtures/
+│       ├── sample_papers/
+│       │   ├── paper1.pdf
+│       │   ├── paper2.pdf
+│       │   └── paper3.pdf
+│       ├── sample_files/
+│       └── expected_outputs/
+│
+├── workspace/                  # Working directory
+│   └── .gitkeep
+│
+└── docs/                       # Documentation (Quarto)
+    ├── _quarto.yml
+    ├── index.qmd
+    └── chapters/
+```
+
+---
+
+## Technology Stack
+
+| Category | Tools |
+|----------|-------|
+| **Package Management** | pixi, uv |
+| **CLI Framework** | Typer, Rich |
+| **Local LLM** | Docker Model Runner, Ollama |
+| **LLM Framework** | LangChain |
+| **Multi-Agent** | CrewAI |
+| **MCP** | Docker MCP Toolkit |
+| **PDF Processing** | PyPDF2, pdfplumber, pypdf |
+| **Embeddings** | sentence-transformers |
+| **File Operations** | pathlib, shutil |
+| **Hashing** | hashlib, xxhash |
+| **Metadata** | exifread, mutagen |
+| **Similarity** | scikit-learn, faiss |
+| **Observability** | Langfuse, OpenTelemetry |
+| **Testing** | pytest, DeepEval |
+| **Containerization** | Docker, Docker Compose |
+
+---
+
+## Example Usage
+
+### End-to-End Workflow
+
+```bash
+# 1. Start the Docker stack
+docker compose up -d
+
+# 2. Scan your messy Downloads folder
+fileorg scan ~/Downloads --analyze-content --export downloads_inventory.json
+
+# 3. Organize files by type and date
+fileorg organize ~/Downloads --strategy=smart --dry-run
+# Review the plan, then execute
+fileorg organize ~/Downloads --strategy=smart
+
+# 4. Organize research papers by topic
+fileorg scan ~/Papers --types=pdf --analyze-content
+fileorg organize ~/Papers --strategy=by-topic --rename --pattern="{year}_{author}_{title}"
+
+# 5. Find and handle duplicates
+fileorg deduplicate ~/Papers --similarity=0.95 --move-to=./duplicates
+
+# 6. Extract metadata and generate bibliography
+fileorg research extract ~/Papers
+fileorg research bibliography ~/Papers --format=bibtex --output=references.bib
+
+# 7. Create a reading list on a specific topic
+fileorg research reading-list ~/Papers --topic "transformers" --order=citations
+
+# 8. View statistics
+fileorg stats ~/Papers
+```
+
+### Research Paper Organization Example
+
+```bash
+# Before:
+~/Papers/
+├── paper_final.pdf
+├── attention_is_all_you_need.pdf
+├── bert_paper.pdf
+├── gpt3.pdf
+├── vision_transformer.pdf
+├── download (1).pdf
+├── download (2).pdf
+└── thesis_draft_v5.pdf
+
+# Run organization
+fileorg organize ~/Papers --strategy=by-topic --rename
+
+# After:
+~/Papers/
+├── Natural_Language_Processing/
+│   ├── Transformers/
+│   │   ├── 2017_Vaswani_Attention_Is_All_You_Need.pdf
+│   │   ├── 2018_Devlin_BERT_Pretraining.pdf
+│   │   └── 2020_Brown_GPT3_Language_Models.pdf
+│   └── Other/
+│       └── 2023_Smith_Thesis_Draft.pdf
+├── Computer_Vision/
+│   └── Transformers/
+│       └── 2020_Dosovitskiy_Vision_Transformer.pdf
+└── Uncategorized/
+    └── 2024_Unknown_Document.pdf
+```
+
+### Duplicate Detection Example
+
+```bash
+# Find exact duplicates
+fileorg deduplicate ~/Downloads
+# Found 15 duplicate files (45 MB)
+# • download.pdf (3 copies)
+# • image.jpg (2 copies)
+# • report.docx (2 copies)
+
+# Find similar papers (different versions)
+fileorg deduplicate ~/Papers --similarity=0.9 --method=content
+# Found 3 similar file groups:
+# • attention_paper.pdf, attention_is_all_you_need.pdf (95% similar)
+# • bert_preprint.pdf, bert_final.pdf (98% similar)
+
+# Auto-cleanup (keep newest)
+fileorg deduplicate ~/Downloads --auto-delete --keep=newest
+# ✓ Deleted 15 duplicate files, freed 45 MB
+```
+
+---
+
+## Learning Outcomes
+
+By building FileOrganizer, learners will be able to:
+
+1. ✅ Set up modern Python projects with pixi and reproducible environments
+2. ✅ Build professional CLI tools with Typer and Rich
+3. ✅ Run local LLMs using Docker Model Runner
+4. ✅ Process and extract content from PDF files
+5. ✅ Build MCP servers to connect AI agents to file systems
+6. ✅ Design multi-agent systems with CrewAI
+7. ✅ Implement content-based similarity and clustering
+8. ✅ Generate embeddings for semantic search
+9. ✅ Handle file operations safely with backups and dry-run modes
+10. ✅ Implement observability for AI applications
+11. ✅ Test non-deterministic systems effectively
+12. ✅ Deploy self-hosted AI applications with Docker Compose
+
+---
+
+## Advanced Features
+
+### Smart Organization Strategy
+
+The `smart` strategy uses AI to analyze file content and context to determine the best organization approach:
+
+```python
+# Pseudocode for smart strategy
+def smart_organize(files):
+    # 1. Analyze file types and content
+    file_analysis = scanner_agent.analyze(files)
+    
+    # 2. Determine optimal strategy
+    if mostly_pdfs_with_academic_content:
+        strategy = "by-topic-hierarchical"
+    elif mostly_media_files:
+        strategy = "by-date-and-type"
+    elif mixed_work_documents:
+        strategy = "by-project-and-date"
+    
+    # 3. Execute with AI-powered categorization
+    classifier_agent.categorize(files, strategy)
+    organizer_agent.execute(strategy)
+```
+
+### Research Paper Features
+
+Special handling for academic PDFs:
+
+- **Metadata Extraction**: Title, authors, year, abstract, keywords
+- **Citation Parsing**: Extract and parse references
+- **Smart Naming**: `{year}_{first_author}_{short_title}.pdf`
+- **Topic Clustering**: Group papers by research area
+- **Citation Network**: Identify related papers
+- **Bibliography Generation**: BibTeX, APA, MLA formats
+
+### Deduplication Strategies
+
+Multiple methods for finding duplicates:
+
+1. **Hash-based**: Exact file matches (fastest)
+2. **Content-based**: Similar content using embeddings
+3. **Metadata-based**: Same title/author but different files
+4. **Fuzzy matching**: Handle renamed or modified files
+
+---
+
+*This project serves as the main example in the [Learning Path](../learning-path.md) for building AI-powered CLI tools.*

docs/projects/README.md

@@ -0,0 +1,350 @@
+# Python Package Ideas: CLI Tools for AI & Daily Operations
+
+A curated list of Python package ideas that combine CLI interfaces with AI capabilities for day-to-day productivity and agent automation.
+
+## 📊 Data & Analytics Tools
+
+### 1. **smart-csv**
+- **Purpose**: Intelligent CSV manipulation with natural language queries
+- **CLI Features**: 
+  - `smart-csv query data.csv "show me top 10 customers by revenue"`
+  - `smart-csv transform data.csv --operation "normalize dates"`
+  - `smart-csv merge file1.csv file2.csv --ai-match-columns`
+- **AI Integration**: LLM-powered column matching, data cleaning suggestions, anomaly detection
+- **Agent Use**: Data preprocessing, ETL operations, report generation
+
+### 2. **log-insight**
+- **Purpose**: AI-powered log analysis and troubleshooting
+- **CLI Features**:
+  - `log-insight analyze app.log --find-errors`
+  - `log-insight pattern-detect --timerange "last 24h"`
+  - `log-insight explain-error "stack trace here"`
+- **AI Integration**: Pattern recognition, root cause analysis, predictive alerts
+- **Agent Use**: Automated debugging, system monitoring, incident response
+
+### 3. **data-profiler-ai**
+- **Purpose**: Automated data quality assessment and profiling
+- **CLI Features**:
+  - `data-profiler scan dataset.parquet --generate-report`
+  - `data-profiler validate schema.json data.csv`
+  - `data-profiler suggest-types unknown-data.csv`
+- **AI Integration**: Schema inference, data type detection, quality scoring
+- **Agent Use**: Data validation pipelines, schema evolution tracking
+
+## 🤖 AI Agent Utilities
+
+### 4. **prompt-forge**
+- **Purpose**: Prompt template management and optimization
+- **CLI Features**:
+  - `prompt-forge create --template customer-support`
+  - `prompt-forge test prompt.txt --model gpt-4 --iterations 10`
+  - `prompt-forge optimize --goal "reduce tokens by 20%"`
+- **AI Integration**: Prompt optimization, A/B testing, version control
+- **Agent Use**: Dynamic prompt generation, context management
+
+### 5. **agent-memory**
+- **Purpose**: Persistent memory and context management for AI agents
+- **CLI Features**:
+  - `agent-memory store --key "user_preferences" --value "..."`
+  - `agent-memory recall --query "what did user say about deadlines?"`
+  - `agent-memory summarize --session-id abc123`
+- **AI Integration**: Semantic search, context compression, memory consolidation
+- **Agent Use**: Long-term memory, conversation history, knowledge graphs
+
+### 6. **tool-registry**
+- **Purpose**: Discover, validate, and manage tools for AI agents
+- **CLI Features**:
+  - `tool-registry search "weather API"`
+  - `tool-registry validate my-tool.json`
+  - `tool-registry generate-schema --from-function get_weather`
+- **AI Integration**: Tool recommendation, capability matching, auto-documentation
+- **Agent Use**: Dynamic tool discovery, function calling, API integration
+
+## 📝 Document & Content Processing
+
+### 7. **doc-extract-ai**
+- **Purpose**: Intelligent document parsing and information extraction
+- **CLI Features**:
+  - `doc-extract parse invoice.pdf --extract "vendor, amount, date"`
+  - `doc-extract batch-process ./documents --type receipts`
+  - `doc-extract to-markdown presentation.pptx`
+- **AI Integration**: Layout understanding, entity extraction, format conversion
+- **Agent Use**: Document automation, data entry, content migration
+
+### 8. **smart-summarize**
+- **Purpose**: Multi-format content summarization
+- **CLI Features**:
+  - `smart-summarize article.txt --length 100`
+  - `smart-summarize meeting-notes.md --extract-action-items`
+  - `smart-summarize youtube-url --transcript-summary`
+- **AI Integration**: Abstractive summarization, key point extraction, multi-document synthesis
+- **Agent Use**: Report generation, meeting notes, research assistance
+
+### 9. **content-repurpose**
+- **Purpose**: Transform content across formats and styles
+- **CLI Features**:
+  - `content-repurpose blog-post.md --to twitter-thread`
+  - `content-repurpose presentation.pptx --to blog-post`
+  - `content-repurpose --style "technical to beginner-friendly"`
+- **AI Integration**: Style transfer, format adaptation, audience targeting
+- **Agent Use**: Content marketing, documentation, social media automation
+
+## 🔍 Code & Development Tools
+
+### 10. **code-review-ai**
+- **Purpose**: Automated code review and improvement suggestions
+- **CLI Features**:
+  - `code-review analyze src/ --focus security`
+  - `code-review suggest-refactor messy-function.py`
+  - `code-review explain --file complex.py --line 42`
+- **AI Integration**: Code understanding, best practice detection, vulnerability scanning
+- **Agent Use**: CI/CD integration, code quality gates, learning assistant
+
+### 11. **test-gen-ai**
+- **Purpose**: Intelligent test case generation
+- **CLI Features**:
+  - `test-gen create --file calculator.py --coverage 90`
+  - `test-gen edge-cases --function parse_date`
+  - `test-gen from-spec requirements.md`
+- **AI Integration**: Code analysis, edge case discovery, test oracle generation
+- **Agent Use**: Test automation, TDD assistance, regression testing
+
+### 12. **doc-string-ai**
+- **Purpose**: Automated documentation generation
+- **CLI Features**:
+  - `doc-string generate src/ --style google`
+  - `doc-string update --file api.py --sync-with-code`
+  - `doc-string readme --project-root .`
+- **AI Integration**: Code comprehension, example generation, API documentation
+- **Agent Use**: Documentation maintenance, onboarding, API reference
+
+## 🌐 Web & API Tools
+
+### 13. **api-explorer-ai**
+- **Purpose**: Intelligent API testing and exploration
+- **CLI Features**:
+  - `api-explorer discover https://api.example.com`
+  - `api-explorer test --endpoint /users --generate-scenarios`
+  - `api-explorer mock --from-openapi spec.yaml`
+- **AI Integration**: Endpoint discovery, test case generation, response validation
+- **Agent Use**: API integration, testing automation, mock server generation
+
+### 14. **web-scrape-smart**
+- **Purpose**: AI-powered web scraping with anti-detection
+- **CLI Features**:
+  - `web-scrape extract https://example.com --schema product-listing`
+  - `web-scrape monitor --url news-site.com --alert-on-change`
+  - `web-scrape batch urls.txt --parallel 5`
+- **AI Integration**: Layout understanding, content extraction, CAPTCHA solving
+- **Agent Use**: Data collection, price monitoring, content aggregation
+
+## 📧 Communication & Workflow
+
+### 15. **email-assistant-cli**
+- **Purpose**: Email management and automation
+- **CLI Features**:
+  - `email-assistant draft --to client@example.com --context "project update"`
+  - `email-assistant triage inbox --auto-label --priority-score`
+  - `email-assistant respond --template "meeting-request"`
+- **AI Integration**: Email classification, response generation, sentiment analysis
+- **Agent Use**: Email automation, customer support, scheduling
+
+### 16. **meeting-prep-ai**
+- **Purpose**: Automated meeting preparation and follow-up
+- **CLI Features**:
+  - `meeting-prep agenda --topic "Q4 planning" --attendees team.json`
+  - `meeting-prep transcribe recording.mp3 --extract-decisions`
+  - `meeting-prep follow-up --assign-tasks`
+- **AI Integration**: Agenda generation, transcription, action item extraction
+- **Agent Use**: Meeting automation, task management, documentation
+
+### 17. **slack-digest**
+- **Purpose**: Intelligent Slack/Teams message summarization
+- **CLI Features**:
+  - `slack-digest summarize --channel engineering --since yesterday`
+  - `slack-digest extract-decisions --thread-url "..."`
+  - `slack-digest notify --important-only`
+- **AI Integration**: Message clustering, importance scoring, thread summarization
+- **Agent Use**: Team communication, information retrieval, notification management
+
+## 🔧 System & DevOps Tools
+
+### 18. **config-validator-ai**
+- **Purpose**: Intelligent configuration validation and optimization
+- **CLI Features**:
+  - `config-validator check docker-compose.yml --suggest-improvements`
+  - `config-validator migrate --from v1 --to v2`
+  - `config-validator security-scan kubernetes/`
+- **AI Integration**: Best practice detection, security analysis, migration assistance
+- **Agent Use**: Infrastructure as code, deployment automation, security compliance
+
+### 19. **error-translator**
+- **Purpose**: Translate technical errors to actionable solutions
+- **CLI Features**:
+  - `error-translator explain "segmentation fault core dumped"`
+  - `error-translator fix --error-log build.log --suggest-commands`
+  - `error-translator learn-from-fix --before error.txt --after solution.txt`
+- **AI Integration**: Error pattern matching, solution database, context-aware suggestions
+- **Agent Use**: Debugging assistance, self-healing systems, knowledge base
+
+### 20. **dependency-doctor**
+- **Purpose**: Smart dependency management and conflict resolution
+- **CLI Features**:
+  - `dependency-doctor audit --fix-vulnerabilities`
+  - `dependency-doctor optimize --reduce-size`
+  - `dependency-doctor explain --package requests --why-needed`
+- **AI Integration**: Dependency graph analysis, alternative suggestions, impact prediction
+- **Agent Use**: Security patching, build optimization, dependency updates
+
+## 🎨 Creative & Media Tools
+
+### 21. **image-caption-cli**
+- **Purpose**: Automated image analysis and captioning
+- **CLI Features**:
+  - `image-caption generate photo.jpg --style descriptive`
+  - `image-caption batch-process ./photos --alt-text`
+  - `image-caption search ./images --query "sunset beach"`
+- **AI Integration**: Vision models, semantic search, accessibility text generation
+- **Agent Use**: Content management, SEO optimization, accessibility compliance
+
+### 22. **video-chapter-ai**
+- **Purpose**: Automatic video chapter generation and editing
+- **CLI Features**:
+  - `video-chapter detect video.mp4 --create-chapters`
+  - `video-chapter highlight --topic "product demo"`
+  - `video-chapter transcribe --with-timestamps`
+- **AI Integration**: Scene detection, topic segmentation, speech recognition
+- **Agent Use**: Video processing, content creation, accessibility
+
+## 🔐 Security & Privacy Tools
+
+### 23. **secret-scanner-ai**
+- **Purpose**: Intelligent secret detection and rotation
+- **CLI Features**:
+  - `secret-scanner scan . --deep`
+  - `secret-scanner rotate --service aws --auto-update-configs`
+  - `secret-scanner audit-history --find-leaks`
+- **AI Integration**: Pattern learning, false positive reduction, context-aware detection
+- **Agent Use**: Security automation, compliance, incident response
+
+### 24. **privacy-guard-cli**
+- **Purpose**: PII detection and data anonymization
+- **CLI Features**:
+  - `privacy-guard scan dataset.csv --detect-pii`
+  - `privacy-guard anonymize --method k-anonymity`
+  - `privacy-guard compliance-check --regulation GDPR`
+- **AI Integration**: Entity recognition, anonymization strategies, compliance validation
+- **Agent Use**: Data processing, compliance automation, privacy engineering
+
+## 📚 Knowledge & Research Tools
+
+### 25. **paper-digest**
+- **Purpose**: Academic paper summarization and analysis
+- **CLI Features**:
+  - `paper-digest summarize paper.pdf --technical-level intermediate`
+  - `paper-digest compare paper1.pdf paper2.pdf`
+  - `paper-digest extract-methods --output markdown`
+- **AI Integration**: Scientific text understanding, citation analysis, methodology extraction
+- **Agent Use**: Research assistance, literature review, knowledge synthesis
+
+### 26. **kb-builder**
+- **Purpose**: Automated knowledge base construction
+- **CLI Features**:
+  - `kb-builder index ./docs --create-embeddings`
+  - `kb-builder query "how to deploy?" --with-sources`
+  - `kb-builder update --incremental --watch`
+- **AI Integration**: Semantic search, document chunking, question answering
+- **Agent Use**: Documentation search, customer support, internal wiki
+
+### 27. **citation-manager-ai**
+- **Purpose**: Smart citation management and bibliography generation
+- **CLI Features**:
+  - `citation-manager extract paper.pdf --format bibtex`
+  - `citation-manager validate references.bib`
+  - `citation-manager suggest-related --topic "machine learning"`
+- **AI Integration**: Citation extraction, duplicate detection, related work discovery
+- **Agent Use**: Academic writing, research management, bibliography maintenance
+
+## 🎯 Productivity & Automation
+
+### 28. **task-prioritizer**
+- **Purpose**: AI-powered task management and prioritization
+- **CLI Features**:
+  - `task-prioritizer add "implement feature X" --context project.md`
+  - `task-prioritizer suggest-next --based-on energy-level:low`
+  - `task-prioritizer estimate --task "write tests"`
+- **AI Integration**: Priority scoring, time estimation, dependency detection
+- **Agent Use**: Project management, personal productivity, resource allocation
+
+### 29. **workflow-optimizer**
+- **Purpose**: Analyze and optimize repetitive workflows
+- **CLI Features**:
+  - `workflow-optimizer record --name "daily-standup-prep"`
+  - `workflow-optimizer analyze --suggest-automation`
+  - `workflow-optimizer generate-script --workflow deployment`
+- **AI Integration**: Pattern detection, automation suggestions, efficiency analysis
+- **Agent Use**: Process automation, productivity improvement, workflow design
+
+### 30. **context-switch-helper**
+- **Purpose**: Manage context switching with AI assistance
+- **CLI Features**:
+  - `context-switch save --project backend-api`
+  - `context-switch restore --project frontend`
+  - `context-switch summarize --what-changed-since-last`
+- **AI Integration**: State capture, change summarization, context reconstruction
+- **Agent Use**: Developer productivity, project management, focus optimization
+
+---
+
+## 🏗️ Implementation Considerations
+
+### Common Features Across Tools:
+- **Streaming Output**: Real-time progress for long-running operations
+- **Configuration Files**: YAML/TOML config for defaults and presets
+- **Plugin Architecture**: Extensible with custom processors/models
+- **Multi-Model Support**: OpenAI, Anthropic, local models (Ollama)
+- **Caching**: Intelligent caching to reduce API costs
+- **Batch Processing**: Handle multiple files/inputs efficiently
+- **Output Formats**: JSON, Markdown, CSV, HTML for different use cases
+- **Logging & Telemetry**: Track usage, errors, and performance
+- **Offline Mode**: Local model support for privacy/offline use
+
+### Agent-Friendly Design Patterns:
+1. **Structured Output**: JSON schemas for reliable parsing
+2. **Idempotency**: Safe to retry operations
+3. **Progress Tracking**: Machine-readable status updates
+4. **Error Codes**: Standardized exit codes and error messages
+5. **Composability**: Unix philosophy - do one thing well, pipe-friendly
+6. **API Mode**: HTTP server mode for agent integration
+7. **Webhooks**: Event-driven notifications for async operations
+
+### Technology Stack Suggestions:
+- **CLI Framework**: Click, Typer, or argparse
+- **AI Integration**: LangChain, LlamaIndex, or direct API calls
+- **Async Operations**: asyncio, aiohttp for concurrent processing
+- **Configuration**: Pydantic for validation, dynaconf for management
+- **Testing**: pytest with fixtures for AI mocking
+- **Packaging**: Poetry or uv for dependency management
+- **Distribution**: PyPI, with optional Docker images
+
+---
+
+## 📈 Market Opportunities
+
+### High-Impact Categories:
+1. **Developer Tools** (code-review-ai, test-gen-ai, doc-string-ai)
+2. **Data Processing** (smart-csv, data-profiler-ai, doc-extract-ai)
+3. **Content Creation** (smart-summarize, content-repurpose)
+4. **Security** (secret-scanner-ai, privacy-guard-cli)
+5. **Productivity** (task-prioritizer, email-assistant-cli)
+
+### Differentiation Strategies:
+- **Local-First**: Privacy-focused with local model support
+- **Cost-Optimized**: Intelligent caching and batching to reduce API costs
+- **Domain-Specific**: Deep expertise in particular verticals
+- **Integration-Rich**: Works with existing tools (Git, Jira, Slack)
+- **Open Source**: Community-driven with premium features
+
+---
+
+*Generated: 2025-12-04*

pixi.toml

@@ -0,0 +1,27 @@
+[project]
+name = "kashi-coding-handbook"
+version = "0.1.0"
+description = "Kashi Coding Handbook - Building AI-Powered CLI Tools with Python"
+authors = ["Kashi School of Computing"]
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-64", "osx-arm64", "win-64"]
+
+[dependencies]
+python = ">=3.11"
+quarto = ">=1.8.26,<2"
+
+[tasks]
+install-quarto-extensions = "cd src; quarto install extension grantmcdermott/quarto-revealjs-clean; quarto install extension pandoc-ext/diagram"
+install-tinytex = "quarto install tinytex"
+preview = "quarto preview src"
+render = "quarto render src"
+serve = "python serve.py"
+
+[feature.dev.dependencies]
+black = ">=25.1.0,<26"
+ruff = ">=0.14.8,<0.15"
+mypy = ">=1.19.0,<2"
+
+[environments]
+default = []
+dev = ["dev"]

requirements.txt

@@ -1,3 +0,0 @@
-pandas
-seaborn
-jupyter

serve.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+"""Simple HTTP server for serving the rendered Quarto site."""
+
+import http.server
+import socketserver
+import os
+
+PORT = 7860
+DIRECTORY = "src/_site"
+
+class Handler(http.server.SimpleHTTPRequestHandler):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, directory=DIRECTORY, **kwargs)
+
+if __name__ == "__main__":
+    os.chdir(os.path.dirname(os.path.abspath(__file__)))
+    
+    with socketserver.TCPServer(("", PORT), Handler) as httpd:
+        print(f"Serving {DIRECTORY} at http://0.0.0.0:{PORT}")
+        httpd.serve_forever()

src/.gitignore

@@ -1 +1,3 @@
 /.quarto/
+
+**/*.quarto_ipynb

src/_extensions/grantmcdermott/clean/_extension.yml

@@ -0,0 +1,20 @@
+title: clean
+author: Grant McDermott
+version: 1.4.1
+quarto-required: ">=1.3.0"
+contributes:
+  formats:
+    revealjs:
+      theme: [default, clean.scss]
+      menu:
+        side: left
+      slide-number: true
+      date-format: long
+      html-math-method:
+        method: mathjax
+        url: "https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js"
+      include-before-body:
+        - text: |
+            <script src="mathjax-config.js"></script>
+      format-resources:
+        - mathjax-config.js

src/_extensions/grantmcdermott/clean/clean.scss

@@ -0,0 +1,351 @@
+/*-- scss:defaults --*/
+
+// Custom colours and variables
+
+$jet: #131516;
+$accent: #107895;
+$accent2: #9a2515;
+// $accent2: #e64173;
+$right-arrow: "\2192"; // Unicode character for right arrow
+
+// fonts
+
+/*
+Note: This theme uses the Roboto font family, which it imports from Google
+  Fonts to ensure consistent weighting in addition to availability. While
+  you can use a local installation of Roboto, this is generally not 
+  recommended since the weighting will likely be wrong (probably too
+  light). OTOH, importing from Google Fonts can cause some issues in
+  certain secure environments due the external CDN (see:
+  https://github.com/grantmcdermott/quarto-revealjs-clean/issues/7). If
+  that's the case for you, simply comment out the `@import url(...)` line
+  below and it will default for the default Sans Serif font on your system
+  (e.g., Helvetica on a Mac). Circling back to the earlier point about
+  preserving consistent font weights, you may also wish to remove "Roboto"
+  from the choice set if the family is installed locally.
+*/
+@import url('https://fonts.googleapis.com/css?family=Roboto:200,200i,300,300i,350,350i,400,400i&display=swap');
+
+$font-family-sans-serif: "Roboto", sans-serif !default;
+$presentation-heading-font: "Roboto", sans-serif !default;
+
+$presentation-heading-color: $jet !default;
+$presentation-heading-font-weight: lighter;
+//$presentation-heading-line-height: 2;
+//$presentation-block-margin: 28px;
+$presentation-font-size-root: 32px;
+
+// colors
+//$body-bg: #f0f1eb !default;
+$body-color: $jet !default;
+$link-color: $accent !default;
+$selection-bg: #26351c !default;
+
+
+/*-- scss:rules --*/
+
+.reveal a {
+  line-height: 1.5em;
+}
+
+.reveal p {
+  // font-weight: 300;
+  font-weight: lighter;
+  margin-top: 1.25em;
+}
+
+// title and headings
+
+#title-slide {
+  text-align: left;
+
+  .title {
+    color: $body-color;
+    font-size: 1.4em;
+    // font-weight: 350;
+    font-weight: lighter;
+  }
+
+  .subtitle {
+    color: $accent;
+    font-style: italic;
+    margin-top: 0em;
+    font-weight: lighter;
+  }
+
+  .institute,
+  .quarto-title-affiliation,
+  .quarto-title-author-email {
+    font-style: italic;
+    // font-size: 80%;
+    // color: #7F7F7F;
+  }
+
+  .author,
+  .quarto-title-author-name {
+    color: $body-color;
+  }
+
+  .quarto-title-authors {
+    display: flex;
+    justify-content: left;
+
+    .quarto-title-author {
+      padding-left: 0em;
+      padding-right: 0em;
+      width: 100%;
+    }
+  }
+
+}
+
+
+.reveal h2 {
+  // font-weight: 350;
+  font-weight: lighter;
+  font-size: 1.4em;
+}
+
+.reveal h3 {
+  color: $accent;
+  font-style: italic;
+  // font-weight: 350;
+  font-weight: lighter;
+  font-size: 0.95em;
+}
+
+.reveal h4 {
+  color: $accent2;
+  // font-weight: 350;
+  font-weight: normal;
+  margin-top: 1.25em;
+}
+
+// alerts etc.
+
+.alert {
+  color: $accent2;
+}
+
+.fg {
+  color: var(--col, $jet);
+}
+
+.bg {
+  background-color: var(--col, #fff);
+  padding: 0.1em;
+  border-radius: 5px;
+  display: inline-block;
+}
+
+// lists
+
+// Unordered lists
+
+.reveal ul {
+  // font-weight: 300;
+  font-weight: lighter;
+  padding-left: 16px;
+
+  li::marker {
+    color: mix($accent, white, 70%);
+  }
+}
+
+.reveal ul ul {
+  list-style: none;
+
+  li:before {
+    content: $right-arrow;
+    color: mix($accent, white, 60%);
+    display: inline-block;
+    width: 1em;
+    margin-left: -1em;
+    margin-right: 0.5em;
+  }
+}
+
+// Ordered lists
+
+.reveal ol {
+  // font-weight: 300;
+  font-weight: lighter;
+  padding-left: 16px;
+
+  li::marker {
+    color: $accent;
+  }
+}
+
+// Move "hamburger" menu button to top right
+
+.reveal .slide-menu-button {
+  position: fixed;
+  top: 6px;
+  right: 0;
+  display: flex;
+  justify-content: flex-end;
+  align-items: flex-start;
+  pointer-events: none;
+}
+
+.reveal .slide-menu-button > * {
+  pointer-events: auto;
+}
+
+// Same for chalkboard buttons (with an offset)
+
+.reveal .slide-chalkboard-buttons {
+  position: fixed;
+  top: 12px;
+  right: 24px;
+  display: flex;
+  justify-content: flex-end;
+  align-items: flex-start;
+  pointer-events: none;
+}
+
+.reveal .slide-chalkboard-buttons > * {
+  pointer-events: auto;
+}
+
+// Logo to the bottom-left
+.slide-logo {
+  display: block !important;
+  position: fixed !important;
+  bottom: 0 !important;
+  left: 10px !important;
+  max-width: 150px; // Adjust if necessary
+  max-height: 50px;
+  width: auto !important;
+  color: $body-color !important;
+}
+
+// Also need to enforce slide numbers at bottom-right (if logo is present)
+.slide-number, .reveal.has-logo .slide-number {
+  bottom: 6px !important;
+  right: 10px !important;
+  top: unset !important;
+  color: #777777 !important;
+}
+
+// Beamer-style button link environment
+
+.button {
+  display: inline-block;
+  padding: 6px 12px;
+  margin-bottom: 0;
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 1.42857143;
+  text-align: center;
+  white-space: nowrap;
+  vertical-align: middle;
+  cursor: pointer;
+  background-color: $accent;
+  border: 1px solid $accent;
+  color: #fff !important;
+  text-decoration: none;
+  border-radius: 4px;
+  transition: all 0.2s ease-in-out;
+}
+
+.button:hover {
+  background-color: #0056b3;
+  border-color: #0056b3;
+}
+
+.button::before {
+  content: "▶";
+  margin-right: 5px;
+}
+
+// tables
+
+.reveal table {
+  // height: auto; /* Adjust table width to fit content up to the available slide space */
+  margin: auto;
+  border-collapse: collapse;
+  border-spacing: 0;
+  font-size: 0.8em;
+}
+
+.reveal table th,
+.reveal table td {
+  border: none; /* Remove internal row lines */
+  padding: .23em; /* Adjust padding as needed */
+  text-align: left; /* Adjust text alignment as needed */
+  font-weight: lighter; /* Lighter font weight for main table text */
+}
+
+/* Adds a bottom border to the table header row for distinction */
+.reveal table thead th,
+.reveal .slides table tr:last-child td,
+.reveal .slides table {
+  border-bottom: 2px solid #D3D3D3; /* Dark grey color for the bottom border */
+}
+
+/* Make column headers bold */
+.reveal table thead th {
+  font-weight: bold;
+}
+
+/* Styling table captions */
+.reveal table caption {
+  color: #666666; /* Dark grey color for the caption */
+  font-variant: small-caps; /* Use small caps for the caption text */
+}
+
+// Special catch for etable environment to ensure these table images
+// don't overflow the slide.
+// See: https://lrberge.github.io/fixest/articles/etable_new_features.html
+
+.etable {
+  width: 100%;
+  height: calc(100% - 3em); /* Adjust 3em based on the height of your header, if necessary */
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.etable img {
+  max-width: 100%;
+  max-height: 100%;
+  width: auto;
+  height: auto;
+  object-fit: contain;
+}
+
+// Change the relative widths of `output-location: column`. 
+// See: https://github.com/grantmcdermott/quarto-revealjs-clean/pull/16
+// Example usage:
+// ```{python}
+// #| echo: true
+// #| output-location: column
+// #| classes: columns3070
+// <code>
+// ```
+.reveal .columns3070 > div.column:first-child {
+  width: 30%;
+}
+.reveal .columns3070 div.column:not(:first-child) {
+  width: 70%;
+}
+.reveal .columns7030 > div.column:first-child {
+  width: 70%;
+}
+.reveal .columns7030 div.column:not(:first-child) {
+  width: 30%;
+}
+.reveal .columns4060 > div.column:first-child {
+  width: 40%;
+}
+.reveal .columns4060 div.column:not(:first-child) {
+  width: 60%;
+}      
+.reveal .columns6040 > div.column:first-child {
+  width: 60%;
+}
+.reveal .columns6040 div.column:not(:first-child) {
+  width: 40%;
+}      

src/_extensions/grantmcdermott/clean/mathjax-config.js

@@ -0,0 +1,18 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [['\\(', '\\)']],
+    displayMath: [['\\[', '\\]']],
+    processEscapes: true,
+    processRefs: true,
+    processEnvironments: true
+  },
+  chtml: {
+    font: 'mathjax-asana'
+  },
+  startup: {
+    ready: () => {
+      console.log('MathJax is loaded and ready with font: mathjax-asana (Asana Math)');
+      MathJax.startup.defaultReady();
+    }
+  }
+};

src/_extensions/pandoc-ext/diagram/_extension.yaml

@@ -0,0 +1,7 @@
+title: diagram
+author: Albert Krewinkel
+version: 1.2.0
+quarto-required: ">=1.3"
+contributes:
+  filters:
+    - diagram.lua

src/_extensions/pandoc-ext/diagram/diagram.lua

@@ -0,0 +1,660 @@
+--[[
+diagram – create images and figures from code blocks.
+
+See copyright notice in file LICENSE.
+]]
+-- The filter uses the Figure AST element, which was added in pandoc 3.
+PANDOC_VERSION:must_be_at_least '3.0'
+
+local version = pandoc.types.Version '1.2.0'
+
+-- Report Lua warnings to stderr if the `warn` function is not plugged into
+-- pandoc's logging system.
+if not warn then
+  -- fallback
+  warn = function(...) io.stderr:write(table.concat({ ... })) end
+elseif PANDOC_VERSION < '3.1.4' then
+  -- starting with pandoc 3.1.4, warnings are reported to pandoc's logging
+  -- system, so no need to print warnings to stderr.
+  warn '@on'
+end
+
+local io = require 'io'
+local pandoc = require 'pandoc'
+local system = require 'pandoc.system'
+local utils  = require 'pandoc.utils'
+local List   = require 'pandoc.List'
+local stringify = utils.stringify
+local with_temporary_directory = system.with_temporary_directory
+local with_working_directory = system.with_working_directory
+
+--- Returns a filter-specific directory in which cache files can be
+--- stored, or nil if no such directory is available.
+local function cachedir ()
+  local cache_home = os.getenv 'XDG_CACHE_HOME'
+  if not cache_home or cache_home == '' then
+    local user_home = system.os == 'windows'
+      and os.getenv 'USERPROFILE'
+      or os.getenv 'HOME'
+
+    if not user_home or user_home == '' then
+      return nil
+    end
+    cache_home = pandoc.path.join{user_home, '.cache'} or nil
+  end
+
+  -- Create filter cache directory
+  return pandoc.path.join{cache_home, 'pandoc-diagram-filter'}
+end
+
+--- Path holding the image cache, or `nil` if the cache is not used.
+local image_cache = nil
+
+local mimetype_for_extension = {
+  jpeg = 'image/jpeg',
+  jpg = 'image/jpeg',
+  pdf = 'application/pdf',
+  png = 'image/png',
+  svg = 'image/svg+xml',
+}
+
+local extension_for_mimetype = {
+  ['application/pdf'] = 'pdf',
+  ['image/jpeg'] = 'jpg',
+  ['image/png'] = 'png',
+  ['image/svg+xml'] = 'svg',
+}
+
+--- Converts a list of format specifiers to a set of MIME types.
+local function mime_types_set (tbl)
+  local set = {}
+  local mime_type
+  for _, image_format_spec in ipairs(tbl) do
+    mime_type = mimetype_for_extension[image_format_spec] or image_format_spec
+    set[mime_type] = true
+  end
+  return set
+end
+
+--- Reads the contents of a file.
+local function read_file (filepath)
+  local fh = io.open(filepath, 'rb')
+  local contents = fh:read('a')
+  fh:close()
+  return contents
+end
+
+--- Writes the contents into a file at the given path.
+local function write_file (filepath, content)
+  local fh = io.open(filepath, 'wb')
+  fh:write(content)
+  fh:close()
+end
+
+--- Like `pandoc.pipe`, but allows "multi word" paths:
+-- Supplying a list as the first argument will use the first element as
+-- the executable path and prepend the remaining elements to the list of
+-- arguments.
+local function pipe (command, args, input)
+  local cmd
+  if pandoc.utils.type(command) == 'List' then
+    command = command:map(stringify)
+    cmd = command:remove(1)
+    args = command .. args
+  else
+    cmd = stringify(command)
+  end
+  return pandoc.pipe(cmd, args, input)
+end
+
+
+--
+-- Diagram Engines
+--
+
+-- PlantUML engine; assumes that there's a `plantuml` binary.
+local plantuml = {
+  line_comment_start =  [[']],
+  mime_types = mime_types_set{'pdf', 'png', 'svg'},
+  compile = function (self, puml)
+    local mime_type = self.mime_type or 'image/svg+xml'
+    -- PlantUML format identifiers correspond to common file extensions.
+    local format = extension_for_mimetype[mime_type]
+    if not format then
+      format, mime_type = 'svg', 'image/svg+xml'
+    end
+    local args = {'-t' .. format, "-pipe", "-charset", "UTF8"}
+    return pipe(self.execpath or 'plantuml', args, puml), mime_type
+  end,
+}
+
+--- GraphViz engine for the dot language
+local graphviz = {
+  line_comment_start = '//',
+  mime_types = mime_types_set{'jpg', 'pdf', 'png', 'svg'},
+  mime_type = 'image/svg+xml',
+  compile = function (self, code)
+    local mime_type = self.mime_type
+    -- GraphViz format identifiers correspond to common file extensions.
+    local format = extension_for_mimetype[mime_type]
+    if not format then
+      format, mime_type = 'svg', 'image/svg+xml'
+    end
+    return pipe(self.execpath or 'dot', {"-T"..format}, code), mime_type
+  end,
+}
+
+--- Mermaid engine
+local mermaid = {
+  line_comment_start = '%%',
+  mime_types = mime_types_set{'pdf', 'png', 'svg'},
+  compile = function (self, code)
+    local mime_type = self.mime_type or 'image/svg+xml'
+    local file_extension = extension_for_mimetype[mime_type]
+    return with_temporary_directory("diagram", function (tmpdir)
+      return with_working_directory(tmpdir, function ()
+        local infile = 'diagram.mmd'
+        local outfile = 'diagram.' .. file_extension
+        write_file(infile, code)
+        pipe(
+          self.execpath or 'mmdc',
+          {"--pdfFit", "--input", infile, "--output", outfile},
+          ''
+        )
+        return read_file(outfile), mime_type
+      end)
+    end)
+  end,
+}
+
+--- TikZ
+--
+
+--- LaTeX template used to compile TikZ images.
+local tikz_template = pandoc.template.compile [[
+\documentclass{standalone}
+\usepackage{tikz}
+$for(header-includes)$
+$it$
+$endfor$
+$additional-packages$
+\begin{document}
+$body$
+\end{document}
+]]
+
+--- The TikZ engine uses pdflatex to compile TikZ code to an image
+local tikz = {
+  line_comment_start = '%%',
+
+  mime_types = {
+    ['application/pdf'] = true,
+  },
+
+  --- Compile LaTeX with TikZ code to an image
+  compile = function (self, src, user_opts)
+    return with_temporary_directory("tikz", function (tmpdir)
+      return with_working_directory(tmpdir, function ()
+        -- Define file names:
+        local file_template = "%s/tikz-image.%s"
+        local tikz_file = file_template:format(tmpdir, "tex")
+        local pdf_file = file_template:format(tmpdir, "pdf")
+
+        -- Treat string values as raw LaTeX
+        local meta = {
+          ['header-includes'] = user_opts['header-includes'],
+          ['additional-packages'] = {pandoc.RawInline(
+            'latex',
+            stringify(user_opts['additional-packages'] or '')
+          )},
+        }
+        local tex_code = pandoc.write(
+          pandoc.Pandoc({pandoc.RawBlock('latex', src)}, meta),
+          'latex',
+          {template = tikz_template}
+        )
+        write_file(tikz_file, tex_code)
+
+        -- Execute the LaTeX compiler:
+        local success, result = pcall(
+          pipe,
+          self.execpath or 'pdflatex',
+          { '-interaction=nonstopmode', '-output-directory', tmpdir, tikz_file },
+          ''
+        )
+        if not success then
+          warn(string.format(
+                 "The call\n%s\nfailed with error code %s. Output:\n%s",
+                 result.command,
+                 result.error_code,
+                 result.output
+          ))
+        end
+        return read_file(pdf_file), 'application/pdf'
+      end)
+    end)
+  end
+}
+
+--- Asymptote diagram engine
+local asymptote = {
+  line_comment_start = '%%',
+  mime_types = {
+    ['application/pdf'] = true,
+  },
+  compile = function (self, code)
+    return with_temporary_directory("asymptote", function(tmpdir)
+      return with_working_directory(tmpdir, function ()
+        local pdf_file = "pandoc_diagram.pdf"
+        local args = {'-tex', 'pdflatex', "-o", "pandoc_diagram", '-'}
+        pipe(self.execpath or 'asy', args, code)
+        return read_file(pdf_file), 'application/pdf'
+      end)
+    end)
+  end,
+}
+
+--- Cetz diagram engine
+local cetz = {
+  line_comment_start = '%%',
+  mime_types = mime_types_set{'jpg', 'pdf', 'png', 'svg'},
+  mime_type = 'image/svg+xml',
+  compile = function (self, code)
+    local mime_type = self.mime_type
+    local format = extension_for_mimetype[mime_type]
+    if not format then
+      format, mime_type = 'svg', 'image/svg+xml'
+    end
+    local preamble = [[
+#import "@preview/cetz:0.3.4"
+#set page(width: auto, height: auto, margin: .5cm)
+]]
+
+    local typst_code = preamble .. code
+
+    return with_temporary_directory("diagram", function (tmpdir)
+      return with_working_directory(tmpdir, function ()
+        local outfile = 'diagram.' .. format
+        local execpath = self.execpath
+        if not execpath and quarto and quarto.version >= '1.4' then
+          -- fall back to the Typst exec shipped with Quarto.
+          execpath = List{'quarto', 'typst'}
+        end
+        pipe(
+          execpath or 'typst',
+          {"compile", "-f", format, "-", outfile},
+          typst_code
+        )
+        return read_file(outfile), mime_type
+      end)
+    end)
+  end,
+}
+
+--- D2 engine for the D2 language
+local d2 = {
+  line_comment_start = '#',
+  mime_types = mime_types_set{'png', 'svg'},
+
+  compile = function (self, code, user_opts)
+    return with_temporary_directory('diagram', function (tmpdir)
+      return with_working_directory(tmpdir, function ()
+        -- D2 format identifiers correspond to common file extensions.
+        local mime_type = self.mime_type or 'image/svg+xml'
+        local file_extension = extension_for_mimetype[mime_type]
+        local infile = 'diagram.d2'
+        local outfile = 'diagram.' .. file_extension
+
+        args = {'--bundle', '--pad=0', '--scale=1'}
+
+        d2_user_opts = {
+          'layout',
+        }
+        for _, d2_user_opt in pairs(d2_user_opts) do
+          if user_opts[d2_user_opt] then
+            table.insert(args, '--' .. d2_user_opt .. '=' .. user_opts[d2_user_opt])
+          end
+        end
+
+        table.insert(args, infile)
+        table.insert(args, outfile)
+
+        write_file(infile, code)
+
+        pipe(self.execpath or 'd2', args, '')
+
+        return read_file(outfile), mime_type
+      end)
+    end)
+  end,
+}
+
+local default_engines = {
+  asymptote = asymptote,
+  dot       = graphviz,
+  mermaid   = mermaid,
+  plantuml  = plantuml,
+  tikz      = tikz,
+  cetz      = cetz,
+  d2        = d2,
+}
+
+--
+-- Configuration
+--
+
+--- Options for the output format of the given name.
+local function format_options (name)
+  local pdf2svg = name ~= 'latex' and name ~= 'context'
+  local is_office_format = name == 'docx' or name == 'odt'
+  -- Office formats seem to work better with PNG than with SVG.
+  local preferred_mime_types = is_office_format
+    and pandoc.List{'image/png', 'application/pdf'}
+    or  pandoc.List{'application/pdf', 'image/png'}
+  -- Prefer SVG for non-PDF output formats, except for Office formats
+  if is_office_format then
+    preferred_mime_types:insert('image/svg+xml')
+  elseif pdf2svg then
+    preferred_mime_types:insert(1, 'image/svg+xml')
+  end
+  return {
+    name = name,
+    pdf2svg = pdf2svg,
+    preferred_mime_types = preferred_mime_types,
+    best_mime_type = function (self, supported_mime_types, requested)
+      return self.preferred_mime_types:find_if(function (preferred)
+          return supported_mime_types[preferred] and
+            (not requested or
+             (pandoc.utils.type(requested) == 'List' and
+              requested:includes(preferred)) or
+             (pandoc.utils.type(requested) == 'table' and
+              requested[preferred]) or
+
+             -- Assume string, Inlines, and Blocks values specify the only
+             -- acceptable MIME type.
+             stringify(requested) == preferred)
+      end)
+    end
+  }
+end
+
+--- Returns a configured diagram engine.
+local function get_engine (name, engopts, format)
+  local engine = default_engines[name] or
+    select(2, pcall(require, stringify(engopts.package)))
+
+  -- Sanity check
+  if not engine then
+    warn(PANDOC_SCRIPT_FILE, ": No such engine '", name, "'.")
+    return nil
+  elseif engopts == false then
+    -- engine is disabled
+    return nil
+  elseif engopts == true then
+    -- use default options
+    return engine
+  end
+
+  local execpath = engopts.execpath or os.getenv(name:upper() .. '_BIN')
+
+  local mime_type = format:best_mime_type(
+    engine.mime_types,
+    engopts['mime-type'] or engopts['mime-types']
+  )
+  if not mime_type then
+    warn(PANDOC_SCRIPT_FILE, ": Cannot use ", name, " with ", format.name)
+    return nil
+  end
+
+  return {
+    execpath = execpath,
+    compile = engine.compile,
+    line_comment_start = engine.line_comment_start,
+    mime_type = mime_type,
+    opt = engopts or {},
+  }
+end
+
+--- Returns the diagram engine configs.
+local function configure (meta, format_name)
+  local conf = meta.diagram or {}
+  local format = format_options(format_name)
+  meta.diagram = nil
+
+  -- cache for image files
+  if conf.cache then
+    image_cache = conf['cache-dir']
+      and stringify(conf['cache-dir'])
+      or cachedir()
+    pandoc.system.make_directory(image_cache, true)
+  end
+
+  -- engine configs
+  local engine = {}
+  for name, engopts in pairs(conf.engine or default_engines) do
+    engine[name] = get_engine(name, engopts, format)
+  end
+
+  return {
+    engine = engine,
+    format = format,
+    cache = image_cache and true,
+    image_cache = image_cache,
+  }
+end
+
+--
+-- Format conversion
+--
+
+--- Converts a PDF to SVG.
+local pdf2svg = function (imgdata)
+  -- Using `os.tmpname()` instead of a hash would be slightly cleaner, but the
+  -- function causes problems on Windows (and wasm). See, e.g.,
+  -- https://github.com/pandoc-ext/diagram/issues/49
+  local pdf_file = 'diagram-' .. pandoc.utils.sha1(imgdata) .. '.pdf'
+  write_file(pdf_file, imgdata)
+  local args = {
+    '--export-type=svg',
+    '--export-plain-svg',
+    '--export-filename=-',
+    pdf_file
+  }
+  return pandoc.pipe('inkscape', args, ''), os.remove(pdf_file)
+end
+
+local function properties_from_code (code, comment_start)
+  local props = {}
+  local pattern = comment_start:gsub('%p', '%%%1') .. '| ' ..
+    '([-_%w]+): ([^\n]*)\n'
+  for key, value in code:gmatch(pattern) do
+    if key == 'fig-cap' then
+      props['caption'] = value
+    else
+      props[key] = value
+    end
+  end
+  return props
+end
+
+local function diagram_options (cb, comment_start)
+  local attribs = comment_start
+    and properties_from_code(cb.text, comment_start)
+    or {}
+  for key, value in pairs(cb.attributes) do
+    attribs[key] = value
+  end
+
+  local alt
+  local caption
+  local fig_attr = {id = cb.identifier}
+  local filename
+  local image_attr = {}
+  local user_opt = {}
+
+  for attr_name, value in pairs(attribs) do
+    if attr_name == 'alt' then
+      alt = value
+    elseif attr_name == 'caption' then
+      -- Read caption attribute as Markdown
+      caption = attribs.caption
+        and pandoc.read(attribs.caption).blocks
+        or nil
+    elseif attr_name == 'filename' then
+      filename = value
+    elseif attr_name == 'label' then
+      fig_attr.id = value
+    elseif attr_name == 'name' then
+      fig_attr.name = value
+    else
+      -- Check for prefixed attributes
+      local prefix, key = attr_name:match '^(%a+)%-(%a[-%w]*)$'
+      if prefix == 'fig' then
+        fig_attr[key] = value
+      elseif prefix == 'image' or prefix == 'img' then
+        image_attr[key] = value
+      elseif prefix == 'opt' then
+        user_opt[key] = value
+      else
+        -- Use as image attribute
+        image_attr[attr_name] = value
+      end
+    end
+  end
+
+  return {
+    ['alt'] = alt or
+      (caption and pandoc.utils.blocks_to_inlines(caption)) or
+      {},
+    ['caption'] = caption,
+    ['fig-attr'] = fig_attr,
+    ['filename'] = filename,
+    ['image-attr'] = image_attr,
+    ['opt'] = user_opt,
+  }
+end
+
+local function get_cached_image (hash, mime_type)
+  if not image_cache then
+    return nil
+  end
+  local filename = hash .. '.' .. extension_for_mimetype[mime_type]
+  local imgpath = pandoc.path.join{image_cache, filename}
+  local success, imgdata = pcall(read_file, imgpath)
+  if success then
+    return imgdata, mime_type
+  end
+  return nil
+end
+
+local function cache_image (codeblock, imgdata, mimetype)
+  -- do nothing if caching is disabled or not possible.
+  if not image_cache then
+    return
+  end
+  local ext = extension_for_mimetype[mimetype]
+  local filename = pandoc.sha1(codeblock.text) .. '.' .. ext
+  local imgpath = pandoc.path.join{image_cache, filename}
+  write_file(imgpath, imgdata)
+end
+
+-- Executes each document's code block to find matching code blocks:
+local function code_to_figure (conf)
+  return function (block)
+    -- Check if a converter exists for this block. If not, return the block
+    -- unchanged.
+    local diagram_type = block.classes[1]
+    if not diagram_type then
+      return nil
+    end
+
+    local engine = conf.engine[diagram_type]
+    if not engine then
+      return nil
+    end
+
+    -- Unified properties.
+    local dgr_opt = diagram_options(block, engine.line_comment_start)
+    for optname, value in pairs(engine.opt or {}) do
+      dgr_opt.opt[optname] = dgr_opt.opt[optname] or value
+    end
+
+    local run_pdf2svg = engine.mime_type == 'application/pdf'
+      and conf.format.pdf2svg
+
+    -- Try to retrieve the image data from the cache.
+    local imgdata, imgtype
+    if conf.cache then
+      imgdata, imgtype = get_cached_image(
+        pandoc.sha1(block.text),
+        run_pdf2svg and 'image/svg+xml' or engine.mime_type
+      )
+    end
+
+    if not imgdata or not imgtype then
+      -- No cached image; call the converter
+      local success
+      success, imgdata, imgtype =
+        pcall(engine.compile, engine, block.text, dgr_opt.opt)
+
+      -- Bail if an error occurred; imgdata contains the error message
+      -- when that happens.
+      if not success then
+        warn(PANDOC_SCRIPT_FILE, ': ', tostring(imgdata))
+        return nil
+      elseif not imgdata then
+        warn(PANDOC_SCRIPT_FILE, ': Diagram engine returned no image data.')
+        return nil
+      elseif not imgtype then
+        warn(PANDOC_SCRIPT_FILE, ': Diagram engine did not return a MIME type.')
+        return nil
+      end
+
+      -- Convert SVG if necessary.
+      if imgtype == 'application/pdf' and conf.format.pdf2svg then
+        imgdata, imgtype = pdf2svg(imgdata), 'image/svg+xml'
+      end
+
+      -- If we got here, then the transformation went ok and `img` contains
+      -- the image data.
+      cache_image(block, imgdata, imgtype)
+    end
+
+    -- Use the block's filename attribute or create a new name by hashing the
+    -- image content.
+    local basename, _extension = pandoc.path.split_extension(
+      dgr_opt.filename or pandoc.sha1(imgdata)
+    )
+    local fname = basename .. '.' .. extension_for_mimetype[imgtype]
+
+    -- Store the data in the media bag:
+    pandoc.mediabag.insert(fname, imgtype, imgdata)
+
+    -- Create the image object.
+    local image = pandoc.Image(dgr_opt.alt, fname, "", dgr_opt['image-attr'])
+
+    -- Create a figure if the diagram has a caption; otherwise return
+    -- just the image.
+    return dgr_opt.caption and
+      pandoc.Figure(
+        pandoc.Plain{image},
+        dgr_opt.caption,
+        dgr_opt['fig-attr']
+      ) or
+      pandoc.Plain{image}
+  end
+end
+
+return setmetatable(
+  {{
+    Pandoc = function (doc)
+      local conf = configure(doc.meta, FORMAT)
+      return doc:walk {
+        CodeBlock = code_to_figure(conf),
+      }
+    end
+  }},
+  {
+    version = version,
+  }
+)

src/_quarto.yml

@@ -1,34 +1,83 @@
 project:
   type: website
+
 website:
-  title: "Open-Source AI Cookbook"
+  title: "Kashi Coding Handbook"
+  navbar:
+    left:
+      - text: "Home"
+        href: index.qmd
+      - text: "Foundation Setup"
+        menu:
+          - chapters/ch01-development-environment.qmd
+          - chapters/ch01-project-structure.qmd
+      - text: "CLI Development"
+        menu:
+          - chapters/ch02-building-with-typer.qmd
+          - chapters/ch02-configuration-management.qmd
+      - text: "AI Integration"
+        menu:
+          - chapters/ch03-huggingface-llm-apis.qmd
+          - chapters/ch03-docker-model-deployment.qmd
+          - chapters/ch03-mcp-toolkit.qmd
+          - chapters/ch03-prompt-engineering.qmd
+      - text: "Advanced Features"
+        menu:
+          - chapters/ch04-interactive-elements.qmd
+          - chapters/ch04-batch-processing.qmd
+      - text: "Testing & Quality"
+        menu:
+          - chapters/ch05-writing-tests.qmd
+          - chapters/ch05-code-quality.qmd
+      - text: "Publishing"
+        menu:
+          - chapters/ch06-package-preparation.qmd
+          - chapters/ch06-building-publishing.qmd
+      - text: "Projects"
+        menu:
+          - chapters/ch07-fileorganizer-project.qmd
+      - text: "Appendices"
+        menu:
+          - chapters/appendix-pixi-commands.qmd
+          - chapters/appendix-learning-resources.qmd
   sidebar:
-    style: "docked"
-    search: true
-    collapse-level: 3
-    contents:
-      - section: "About"
-        contents:
-          - href: index.qmd
-            text: About Quarto
-      - section: "Open-Source AI Cookbook"
-        contents:
-        - section: "RAG Techniques"
-          contents:
-            - href: notebooks/rag_zephyr_langchain.qmd
-              text: "RAG Zephyr & LangChain"
-            - href: notebooks/advanced_rag.qmd
-              text: "Advanced RAG"
-            - href: notebooks/rag_evaluation.qmd
-              text: "RAG Evaluation"
-        - section: "Additional Techniques"
-          contents:
-            - href: notebooks/automatic_embedding.ipynb
-              text: "Automatic Embedding"
-            - href: notebooks/faiss.ipynb
-              text: "FAISS for Efficient Search"
-            - href: notebooks/single_gpu.ipynb
-              text: "Single GPU Optimization"
+    - title: "Kashi Coding Handbook"
+      subtitle: "Building AI-Powered CLI Tools with Python"
+      contents:
+        - index.qmd
+        - section: "Chapter 1: Foundation Setup"
+          contents:
+            - chapters/ch01-development-environment.qmd
+            - chapters/ch01-project-structure.qmd
+        - section: "Chapter 2: CLI Development"
+          contents:
+            - chapters/ch02-building-with-typer.qmd
+            - chapters/ch02-configuration-management.qmd
+        - section: "Chapter 3: AI Integration"
+          contents:
+            - chapters/ch03-huggingface-llm-apis.qmd
+            - chapters/ch03-docker-model-deployment.qmd
+            - chapters/ch03-mcp-toolkit.qmd
+            - chapters/ch03-prompt-engineering.qmd
+        - section: "Chapter 4: Advanced Features"
+          contents:
+            - chapters/ch04-interactive-elements.qmd
+            - chapters/ch04-batch-processing.qmd
+        - section: "Chapter 5: Testing & Quality"
+          contents:
+            - chapters/ch05-writing-tests.qmd
+            - chapters/ch05-code-quality.qmd
+        - section: "Chapter 6: Publishing"
+          contents:
+            - chapters/ch06-package-preparation.qmd
+            - chapters/ch06-building-publishing.qmd
+        - section: "Chapter 7: Real-World Projects"
+          contents:
+            - chapters/ch07-fileorganizer-project.qmd
+        - section: "Appendices"
+          contents:
+            - chapters/appendix-pixi-commands.qmd
+            - chapters/appendix-learning-resources.qmd
 
 format:
   html:

src/chapters/appendix-learning-resources.qmd

@@ -0,0 +1,16 @@
+# Learning Resources
+
+## Coming Soon
+
+This chapter is currently being developed. Content will be extracted from the learning path document.
+
+## Topics Covered
+
+- Topic 1
+- Topic 2
+- Topic 3
+
+## Resources
+
+- [Resource 1](#)
+- [Resource 2](#)

src/chapters/appendix-pixi-commands.qmd

@@ -0,0 +1,16 @@
+# Pixi Commands
+
+## Coming Soon
+
+This chapter is currently being developed. Content will be extracted from the learning path document.
+
+## Topics Covered
+
+- Topic 1
+- Topic 2
+- Topic 3
+
+## Resources
+
+- [Resource 1](#)
+- [Resource 2](#)

src/chapters/ch01-development-environment.qmd

@@ -0,0 +1,191 @@
+# Development Environment Setup
+
+## Learning Objectives
+
+By the end of this section, you will be able to:
+
+- Install and configure pixi for Python package management
+- Set up GitHub Copilot for AI-assisted development
+- Configure VS Code or your preferred IDE for Python development
+- Verify your development environment is working correctly
+
+## Installing Pixi
+
+Pixi is a modern, cross-platform package manager that simplifies Python project management and dependency handling.
+
+### Installation
+
+```bash
+# Install pixi (works on Linux, macOS, and Windows)
+curl -fsSL https://pixi.sh/install.sh | bash
+
+# Verify installation
+pixi --version
+```
+
+### Why Pixi?
+
+- **Fast**: Uses conda packages with parallel downloads
+- **Reproducible**: Lock files ensure consistent environments
+- **Cross-platform**: Works identically on all operating systems
+- **Modern**: Built with Rust for performance and reliability
+
+## Setting Up GitHub Copilot
+
+GitHub Copilot is an AI pair programmer that helps you write code faster and with fewer errors.
+
+### Prerequisites
+
+- GitHub account with Copilot subscription (free for students and open-source maintainers)
+- VS Code or compatible IDE
+
+### Installation Steps
+
+1. **Install VS Code** (if not already installed)
+   - Download from [code.visualstudio.com](https://code.visualstudio.com/)
+
+2. **Install GitHub Copilot Extension**
+   - Open VS Code
+   - Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
+   - Search for "GitHub Copilot"
+   - Click Install
+
+3. **Sign In**
+   - Click "Sign in to GitHub" when prompted
+   - Authorize VS Code to access your GitHub account
+   - Complete the authentication flow
+
+4. **Verify Setup**
+   - Create a new Python file
+   - Start typing a function definition
+   - You should see gray suggestions from Copilot
+
+### Copilot Best Practices
+
+- **Write clear comments**: Copilot uses comments to understand your intent
+- **Use descriptive names**: Function and variable names guide suggestions
+- **Review suggestions**: Always review and understand generated code
+- **Iterate**: If the first suggestion isn't right, try rephrasing your comment
+
+## Installing Git
+
+Git is essential for version control and collaboration.
+
+```bash
+# Linux (Debian/Ubuntu)
+sudo apt install git
+
+# macOS (with Homebrew)
+brew install git
+
+# Windows
+# Download from git-scm.com
+```
+
+Verify installation:
+
+```bash
+git --version
+```
+
+## IDE Configuration
+
+### VS Code Extensions
+
+Install these recommended extensions:
+
+- **Python** (Microsoft) - Python language support
+- **GitHub Copilot** - AI pair programmer
+- **Pylance** - Fast Python language server
+- **Ruff** - Fast Python linter
+- **GitLens** - Enhanced Git capabilities
+
+### VS Code Settings
+
+Create or update `.vscode/settings.json` in your project:
+
+```json
+{
+  "python.linting.enabled": true,
+  "python.linting.ruffEnabled": true,
+  "python.formatting.provider": "black",
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": true
+  },
+  "github.copilot.enable": {
+    "*": true,
+    "python": true
+  }
+}
+```
+
+## Verification
+
+Let's verify everything is working:
+
+```bash
+# Check pixi
+pixi --version
+
+# Check Git
+git --version
+
+# Check Python (via pixi)
+pixi run python --version
+```
+
+## Creating Your First Pixi Project
+
+```bash
+# Create a new directory
+mkdir my-first-cli
+cd my-first-cli
+
+# Initialize pixi project
+pixi init
+
+# Add Python
+pixi add python
+
+# Create a simple script
+mkdir src
+echo 'print("Hello from Kashi Coding Handbook!")' > src/hello.py
+
+# Run it
+pixi run python src/hello.py
+```
+
+You should see: `Hello from Kashi Coding Handbook!`
+
+## Troubleshooting
+
+### Pixi not found after installation
+
+- **Linux/macOS**: Add pixi to your PATH by restarting your terminal or running:
+  ```bash
+  source ~/.bashrc  # or ~/.zshrc
+  ```
+
+- **Windows**: Restart your terminal or add pixi to your system PATH
+
+### Copilot not showing suggestions
+
+- Verify you're signed in to GitHub in VS Code
+- Check that Copilot is enabled in VS Code settings
+- Try reloading VS Code (Ctrl+Shift+P → "Reload Window")
+
+### Permission errors with pixi
+
+- Don't use `sudo` with pixi
+- Ensure you have write permissions in your home directory
+
+## Next Steps
+
+Now that your development environment is set up, proceed to the next section to learn about modern Python project structure.
+
+## Resources
+
+- [Pixi Documentation](https://pixi.sh/latest/)
+- [GitHub Copilot Docs](https://docs.github.com/en/copilot)
+- [VS Code Python Tutorial](https://code.visualstudio.com/docs/python/python-tutorial)

src/chapters/ch01-project-structure.qmd

@@ -0,0 +1,328 @@
+# Modern Python Project Structure
+
+## Learning Objectives
+
+- Understand modern Python project layouts
+- Learn about `pyproject.toml` and `pixi.toml` configuration files
+- Set up proper directory structure for CLI applications
+- Implement version control best practices
+
+## Project Layout Options
+
+There are two main approaches to organizing Python projects:
+
+### Flat Layout
+
+```
+my-cli/
+├── my_cli/
+│   ├── __init__.py
+│   ├── cli.py
+│   └── utils.py
+├── tests/
+├── pyproject.toml
+└── README.md
+```
+
+### Src Layout (Recommended)
+
+```
+my-cli/
+├── src/
+│   └── my_cli/
+│       ├── __init__.py
+│       ├── cli.py
+│       └── utils.py
+├── tests/
+├── pyproject.toml
+├── pixi.toml
+└── README.md
+```
+
+**Why src layout?**
+- Prevents accidental imports from development directory
+- Clearer separation between source and other files
+- Better for testing and packaging
+
+## Essential Configuration Files
+
+### pyproject.toml
+
+The modern standard for Python project metadata:
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "my-cli-tool"
+version = "0.1.0"
+description = "An AI-powered CLI tool"
+authors = [{name = "Your Name", email = "you@example.com"}]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.9",
+    "rich>=13.0",
+]
+
+[project.scripts]
+my-cli = "my_cli.cli:app"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+```
+
+### pixi.toml
+
+Pixi-specific configuration for environment management:
+
+```toml
+[project]
+name = "my-cli-tool"
+version = "0.1.0"
+description = "An AI-powered CLI tool"
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-64", "win-64"]
+
+[dependencies]
+python = ">=3.11"
+typer = ">=0.9"
+rich = ">=13.0"
+
+[feature.dev.dependencies]
+pytest = "*"
+ruff = "*"
+mypy = "*"
+black = "*"
+
+[environments]
+default = []
+dev = ["dev"]
+
+[tasks]
+start = "python -m my_cli.cli"
+test = "pytest tests/"
+lint = "ruff check src/"
+format = "black src/ tests/"
+```
+
+## Complete Project Structure
+
+Here's a complete, production-ready project structure:
+
+```
+my-cli-tool/
+├── .git/                      # Git repository
+├── .gitignore                 # Git ignore rules
+├── .vscode/                   # VS Code settings
+│   └── settings.json
+├── src/
+│   └── my_cli/
+│       ├── __init__.py        # Package initialization
+│       ├── cli.py             # Main CLI entry point
+│       ├── commands/          # Command modules
+│       │   ├── __init__.py
+│       │   ├── organize.py
+│       │   └── stats.py
+│       ├── core/              # Core functionality
+│       │   ├── __init__.py
+│       │   └── processor.py
+│       └── utils/             # Utility functions
+│           ├── __init__.py
+│           └── helpers.py
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py            # Pytest configuration
+│   ├── test_cli.py
+│   └── test_core.py
+├── docs/                      # Documentation
+│   └── README.md
+├── .gitignore
+├── pyproject.toml             # Python project config
+├── pixi.toml                  # Pixi environment config
+├── pixi.lock                  # Locked dependencies
+├── LICENSE                    # License file
+└── README.md                  # Project documentation
+```
+
+## Creating the Structure
+
+Use this script to create the structure:
+
+```bash
+#!/bin/bash
+# create-project.sh
+
+PROJECT_NAME="my-cli-tool"
+PACKAGE_NAME="my_cli"
+
+# Create directories
+mkdir -p $PROJECT_NAME/{src/$PACKAGE_NAME/{commands,core,utils},tests,docs,.vscode}
+
+# Create __init__.py files
+touch $PROJECT_NAME/src/$PACKAGE_NAME/__init__.py
+touch $PROJECT_NAME/src/$PACKAGE_NAME/commands/__init__.py
+touch $PROJECT_NAME/src/$PACKAGE_NAME/core/__init__.py
+touch $PROJECT_NAME/src/$PACKAGE_NAME/utils/__init__.py
+touch $PROJECT_NAME/tests/__init__.py
+
+# Create main files
+touch $PROJECT_NAME/src/$PACKAGE_NAME/cli.py
+touch $PROJECT_NAME/README.md
+touch $PROJECT_NAME/LICENSE
+
+echo "Project structure created!"
+```
+
+Or use pixi to create it:
+
+```bash
+# Initialize with pixi
+pixi init my-cli-tool
+cd my-cli-tool
+
+# Add Python and dependencies
+pixi add python typer rich
+
+# Create src layout
+mkdir -p src/my_cli/{commands,core,utils}
+touch src/my_cli/__init__.py
+touch src/my_cli/cli.py
+
+# Create tests
+mkdir tests
+touch tests/__init__.py
+```
+
+## .gitignore
+
+Essential patterns for Python projects:
+
+```gitignore
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Pixi
+.pixi/
+pixi.lock
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+```
+
+## Version Control Setup
+
+Initialize Git and make your first commit:
+
+```bash
+# Initialize repository
+git init
+
+# Create .gitignore (use content above)
+# Use Copilot: "Generate a comprehensive .gitignore for Python projects"
+
+# Add files
+git add .
+
+# First commit
+git commit -m "Initial project structure"
+
+# Create GitHub repository (optional)
+gh repo create my-cli-tool --public --source=. --remote=origin
+git push -u origin main
+```
+
+## Package Initialization
+
+### src/my_cli/__init__.py
+
+```python
+"""My CLI Tool - An AI-powered command-line application."""
+
+__version__ = "0.1.0"
+__author__ = "Your Name"
+__email__ = "you@example.com"
+
+# Export main components
+from .cli import app
+
+__all__ = ["app"]
+```
+
+## Best Practices
+
+1. **Use src layout**: Prevents import issues and improves testing
+2. **Lock dependencies**: Commit `pixi.lock` for reproducibility
+3. **Separate concerns**: Use subdirectories for commands, core logic, and utilities
+4. **Write tests early**: Create test files alongside implementation
+5. **Document as you go**: Update README with each feature
+6. **Use type hints**: Enable better IDE support and catch errors early
+
+## Using Copilot for Project Setup
+
+Ask Copilot to help with:
+
+```python
+# In your IDE, write comments like:
+# "Create a pyproject.toml for a CLI tool with typer and rich dependencies"
+# "Generate a comprehensive .gitignore for a Python project"
+# "Create a README template for a CLI application"
+```
+
+## Next Steps
+
+With your project structure in place, you're ready to start building your CLI application. In the next chapter, we'll use Typer to create powerful command-line interfaces.
+
+## Resources
+
+- [Python Packaging Guide](https://packaging.python.org/)
+- [Pixi Project Configuration](https://pixi.sh/latest/reference/project_configuration/)
+- [PEP 518 - pyproject.toml](https://peps.python.org/pep-0518/)

src/chapters/ch02-building-with-typer.qmd

@@ -0,0 +1,416 @@
+# Building CLI Applications with Typer
+
+## Learning Objectives
+
+- Understand Typer's type-hint based approach to CLI development
+- Create commands with arguments and options
+- Implement subcommands for complex CLIs
+- Add rich formatting and user-friendly output
+- Handle errors and validation gracefully
+
+## Introduction to Typer
+
+Typer is a modern CLI framework that uses Python type hints to automatically generate command-line interfaces. It's built on top of Click but provides a more intuitive, type-safe API.
+
+### Why Typer?
+
+- **Type hints**: Uses Python's type system for automatic validation
+- **Auto-completion**: Built-in shell completion support
+- **Rich integration**: Beautiful terminal output out of the box
+- **Less boilerplate**: Minimal code for maximum functionality
+- **Great docs**: Excellent documentation and examples
+
+## Installation
+
+```bash
+pixi add typer rich
+```
+
+## Your First Typer CLI
+
+Create `src/my_cli/cli.py`:
+
+```python
+import typer
+from rich.console import Console
+
+app = typer.Typer(help="My awesome CLI tool")
+console = Console()
+
+@app.command()
+def hello(name: str = typer.Argument(..., help="Your name")):
+    """Say hello to NAME."""
+    console.print(f"[bold green]Hello {name}![/bold green]")
+
+if __name__ == "__main__":
+    app()
+```
+
+Run it:
+
+```bash
+pixi run python -m my_cli.cli hello World
+# Output: Hello World!
+```
+
+## Commands, Arguments, and Options
+
+### Arguments
+
+Required positional parameters:
+
+```python
+@app.command()
+def process(
+    filename: str = typer.Argument(..., help="File to process"),
+    output: str = typer.Argument("output.txt", help="Output file")
+):
+    """Process FILENAME and save to OUTPUT."""
+    console.print(f"Processing {filename} → {output}")
+```
+
+### Options
+
+Optional named parameters:
+
+```python
+from pathlib import Path
+
+@app.command()
+def organize(
+    directory: Path = typer.Option(
+        ".",
+        "--dir",
+        "-d",
+        help="Directory to organize",
+        exists=True,
+        file_okay=False,
+        dir_okay=True
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Preview changes without executing"
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show detailed output"
+    )
+):
+    """Organize files in DIRECTORY."""
+    if dry_run:
+        console.print("[yellow]DRY RUN MODE[/yellow]")
+    
+    if verbose:
+        console.print(f"[blue]Processing: {directory}[/blue]")
+```
+
+## Rich Output Formatting
+
+### Console Printing
+
+```python
+from rich.console import Console
+from rich.table import Table
+from rich.progress import track
+import time
+
+console = Console()
+
+@app.command()
+def stats(directory: Path):
+    """Show statistics about files."""
+    
+    # Colored output
+    console.print("[bold cyan]File Statistics[/bold cyan]")
+    
+    # Tables
+    table = Table(title="File Types")
+    table.add_column("Extension", style="cyan")
+    table.add_column("Count", justify="right", style="green")
+    
+    table.add_row(".py", "42")
+    table.add_row(".txt", "15")
+    table.add_row(".md", "8")
+    
+    console.print(table)
+    
+    # Progress bars
+    console.print("\n[bold]Processing files...[/bold]")
+    for _ in track(range(100), description="Scanning..."):
+        time.sleep(0.01)
+```
+
+## Subcommands
+
+For complex CLIs, organize commands into groups:
+
+```python
+import typer
+
+app = typer.Typer()
+
+# Create subcommand groups
+files_app = typer.Typer(help="File operations")
+config_app = typer.Typer(help="Configuration management")
+
+app.add_typer(files_app, name="files")
+app.add_typer(config_app, name="config")
+
+# File commands
+@files_app.command("organize")
+def files_organize(directory: Path):
+    """Organize files in directory."""
+    console.print(f"Organizing {directory}")
+
+@files_app.command("stats")
+def files_stats(directory: Path):
+    """Show file statistics."""
+    console.print(f"Stats for {directory}")
+
+# Config commands
+@config_app.command("show")
+def config_show():
+    """Show current configuration."""
+    console.print("Current config...")
+
+@config_app.command("set")
+def config_set(key: str, value: str):
+    """Set configuration value."""
+    console.print(f"Set {key} = {value}")
+```
+
+Usage:
+
+```bash
+my-cli files organize ./data
+my-cli files stats ./data
+my-cli config show
+my-cli config set theme dark
+```
+
+## Input Validation
+
+### Type Validation
+
+```python
+from typing import Optional
+from enum import Enum
+
+class OutputFormat(str, Enum):
+    JSON = "json"
+    YAML = "yaml"
+    TEXT = "text"
+
+@app.command()
+def export(
+    count: int = typer.Option(10, min=1, max=100),
+    format: OutputFormat = typer.Option(OutputFormat.JSON),
+    email: Optional[str] = typer.Option(None)
+):
+    """Export data in specified format."""
+    if email and "@" not in email:
+        raise typer.BadParameter("Invalid email address")
+    
+    console.print(f"Exporting {count} items as {format.value}")
+```
+
+### Custom Validation
+
+```python
+def validate_path(path: Path) -> Path:
+    """Validate that path exists and is readable."""
+    if not path.exists():
+        raise typer.BadParameter(f"Path does not exist: {path}")
+    if not path.is_dir():
+        raise typer.BadParameter(f"Path is not a directory: {path}")
+    return path
+
+@app.command()
+def process(
+    directory: Path = typer.Argument(..., callback=validate_path)
+):
+    """Process files in directory."""
+    console.print(f"Processing {directory}")
+```
+
+## Error Handling
+
+```python
+from rich.console import Console
+
+console = Console()
+
+@app.command()
+def risky_operation(filename: str):
+    """Perform a risky operation."""
+    try:
+        with open(filename) as f:
+            data = f.read()
+        console.print("[green]Success![/green]")
+    except FileNotFoundError:
+        console.print(f"[red]Error: File not found: {filename}[/red]")
+        raise typer.Exit(code=1)
+    except PermissionError:
+        console.print(f"[red]Error: Permission denied: {filename}[/red]")
+        raise typer.Exit(code=1)
+    except Exception as e:
+        console.print(f"[red]Unexpected error: {e}[/red]")
+        raise typer.Exit(code=1)
+```
+
+## Interactive Prompts
+
+```python
+@app.command()
+def delete(filename: str):
+    """Delete a file with confirmation."""
+    if not typer.confirm(f"Are you sure you want to delete {filename}?"):
+        console.print("[yellow]Cancelled[/yellow]")
+        raise typer.Abort()
+    
+    # Proceed with deletion
+    console.print(f"[red]Deleted {filename}[/red]")
+```
+
+## Complete Example: File Organizer CLI
+
+```python
+import typer
+from pathlib import Path
+from rich.console import Console
+from rich.table import Table
+from rich.progress import track
+from typing import Optional
+from enum import Enum
+
+app = typer.Typer(
+    name="file-organizer",
+    help="Organize files intelligently",
+    add_completion=True
+)
+console = Console()
+
+class Strategy(str, Enum):
+    EXTENSION = "extension"
+    DATE = "date"
+    SIZE = "size"
+
+@app.command()
+def organize(
+    directory: Path = typer.Argument(
+        ...,
+        help="Directory to organize",
+        exists=True,
+        file_okay=False,
+        dir_okay=True
+    ),
+    strategy: Strategy = typer.Option(
+        Strategy.EXTENSION,
+        "--strategy",
+        "-s",
+        help="Organization strategy"
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Preview without making changes"
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show detailed output"
+    )
+):
+    """Organize files in DIRECTORY using STRATEGY."""
+    
+    if dry_run:
+        console.print("[yellow]DRY RUN - No changes will be made[/yellow]\n")
+    
+    console.print(f"[bold cyan]Organizing {directory}[/bold cyan]")
+    console.print(f"Strategy: [green]{strategy.value}[/green]\n")
+    
+    # Scan files
+    files = list(directory.glob("*"))
+    files = [f for f in files if f.is_file()]
+    
+    if verbose:
+        console.print(f"Found {len(files)} files\n")
+    
+    # Process files
+    for file in track(files, description="Processing..."):
+        if verbose:
+            console.print(f"  Processing: {file.name}")
+    
+    console.print("\n[bold green]✓ Complete![/bold green]")
+
+@app.command()
+def stats(
+    directory: Path = typer.Argument(..., exists=True, file_okay=False)
+):
+    """Show statistics about files in DIRECTORY."""
+    
+    files = list(directory.glob("*"))
+    files = [f for f in files if f.is_file()]
+    
+    # Count by extension
+    extensions = {}
+    for file in files:
+        ext = file.suffix or "no extension"
+        extensions[ext] = extensions.get(ext, 0) + 1
+    
+    # Display table
+    table = Table(title=f"File Statistics: {directory}")
+    table.add_column("Extension", style="cyan")
+    table.add_column("Count", justify="right", style="green")
+    
+    for ext, count in sorted(extensions.items(), key=lambda x: x[1], reverse=True):
+        table.add_row(ext, str(count))
+    
+    console.print(table)
+    console.print(f"\n[bold]Total files: {len(files)}[/bold]")
+
+if __name__ == "__main__":
+    app()
+```
+
+## Testing Your CLI
+
+```python
+# tests/test_cli.py
+from typer.testing import CliRunner
+from my_cli.cli import app
+
+runner = CliRunner()
+
+def test_organize_dry_run():
+    result = runner.invoke(app, ["organize", ".", "--dry-run"])
+    assert result.exit_code == 0
+    assert "DRY RUN" in result.stdout
+
+def test_stats():
+    result = runner.invoke(app, ["stats", "."])
+    assert result.exit_code == 0
+```
+
+## Using Copilot
+
+Ask Copilot to help with:
+
+- "Create a Typer command that accepts a file path and validates it exists"
+- "Add a progress bar for processing multiple files"
+- "Generate help text and docstrings for CLI commands"
+- "Create an enum for output format options"
+
+## Next Steps
+
+Now that you can build CLIs with Typer, the next section covers configuration management for your applications.
+
+## Resources
+
+- [Typer Documentation](https://typer.tiangolo.com/)
+- [Rich Documentation](https://rich.readthedocs.io/)
+- [Typer Tutorial](https://typer.tiangolo.com/tutorial/)