Feat/implement new and robust llm providers

.claude/skills/commit/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: commit
+description: Turn uncommitted work into a logically ordered sequence of atomic conventional commits. Surveys the whole working tree, groups changes, orders them foundation-first, shows a plan, then commits by path. Use when the user says "commit this", "commit my work", "split this into commits", or "clean up my changes into commits"
+disable-model-invocation: true
+---
+
+# commit
+
+Take the current uncommitted work and commit it as a clean, ordered sequence of atomic commits — each self-consistent, each a conventional-commit.
+
+## 1. Survey
+
+Run these to see everything (not just what's staged):
+
+```bash
+git status --short
+git diff            # unstaged
+git diff --staged   # staged
+```
+
+Read the actual changes. List untracked files too (`git status --short` shows them as `??`).
+
+If the user named a subset to commit (specific files, or "just the auth work"), scope everything below to that subset and leave the rest untouched. Otherwise consider the whole tree.
+
+## 2. Group into atomic commits
+
+Cluster the changes into the smallest units that each stand on their own (one logical change per commit). Split unrelated work apart; keep a change and its direct test/doc together.
+
+**Flag unfinished work.** While reading the diff, watch for changes that look incomplete or not meant to ship — e.g. `TODO`/`FIXME`/`XXX` added, commented-out or debug code (`print`, `console.log`, `dbg!`), stubs / empty function bodies / `pass` / `NotImplementedError`, half-edited files, failing or `.skip`ped tests, or a reference with no definition. List each one and **ask** whether to include it, hold it back (leave unstaged), or fix it first. Don't silently commit it.
+
+## 3. Order foundation-first
+
+Sequence commits so each builds on the last:
+
+1. Dependencies / config / build setup
+2. Shared utilities, types, refactors that others depend on
+3. Features / fixes that use them
+4. Tests
+5. Docs
+
+## 4. Show the plan, wait for approval
+
+Print the proposed sequence and stop:
+
+```
+1. feat(auth): add password reset endpoint
+   files: src/auth/reset.ts, src/routes.ts
+2. test(auth): cover password reset flow
+   files: test/auth/reset.test.ts
+```
+
+Do not create any commit until the user approves. Adjust on feedback.
+
+## 5. Commit sequentially
+
+For each commit, stage that group **by path** then commit:
+
+```bash
+git add <paths for this commit>
+git commit -m "<type>(<scope>): <description>" -m "- detail" -m "- detail"
+```
+
+- Stage by explicit paths only. Do **not** use `git add -p`/`git add -i` (interactive, unsupported here); if two logically separate changes live in the same file and can't be split by path, note it in the plan and commit them together.
+- After each commit, verify with `git status` that the right files landed.
+
+## Commit format
+
+```
+<type>(<scope>): <description>
+```
+Add a bullet body (`-m` per bullet) only when the change has multiple parts.
+
+Types: `feat` (new feature), `fix` (bug fix), `refactor`, `perf`, `test`, `docs`, `build`, `ci`, `chore`. Scope is optional, lowercase, the affected area. Description: imperative, lowercase, no trailing period.
+
+## Rules
+
+- **Plan before committing.** Never commit without showing the sequence first.
+- **Subset is fine.** Commit only the changes the user asked for; leave everything else exactly as it was.
+- **Never commit unfinished work silently.** If something looks incomplete, ask first.
+- **Clean messages.** No agent attribution footer — write them as a human would.
+- **Never push.** Only `git push` if the user explicitly asks.
+- **Don't commit junk.** If a file looks like a secret, credential, or large build artifact, leave it unstaged and flag it.
+- **Branch safety.** If on the default branch (`main`/`master`), say so and offer to create a branch before committing.
+- **Respect hooks.** If a pre-commit hook rejects or rewrites a commit, stop and report — don't loop or bypass with `--no-verify` unless asked.

.claude/skills/decide/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: decide
+description: Record decisions in docs-agents/DECISIONS.md — add a TBD (open question), log a decided decision, or revise/revoke an existing one. Use when the user says "decide", "we decided", "log a decision", "that's TBD", or wants to change/revoke a past decision
+disable-model-invocation: true
+---
+
+# decide
+
+Maintains `docs-agents/DECISIONS.md`. Keep entries terse.
+
+## Locate the file
+
+Edit `docs-agents/DECISIONS.md` in the current project. If it doesn't exist, create it with this structure:
+
+```markdown
+# Decisions
+
+## TBD
+
+- **<Shortname> — <pending decision>** — options/context in one line.
+
+## Decided
+
+### DEC-001 — title
+
+Decided by: Author | Author with Claude Code | Claude Code
+Date: YYYY-MM-DD HH:MM
+
+**Decision:** 1–2 sentences (what was decided).
+
+**Rationale:** 1–2 sentences (why).
+```
+
+## Modes
+
+**1. Add a TBD** (open question requiring a decision to move forward, not yet decided). 
+Not to be confused with an open question from `docs-agents/QUESTIONS.md` which do not related to decision.
+Append to the `## TBD` list:
+```
+- **<Shortname> — <pending decision>** — options/context in one line.
+```
+
+**2. Log a decided decision**
+- Find the highest `DEC-NNN` in `## Decided`; new id = highest + 1, zero-padded to 3 digits.
+- Prepend the new entry to the top of `## Decided` (newest first).
+- Get the timestamp by running `date "+%Y-%m-%d %H:%M"`.
+- If it resolves a `## TBD` item, remove that TBD line.
+```
+### DEC-NNN — <title>
+
+Decided by: Author | Author with Agent | Agent
+Date: YYYY-MM-DD HH:MM
+
+**Decision:** 1–2 sentences (what was decided).
+
+**Rationale:** 1–2 sentences (why).
+```
+Set "Decided by" to who actually decided (ask if unclear; default `Author with Agent`).
+`Author` means the person using the skill.
+`Agent` means the coding agent harness (Claude Code / Codex).
+
+**3. Revise a decision**
+Locate the `DEC-NNN`. Do NOT rewrite history silently — append a revision note under the existing entry:
+```
+**Revised (YYYY-MM-DD HH:MM):** what changed and why. Supersedes original decision above.
+```
+Then move the whole entry to the top of `## Decided`. Keep its original id — the number is a stable reference, not a sort key, so recently-touched decisions surface first even if ids end up out of numeric order.
+
+**4. Revoke a decision**
+Prefix the title with `~~REVOKED~~` and append:
+```
+**Revoked (YYYY-MM-DD HH:MM):** reason. No longer in effect.
+```
+Then move the whole entry to the top of `## Decided` (same rule as revise) — a revocation is important activity, so surface the "no longer in effect" warning rather than leaving it buried.
+
+## Rules
+
+- Never renumber existing DEC ids.
+- Always stamp real timestamps via `date`, never guess.
+- Keep it skimmable — 1–2 sentences per field.

.claude/skills/glossary/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: glossary
+description: Manage docs-agents/GLOSSARY.md — add or refine a canonical term, extract terms from the current conversation, or audit for conflicts and duplicates. Use when the user says "define this term", "add to the glossary", "build a glossary", "what do we call this", or wants to harden terminology
+disable-model-invocation: true
+---
+
+# glossary
+
+Maintains `docs-agents/GLOSSARY.md` — the single source of truth for what terms mean in this project. Reference doc: opinionated, tight, skimmable. No implementation details or code.
+
+## Locate the file
+
+Edit `docs-agents/GLOSSARY.md`. If it doesn't exist, create it with this structure:
+
+```markdown
+# Glossary
+
+**<Term>** — one or two sentence definition in this project's context. _avoid:_ <synonyms to not use>
+```
+
+Format per term: a bold term, an em-dash, one or two sentences saying what it **is** (not what it does), and an optional `_avoid:_` list of synonyms to kill. One term per line. Keep alphabetical, or group under `##` subheadings only when natural clusters clearly emerge.
+
+## Modes
+
+**1. Add a term**
+Append (or insert alphabetically) one line in the format above. Pick the best word as canonical; list rejected synonyms under `_avoid:_`.
+
+**2. Refine a term**
+Locate the existing line and tighten its definition or update its `_avoid:_` list in place. Don't duplicate the term.
+
+**3. Extract from this conversation**
+Scan the discussion for project/domain-specific nouns and concepts. For each: pick a canonical term, write a one or two sentence definition, and note synonyms actually used in the conversation under `_avoid:_`. Add all new terms; refine any already present.
+
+**4. Audit**
+Read the whole file and report (inline, to the user): duplicate/near-duplicate terms, definitions longer than two sentences, generic programming terms that don't belong, and any term used two ways. Propose fixes; apply on confirmation.
+
+## Rules
+
+- **Be opinionated.** One canonical term per concept; everything else goes under `_avoid:_`.
+- **One or two sentences, define what it IS.** Cut anything longer.
+- **Project-specific only.** Skip generic programming concepts (array, endpoint, timeout) unless they carry special meaning here.
+- **Flag conflicts, don't silently overwrite.** If a new term clashes with an existing definition, surface it to the user and let them resolve it.
+- **No implementation details.** This is a glossary, not a spec or scratchpad.

.claude/skills/log/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: log
+description: Quickly add one entry to the right doc — a task, idea, stack choice, concern, or open question — in the correct format. Triggered by "log"/"note"/"capture"/"add"/"jot down" + the kind, e.g. "log this task", "note this idea down", "capture a concern", "add TODO", "we're using X for Y — put it in the stack", "open question:". Addition only.
+disable-model-invocation: true
+---
+
+# log
+
+Append a single new entry to the correct doc under `docs-agents/`, in that doc's format. This skill only **adds** — it never edits, reorders, or removes existing entries. Decisions and glossary terms are out of scope (use `decide` / `glossary`).
+
+## Route by what the user is logging
+
+Match on the **kind** the user names, however they phrase it (log / note / capture / add / jot down / write down / remember, or just naming the thing):
+
+| Kind & example phrasings                                                       | File                       | What to do                            |
+| ------------------------------------------------------------------------------ | -------------------------- | ------------------------------------- |
+| **task** — "log this task", "add a TODO", "remind me to…", "we still need to…" | `docs-agents/TASKS.md`     | checkbox item at top of **To do**     |
+| **idea** — "log this idea", "note this down", "what if we…", "idea:"           | `docs-agents/IDEAS.md`     | new `IDEA-NNN` at the top             |
+| **stack** — "we're using X for Y", "put X in the stack", "we went with X"      | `docs-agents/STACK.md`     | add a `- **Category:** choice` bullet |
+| **concern** — "log this concern", "I'm worried that…", "flag that…", "risk:"   | `docs-agents/CONCERNS.md`  | new `CON-NNN` at the top              |
+| **question** — "log this question", "open question:", "we need to figure out…" | `docs-agents/QUESTIONS.md` | new `Q-NNN` at the top                |
+
+**Newest goes on top.** Insert each new entry above the existing ones, not at the bottom. (Stack is the exception — it's grouped by category, not by recency.)
+
+If the target file doesn't exist, create it with just its `# Heading` before adding the entry. For ID'd docs, next id = highest existing NNN + 1, zero-padded to 3.
+
+## Formats
+
+**Task** — `docs-agents/TASKS.md`, insert at the top of the `## To do` section:
+```
+- [ ] <task> <!-- optional (context) -->
+```
+The file is organized `## To do` / `## Done`. Create those sections if missing; leave completed items alone (they belong under `## Done`).
+
+**Idea** — `docs-agents/IDEAS.md`, insert at top of the list (newest first):
+```
+## IDEA-NNN — <one-line title>
+
+Brief note (10–50 words), or bullets.
+```
+
+**Stack** — `docs-agents/STACK.md`, add a bullet in its logical spot (grouped by category, parentheses only if extra detail helps):
+```
+- **<Category>:** <choice> (<detail>)
+```
+If that category already exists with a different value, don't overwrite — flag the conflict and ask.
+
+**Concern** — `docs-agents/CONCERNS.md`, insert at top (newest first):
+```
+## CON-NNN — <one-line title>
+
+What it is and why it matters (10–50 words). Ref: <url, if any>
+```
+
+**Question** — `docs-agents/QUESTIONS.md`, insert at top (newest first):
+```
+## Q-NNN — <the question> — `open`
+
+**Answer:** <fill once answered; set status to `answered`>
+```
+
+## Rules
+
+- **One entry per invocation**, inserted at the top — no rewriting the rest of the file.
+- **Keep it tight.** Fit the format; don't pad. Rephrase the user's note only enough to be clear.
+- **Never guess an id** — read the file, find the highest, increment.
+- **Ambiguous target?** If it's unclear which doc the user means, ask before writing.

.claude/skills/write-manual/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: write-manual
+description: Write or update docs-agents/SUM.md — the Software User Manual — from the codebase. Mode 1 (generate) builds a full, detailed SUM from scratch by inventorying every user-facing surface so nothing is missed. Mode 2 (update) revises the SUM against a PR/diff, removing what's obsolete, editing what changed, and adding what's new — precisely and concisely. Triggered by "write the manual", "generate the user manual", "document how to use this", or "update the manual for this PR".
+disable-model-invocation: true
+---
+
+# write-manual
+
+Maintains `docs-agents/SUM.md` — the end-user manual: how to install and use the software correctly. Follows the template in `templates/docs-agents/SUM.md`: a **Contents** map up top, then 9 sections (§6–8 optional). This is a **user** manual, not a design doc — no internals, architecture, or rationale.
+
+## The Contents block
+
+A SUM is long, so `docs-agents/SUM.md` opens with a `## Contents` map — the first thing an AI tool (Claude Code, Codex) or human reads to jump to the right passage. Build it from the actual headings (never guess), and **rebuild it after every change so it always matches the document** (see Mode 1 Step C and Mode 2 step 4).
+
+- One entry per `##` section, and one **nested** sub-entry per `### Feature: <name>` subsection under §5, in document order.
+- Each entry is a heading anchor link + ` — ` + a one-line "what's here". For a feature, the one-liner is what the feature does.
+- Anchor = heading text lowercased, punctuation dropped, spaces → hyphens. E.g. `## 6. Configuration & Security` → `#6-configuration--security`; `### Feature: Export data` → `#feature-export-data`.
+- List only sections/features that actually exist — omit entries for dropped optional sections (§6–8). Never list the Contents block itself.
+
+## Before writing (both modes)
+
+1. **Read the template** `templates/docs-agents/SUM.md` for the target structure.
+2. **Read `docs-agents/GLOSSARY.md`** — use its canonical terms verbatim; never invent a synonym for something the glossary already names.
+3. **Skim sibling docs for context, not for copying:** `docs-agents/PRD.md` (what & who it's for), `docs-agents/features/*` (feature intent), `README.md`, `docs-agents/CHANGELOG.md`. The SUM describes *how to use*, the PRD/FRD describe *what & why* — don't leak the latter in.
+
+## Mode 1 — Generate a full SUM from the codebase
+
+Goal: a complete manual with **no blind spots**. Blind spots come from documenting only the obvious entry point and missing the rest. Prevent that by **inventorying every user-facing surface first**, then writing.
+
+**Step A — Inventory (do this before writing a word).** Sweep the codebase and list every surface a user touches:
+
+| Surface | Where to look |
+| --- | --- |
+| Install / build | `package.json` scripts, `pyproject.toml`, `Dockerfile`, `Makefile`, install docs |
+| Entry points | `bin/`, `main`, `cmd/`, `__main__`, CLI framework registrations |
+| Commands / subcommands | arg-parser definitions (argparse/click/commander/cobra…) |
+| API / endpoints | route definitions, OpenAPI/proto specs, exported public functions |
+| Config & env vars | config schema, `.env.example`, settings files, defaults |
+| Required files / services / credentials | DB, external APIs, secrets, tokens the software needs to run |
+| Features | `docs-agents/features/*` and the code that implements them |
+| Error/diagnostic messages | raised errors, exit codes, log strings a user would see |
+| Prerequisites & platforms | supported OS/runtime, version constraints, dependencies |
+
+Reconcile the inventory against the glossary and features docs. **Report the inventory to the user before drafting** if the surface is large — cheap way to catch a missing area early.
+
+**Step B — Write.** Fill the template top to bottom. Map each inventory item to its section:
+- Prereqs/platforms/required services → **§3 Requirements**
+- Install + config + a verify-it-worked check → **§4 Installation**
+- Every command/endpoint/feature → **§5 Usage** (one `### Feature: <name>` subsection each: what it does, how to use, example, options)
+- Config keys, secrets/access, secure setup → **§6 Configuration & Security**
+- Common errors → cause → fix, logs, recovery → **§7 Troubleshooting**
+- Full command/config/env/error tables → **§8 Reference**
+
+Every user-facing surface from Step A lands in exactly one section, or is deliberately dropped with a reason. Drop §6–8 only if genuinely empty.
+
+**Step C — Build the Contents block.** Once the body is final, generate the `## Contents` map from the headings you actually wrote (per "The Contents block" above). This is the last step so the map matches the finished document.
+
+## Mode 2 — Update the SUM for a PR
+
+Goal: bring the SUM back in sync with reality **precisely and concisely** — touch only what the change touched. This is a surgical edit, not a rewrite.
+
+1. **Get the diff.** `git diff <base>...HEAD` (or the PR range). Identify which user-facing surfaces changed — reuse the Step A inventory lenses, but scoped to the diff.
+2. **Classify each SUM impact and act:**
+   - **Remove** — a feature/command/flag/option the diff deleted → cut its lines (and its `### Feature:` subsection, reference row, error entry).
+   - **Modify** — behavior, syntax, defaults, or steps changed → edit that passage in place; keep glossary terms.
+   - **Add** — a new user-facing surface with no coverage → add the minimal section/`### Feature:` subsection/row needed.
+3. **Leave untouched** anything the diff didn't affect. No reflowing, reordering, or "while I'm here" cleanups.
+4. **Refresh the Contents block** — mandatory, not a "while I'm here" cleanup. If you added, removed, or renamed a section or `### Feature:` subsection, add/cut/rename its Contents entry; if a feature's purpose changed, update its one-liner. If no heading changed, leave Contents as-is.
+5. **Report** a short changelist to the user: what you removed / modified / added and why (note any Contents change).
+
+## Rules
+
+- **User-facing only.** How to install, configure, and use it. No architecture, no design rationale, no code internals.
+- **No blind spots (Mode 1):** inventory before drafting; every surface is covered or consciously dropped.
+- **Surgical (Mode 2):** change only what the diff changed; don't rewrite stable sections.
+- **Contents never goes stale.** After any edit, the `## Contents` map must match the document's headings exactly (right entries, right order, working anchors, one feature per `### Feature:` subsection). Regenerate it — this is required even in surgical Mode 2.
+- **Glossary is law.** Use canonical terms; if the code reveals a user-facing concept the glossary is missing, flag it (suggest running `glossary`), don't coin a term silently.
+- **Concise.** Fit the template; every example should be copy-pasteable. Cut prose that doesn't help a user act.
+- **Verify examples exist.** Don't invent commands, flags, or endpoints — cite ones that are actually in the code.
+- **Omit empty optional sections.** §6–8 carry `*(optional)*`; delete rather than pad.