chore(deps): bump vite from 7.1.7 to 7.1.11 in /docs

.ai/README-debug.md

@@ -0,0 +1,172 @@
+# SpocR Debug & Development Guide
+
+This guide explains how to efficiently debug, profile and iterate on SpocR code generation and schema pulling – independent of any specific feature (kept generic; former JSON‑specific notes were generalized).
+
+## Goals
+
+- Fast feedback loop when changing generators / schema loading
+- Deterministic rebuilds for reproducible diffs
+- Transparent diagnostics (what was pulled, what was generated, timings)
+- Foundation for future performance improvements (batch queries, caching)
+
+## Core Commands
+
+| Scenario                             | Command (example)                                                                |
+| ------------------------------------ | -------------------------------------------------------------------------------- |
+| Pull database schema only            | `dotnet run --project src/SpocR.csproj -- pull -p debug\spocr.json --verbose`    |
+| Build from existing schema in config | `dotnet run --project src/SpocR.csproj -- build -p debug\spocr.json`             |
+| Full refresh (pull + build)          | `dotnet run --project src/SpocR.csproj -- rebuild -p debug\spocr.json --verbose` |
+| Remove generated files               | `dotnet run --project src/SpocR.csproj -- remove -p debug\spocr.json`            |
+
+`--verbose` adds detailed log lines (schema + stored procedure iteration, progress etc.).
+
+## Recommended Debug Workflow
+
+1. Adjust test configuration in `debug/spocr.json` (schemas, connection string, role etc.)
+2. Run a full `rebuild` to regenerate baseline output
+3. Make code changes (parsers, generators, services)
+4. Re-run `build` (skip pull) to isolate generator effects
+5. Compare results under `debug/DataContext` using Git diff
+6. If structural DB changes occurred → run `pull` / `rebuild` again
+
+## Output Layout (Debug Folder)
+
+```
+debug/
+  spocr.json            # Project configuration (debug scope)
+  spocr.global.json     # Optional global overrides (debug)
+  DataContext/
+    Models/
+    Outputs/
+    StoredProcedures/
+    TableTypes/
+    ...
+```
+
+Generated files adopt the namespace & role configured in `spocr.json`.
+
+## Progress & Timing
+
+SpocR prints per-stage timing in the build summary:
+
+- CodeBase (template skeleton)
+- TableTypes
+- Inputs
+- Outputs
+- Models
+- StoredProcedures
+
+For large schema pulls, a progress indicator can surface total processed stored procedures vs. total. (If you need a more granular progress bar, hook into `SchemaManager` where the stored procedure loop resides.)
+
+## Extending Diagnostics
+
+| Need                       | Approach                                                             |
+| -------------------------- | -------------------------------------------------------------------- |
+| See raw SQL queries        | Add temporary logging in `DbContext` execution wrappers              |
+| Inspect parser results     | Dump `StoredProcedureContentModel` properties (guard with `verbose`) |
+| Measure query count        | Add counters in `SchemaManager` around each DB call                  |
+| Trace generation decisions | Insert `Verbose(...)` lines in generator base classes                |
+
+## Safe Experimentation Tips
+
+| Action                       | Recommendation                                                     |
+| ---------------------------- | ------------------------------------------------------------------ |
+| Prototype parsing changes    | Add a new internal method & A/B compare outputs before replacing   |
+| Large refactor of generation | Create a separate branch & snapshot baseline output first          |
+| Temporary logging            | Use `Verbose` level so normal runs stay clean                      |
+| Benchmarking                 | Run successive `build` (without `pull`) to remove DB latency noise |
+
+## Caching (Planned Generic Design)
+
+The local (non‑git) cache now lives under `.spocr/cache/` (created in the project root beside `spocr.json`). Add `.spocr/` to your `.gitignore` to avoid committing ephemeral state.
+
+Purpose: speed up repeated pulls by reusing previously parsed stored procedure metadata when unchanged. Key design points:
+
+- Location: `.spocr/cache/<fingerprint>.json`
+- Fingerprint: server + database + selected schemas (order-normalized)
+- Local cache file keyed by DB fingerprint (server + database + selected schemas)
+- Store: name, schema, last modified timestamp, definition hash, input/output signatures
+- Validate via (modify_date + hash) before skipping re-fetch
+- Flags:
+  - `--no-cache` to force refresh
+  - Future `cache clear` command
+
+## Batch Optimization (Planned)
+
+| Area        | Current                                                 | Planned Improvement                                       |
+| ----------- | ------------------------------------------------------- | --------------------------------------------------------- |
+| Definitions | One query per procedure                                 | Single bulk query joining `sys.objects + sys.sql_modules` |
+| Parameters  | Per procedure                                           | Bulk gather from `sys.parameters` filtered by object ids  |
+| Outputs     | `dm_exec_describe_first_result_set_for_object` per proc | Possibly optional / deferred (expensive to batch)         |
+
+## Common Debug Questions
+
+**Q: My generated extension methods didn’t change even after code edits.**  
+A: Ensure you ran `build` (not only `pull`). Also check you’re editing the correct generator variant (some code lives under versioned output roots).
+
+**Q: Why are some models ‘empty’ or minimal?**  
+A: When a procedure’s output columns can’t be reliably inferred, a skeleton is generated with XML documentation prompting manual extension.
+
+**Q: How do I isolate generation performance?**  
+A: Run multiple `build` commands in a row (without `pull`) and average the last timings.
+
+**Q: How can I debug only one procedure?**  
+A: (If a dedicated command exists) run a targeted stored procedure build; otherwise temporarily filter the schema list in `spocr.json` to a minimal subset.
+
+## Minimal Troubleshooting Matrix
+
+| Symptom                       | Probable Cause                      | Quick Check                                | Fix                                  |
+| ----------------------------- | ----------------------------------- | ------------------------------------------ | ------------------------------------ |
+| Missing generated files       | Wrong output root / path resolution | Look at `OutputService.GetOutputRootDir()` | Adjust path logic / framework string |
+| Repeated auto-update prompt   | Global config not honoring skip     | Inspect global file / env flags            | Extend early skip condition          |
+| Extremely slow pull           | Per-proc content fetch overhead     | Count DB calls (add counters)              | Implement batch reads / caching      |
+| Incorrect namespace in output | Role mismatch (Lib vs Default)      | Inspect generated usings                   | Adjust config role                   |
+
+## Suggested Next Enhancements (Generic)
+
+- Local metadata cache (fingerprint + hash) (IN PROGRESS; directory structure established)
+
+## Skipping Auto-Update
+
+You can disable the auto-update check in different ways:
+
+| Method          | Usage                  | Notes                                        |
+| --------------- | ---------------------- | -------------------------------------------- |
+| CLI Flag        | `--no-auto-update`     | One-off run suppression                      |
+| Quiet Mode      | `--silent`             | Also suppresses interactive prompts          |
+| Env Var         | `SPOCR_SKIP_UPDATE=1`  | Accepts: 1, true, yes, on (case-insensitive) |
+| Env Var (alias) | `SPOCR_NO_UPDATE=true` | Alias for the same behavior                  |
+
+When any of these are active the updater short-circuits before network calls.
+
+- Unified progress bar (pull + build combined view)
+- Optional diff report summarizing modified vs up-to-date files
+- Pluggable serializer / model post-processing hook
+
+## Contribution Checklist (During Debug Enhancements)
+
+- [ ] Add/update tests (snapshot or targeted)
+- [ ] Keep `spocr.json` changes minimal (avoid noise)
+- [ ] No sensitive connection strings committed
+- [ ] Document any new flags / environment variables here
+
+## Quick Command Reference
+
+```cmd
+:: Full refresh verbose
+DOTNET_ENVIRONMENT=Development dotnet run --project src/SpocR.csproj -- rebuild -p debug\spocr.json --verbose
+
+:: Build only (schema unchanged)
+dotnet run --project src/SpocR.csproj -- build -p debug\spocr.json
+
+:: Pull only
+dotnet run --project src/SpocR.csproj -- pull -p debug\spocr.json
+```
+
+## Updating This Guide
+
+When adding a new optimization (caching, batching, progress bar unification) add: goal, toggle/flag, rollback strategy.
+
+---
+
+Last update: (auto-generated base) – adapt freely as features evolve.

.ai/README-dot-spocr.md

@@ -0,0 +1,102 @@
+# The `.spocr` Directory
+
+A reserved local workspace folder for SpocR runtime and augmentation data. This directory is NOT meant to be committed and should be added to your `.gitignore`.
+
+## Current Structure
+
+```
+.spocr/
+  cache/                # JSON cache snapshots (per database fingerprint)
+```
+
+## Rationale
+
+- Keeps ephemeral & environment‑specific artifacts out of `spocr.json`
+- Allows incremental evolution without breaking existing configs
+- Provides a staging area for future separation of configuration vs. extracted schema metadata
+
+## Cache Files
+
+Each cache file lives at:
+
+```
+.spocr/cache/<fingerprint>.json
+```
+
+`<fingerprint>` is a stable string composed of:
+
+- Server (normalized)
+- Database name
+- Included schemas (sorted, comma-joined)
+
+(Exact format may evolve; treat as opaque.)
+
+Contents (conceptual model – actual implementation may lag):
+
+```jsonc
+{
+  "Fingerprint": "...",
+  "CreatedUtc": "2025-10-04T12:34:56Z",
+  "Procedures": [
+    { "Schema": "dbo", "Name": "GetUsers", "ModifiedTicks": 638000000000000000 }
+  ]
+}
+```
+
+## Planned Uses Beyond Caching
+
+| Feature Idea                  | Usage of `.spocr`                                                                                                                                                    |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Schema/config split           | Store extracted schema (procedures, tables, types) as granular JSON (e.g. `.spocr/schema/<schema>/<proc>.json`) while keeping user editable settings in `spocr.json` |
+| Diff assistance               | Maintain last two snapshot manifests to generate change reports before regeneration                                                                                  |
+| Failure diagnostics           | Persist last error context (SQL text fragments) for post-mortem without polluting stdout                                                                             |
+| Partial rebuild orchestration | Track dependency graph of generated files to enable selective regeneration                                                                                           |
+| Experimental plugins          | Drop-in extension metadata or feature toggles without altering main config                                                                                           |
+
+## .gitignore Recommendation
+
+Add (or ensure) the following lines:
+
+```
+# SpocR runtime workspace
+.spocr/
+```
+
+If granular control is desired, whitelist nothing—treat the entire directory as disposable.
+
+## Safety & Cleanup
+
+- Files are small JSON blobs; periodic manual cleanup is safe
+- A future CLI command `spocr cache clear` may automate removal
+- Corruption or deserialization failure is auto-treated as a cache miss
+
+## Evolution Guidelines
+
+When adding new items under `.spocr/`:
+
+1. Use clear subdirectories (e.g. `schema/`, `diagnostics/`)
+2. Avoid storing secrets (connection strings, credentials)
+3. Prefer JSON for transparency unless binary size is a concern
+4. Document new subfolder purpose here
+
+## Auto-Update Skip Reference
+
+Environment variables influencing update behavior (checked very early):
+
+```
+SPOCR_SKIP_UPDATE=1      # or true/yes/on
+SPOCR_NO_UPDATE=true     # alias
+```
+
+CLI flags:
+
+```
+--no-auto-update   # disables check for that invocation
+--silent           # implicitly suppresses update prompts
+```
+
+If any is present, the auto-update service exits without contacting package sources.
+
+---
+
+Last update: 2025-10-04

.ai/README.md

@@ -0,0 +1,81 @@
+# SpocR Project AI Assistant Setup
+
+This directory contains configuration and guidelines for AI agents working on the SpocR project.
+
+## 📋 Files Overview
+
+- **`guidelines.md`** - Comprehensive AI agent guidelines for code quality, standards, and workflows
+- **`mcp-config.json`** - Model Context Protocol configuration (future)
+- **`prompts/`** - Reusable prompt templates for common tasks
+
+## 🤖 For AI Agents
+
+When working on SpocR, always:
+
+1. **Read `guidelines.md` first** - Understand project standards and requirements
+2. **Run self-validation early**: `dotnet run --project src/SpocR.csproj -- test --validate`
+3. **Use quality gates script** before proposing release changes
+4. **Update docs & changelog** alongside behavioral changes
+5. Prefer parsing `.artifacts/test-summary.json` (when using `--ci`) over console scraping
+
+## 🔧 Quick Setup Verification
+
+```bash
+# .NET toolchain
+dotnet --version   # Expect 8.x
+
+# Build main project
+dotnet build src/SpocR.csproj
+
+# Run structural validation only
+dotnet run --project src/SpocR.csproj -- test --validate
+
+# Full test suite (uses tests solution)
+dotnet test tests/Tests.sln
+```
+
+Quality gates (build + validate + tests + optional coverage):
+
+```powershell
+powershell -ExecutionPolicy Bypass -File eng/quality-gates.ps1 -SkipCoverage
+```
+
+Add coverage threshold (example 60):
+
+```powershell
+powershell -ExecutionPolicy Bypass -File eng/quality-gates.ps1 -CoverageThreshold 60
+```
+
+## 🧾 CI JSON Summary
+
+In CI mode (`--ci` flag), a machine-readable summary is written to `.artifacts/test-summary.json` describing validation/test counts and success state. Use this for conditional workflow steps instead of regex parsing on logs.
+
+## 🧪 Slow Tests
+
+Reflection/version stability tests are marked with `[Trait("Category","Slow")]`. You can filter them if needed using xUnit traits.
+
+## 📖 Key Resources
+
+- [Contributing Guidelines](../CONTRIBUTING.md)
+- [Testing Documentation](../tests/docs/TESTING.md) _(additions planned)_
+- [Project README](../README.md)
+- [AI Guidelines](./guidelines.md)
+
+## 🛠 Docs Development
+
+The documentation site uses Bun + Nuxt:
+
+```bash
+cd docs
+bun install
+bun run dev
+```
+
+## ⚙ Exit Codes
+
+See overview in main `README.md` (Exit Codes section). Treat non-zero values per category; avoid hardcoding future subcodes in tests.
+
+---
+
+**Last Updated:** October 2, 2025  
+**Version:** 1.1