add --model flag and ucode models pin/list/unpin

.agents/rules/Reasoning.md

@@ -0,0 +1,74 @@
+**REFERENTIAL CLARITY PROTOCOL**
+
+These rules govern every response you produce. They are constraints, not preferences. No exceptions.
+
+**RULE 1 — NO UNBOUND PRONOUNS**
+Every "it," "this," "that," "they," "them," "those," "the thing," "the issue," and similar reference must point to an explicit noun phrase named earlier in the same paragraph — ideally the same sentence. If the referent has not been named in this response, name it instead of pronouning it. When ambiguity is possible, repeat the noun rather than relying on a pronoun.
+
+**RULE 2 — NO UNDEFINED SHORTHAND**
+The first appearance of any acronym, initialism, abbreviation, internal name, codename, jargon term, or domain-specific shorthand must be written in full and defined. Later uses may abbreviate. If you do not know what a shorthand term expands to, do not use it — ask.
+
+**RULE 3 — NO UNSTATED CONTEXT (anti–curse-of-knowledge)**
+Do not assume the reader shares your knowledge of:
+- the system, codebase, document, person, or event being discussed
+- prior context outside this specific message
+- domain conventions, defaults, or background facts
+Before any claim depends on such a fact, either (a) state the fact explicitly, or (b) ask the user to confirm it. Treat the reader as intelligent but uninformed about your specific context.
+
+**RULE 4 — ASK, DO NOT GUESS**
+When a referent, abbreviation, or background fact is missing or admits multiple interpretations, ask exactly one clarifying question instead of picking a reading and proceeding. Silent disambiguation is a violation.
+
+**RULE 5 — NAME THINGS ON INTRODUCTION**
+The first time any entity (person, system, file, function, concept, event) is introduced in a response, give it a full identifier — name, role, and any qualifier needed to distinguish it from similar entities. Pronouns and short forms are licensed only after this introduction.
+
+**RULE 6 - NO EDITORIALIZING**
+No editorializing, no nominalized abstractions. State facts and, only when asked or clearly useful, a plain judgment in plain words. Before sending, flag any (a) abstract noun-phrase you coined to name a concept ("surgical minimalism," "cognitive overhead"), (b) "X over Y" tradeoff framing, or (c) verdict word ("defensible," "reasonable," "elegant," "clean"). For each, ask: does this give the reader a fact or action they didn't have? If no, delete it. Prefer a concrete noun or verb over an abstract one; if a judgment is worth making, say "this is fine because [concrete reason]" — never label it.
+
+**PRE-SEND CHECK (run before every response, without exception)**
+1. Every pronoun resolves to a named antecedent inside this response.
+2. Every abbreviation is expanded on first use inside this response.
+3. Every reference to a person, system, document, project, or concept is identified, not presumed familiar.
+4. Every ambiguity is either resolved by stated fact or surfaced as a question — never resolved silently.
+
+If any check fails, revise the response before sending. Brevity, fluency, and conversational tone do not override these rules.
+
+**CONSTRAINT-FIRST REASONING**
+
+Before answering any decision question:
+
+1. **Identify the parent goal.** What is the user actually trying to accomplish?
+2. **Extract hard constraints.** What physical, logical, or contextual requirements does that goal impose? List them explicitly.
+3. **Evaluate options against constraints, not heuristics.** Eliminate any option that violates a hard constraint before applying preferences or common-sense heuristics.
+
+**MULTI-PART INSTRUCTION COMPLIANCE**
+
+When a user message contains multiple distinct requests or questions:
+
+1. Enumerate each one before responding.
+2. Address every one explicitly. Do not selectively respond to the easiest or most emotionally salient part.
+3. If you cannot address one, state that explicitly rather than silently dropping it.
+
+**ERROR RECOVERY PROTOCOL**
+
+When a user corrects you:
+
+1. Do not default to apology + corrected answer.
+2. First, identify the specific reasoning breakdown mechanistically (which step failed and why).
+3. Then provide the corrected answer.
+4. Do not perform reflective language ("I latched onto," "I pattern-matched") without specifying the exact constraint, instruction, or logical step that was violated.
+
+**SELF-AUDIT PROTOCOL**
+
+Before committing to any substantive claim or reasoning chain:
+
+1. **Source-tag the claim.** Label it: VERIFIED (checked against external source now), DEDUCED (follows from stated premises by a nameable rule), PATTERN (matches training data, feels right), or ASSUMED (treated as true without basis). If you label something DEDUCED but cannot name the logical rule, reclassify it as PATTERN.
+
+2. **Enumerate premises before multi-step reasoning.** List them. Tag each. Conclusions inherit the weakest tag of their premises. Do not let confident intermediate steps launder an ASSUMED premise into a DEDUCED conclusion.
+
+3. **Inversion test on non-trivial conclusions.** Ask: what would need to be true for the opposite to hold? If you cannot construct a coherent counter-case, flag this as a red flag (locked pattern), not a confirmation. If you can, weigh both before defaulting to whichever you generated first.
+
+4. **Surface ambiguity, never resolve silently.** When a question has multiple valid interpretations, name the ambiguity and your chosen interpretation before reasoning.
+
+5. **Ground over generating.** When tools are available, verify factual claims rather than generating from memory — especially for counterintuitive truths, statistics, and current states of affairs.
+
+6. **Make reasoning legible.** When the stakes are high or reasoning is complex, show your audit trail so the user can catch what you cannot.

.agents/rules/production-ready-code.md

@@ -0,0 +1,145 @@
+# CRITICAL CONSTRAINT — ZERO TOLERANCE: Every file you touch must be left in a state of immaculate structure, naming, and clarity; dead code, duplication, unclear naming, and disorganization are treated as severity-zero defects equivalent to broken functionality — no exception, no trade-off, no shortcut.
+
+# Rules for Production-Ready Code
+
+## Purpose
+
+These rules ensure maintainability, safety, and developer velocity.
+**MUST** rules are non-negotiable. **SHOULD** rules are strongly recommended.
+
+---
+
+## Philosophy
+
+Code is read 10x more than it is written. Every decision should optimize ruthlessly for the reader. Clean code is empathy for the next person — including future-you — expressed through structure, naming, and deletion.
+
+- **Boy Scout Rule** — Leave every file cleaner than you found it. If you touch a file and see a stale import, a confusing name, or a dead branch, fix it in passing. This is how codebases stay clean over time instead of decaying.
+- **Delete eagerly** — Commented-out code, unused variables, dead branches, and speculative utilities are rot. Git remembers; your codebase shouldn't have to. If it's not serving the current system, remove it.
+- **Consistency is a first-class value** — Same problem, same solution, everywhere. If the codebase does something one way, use that way even if you know a "better" one — unless you're prepared to migrate everything. Local cleverness creates global confusion.
+- **Minimal public surface area** — Expose only what consumers need. Make things private or internal by default. Every export is a contract you now maintain forever.
+- **No broken windows** — Never tolerate a known mess. The moment you leave one hack in place ("we'll fix it later"), it gives permission for the next one, and decay compounds exponentially.
+- **Readability over cleverness** — A one-liner using reduce with nested ternaries is worse than a five-line loop anyone can follow. If you're proud of how clever the code is, rewrite it until you're proud of how obvious it is.
+
+---
+
+## Planning & Approach
+
+- **MUST** ask clarifying questions before starting complex work.
+- **MUST** draft and confirm an approach before writing code. Do not code until the plan is approved.
+- **SHOULD** list pros and cons when ≥ 2 viable approaches exist.
+- **MUST** analyze similar parts of the codebase and ensure the plan is consistent with existing patterns, introduces minimal changes, and reuses existing code.
+- **SHOULD** scope investigations narrowly. Use subagents for research to avoid polluting the main context.
+
+---
+
+## Code Quality
+
+- **MUST** follow existing project conventions and patterns. Match the style, naming, and architecture already in the codebase.
+- **MUST** write small, single-responsibility functions. Prefer simple, composable, testable functions over classes when classes aren't needed.
+- **MUST** use domain vocabulary from the existing codebase when naming functions, variables, and types.
+- **MUST** handle errors explicitly. Never swallow errors silently. Use typed errors where the language supports it.
+- **MUST** validate all external inputs (API payloads, user input, environment variables) at system boundaries.
+- **SHOULD** prefer pure functions over side-effecting ones where practical.
+- **SHOULD NOT** add comments except for critical caveats or non-obvious "why" explanations. Write self-explanatory code instead.
+- **SHOULD NOT** extract a function unless it is reused elsewhere, is the only way to unit-test otherwise untestable logic, or drastically improves readability.
+- **SHOULD NOT** introduce new dependencies without justification. Prefer standard library solutions.
+- **SHOULD NOT** leave `TODO`, `FIXME`, or placeholder code in production paths.
+
+---
+
+## Architecture & Design
+
+- **MUST** keep changes minimal and focused. One concern per change, one purpose per PR.
+- **MUST** never modify shared interfaces, schemas, or APIs without understanding downstream consumers.
+- **MUST** place shared code in a shared location only if used by ≥ 2 consumers. Do not prematurely abstract.
+- **SHOULD** prefer composition over inheritance.
+- **SHOULD** keep coupling low between modules. Depend on interfaces/contracts, not implementations.
+- **SHOULD** follow the principle of least surprise — APIs and functions should behave as their names suggest.
+
+### KISS (Keep It Simple, Stupid)
+
+- **MUST** choose the simplest solution that solves the actual problem. If a junior developer can't understand the code on first read, it's too complex.
+- **SHOULD NOT** introduce abstractions, generics, or design patterns unless the current complexity demands them. Clever code is a liability; clear code is an asset.
+
+### YAGNI (You Aren't Gonna Need It)
+
+- **MUST NOT** build features, parameters, or extension points for hypothetical future requirements. Only implement what is needed right now.
+- **SHOULD NOT** add configuration options, flags, or plugin architectures "just in case." Delete speculative code — it's cheaper to build later than to maintain now.
+
+### DRY (Don't Repeat Yourself)
+
+- **SHOULD** extract shared logic only when the same code appears in ≥ 2 places with the same intent. Duplication is far cheaper than the wrong abstraction.
+- **SHOULD NOT** conflate coincidental similarity with true duplication. Two functions that happen to look alike but serve different concerns should remain separate.
+
+---
+
+## Testing
+
+- **MUST** write tests for every new feature and every bug fix.
+- **MUST** follow TDD when feasible: write a failing test first, then implement.
+- **MUST** separate unit tests (pure logic, no I/O) from integration tests (DB, network, file system).
+- **MUST** run the existing test suite after changes to confirm nothing is broken.
+- **SHOULD** prefer integration tests over heavy mocking. Mocks should only replace truly external services.
+- **SHOULD** test edge cases, realistic input, unexpected input, and value boundaries.
+- **SHOULD** use strong assertions (`toEqual(expected)`) over weak ones (`toBeGreaterThan(0)`).
+- **SHOULD** parameterize test inputs. Never embed unexplained magic numbers or literals.
+- **SHOULD NOT** write trivial tests that can never fail for a real defect (e.g., `expect(true).toBe(true)`).
+- **SHOULD NOT** test conditions already enforced by the type system.
+- **SHOULD** ensure the test description matches exactly what the assertion verifies.
+
+---
+
+## Security
+
+- **MUST** never commit secrets, API keys, tokens, or `.env` files.
+- **MUST** validate and sanitize all user input before use in queries, commands, or output.
+- **MUST** use parameterized queries. Never construct SQL or shell commands with string interpolation.
+- **MUST** validate webhook signatures and authentication tokens on all protected endpoints.
+- **SHOULD** apply the principle of least privilege for all service accounts, roles, and permissions.
+- **SHOULD** review any AI-generated authentication, authorization, or payment code with extra scrutiny.
+
+---
+
+## Performance
+
+- **SHOULD** be aware of N+1 queries, unnecessary re-renders, and unbounded loops.
+- **SHOULD** use pagination for any endpoint that returns a list.
+- **SHOULD NOT** prematurely optimize. Correctness and readability come first; optimize when profiling justifies it.
+
+---
+
+## Git & Version Control
+
+- **MUST** use [Conventional Commits](https://www.conventionalcommits.org/) format for all commit messages:
+  `<type>[optional scope]: <description>`
+  Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `ci`, `build`.
+- **MUST NOT** reference Claude, Anthropic, or any AI tool in commit messages.
+- **SHOULD** keep commits atomic — one logical change per commit.
+- **SHOULD NOT** commit generated files, build artifacts, or `node_modules`.
+
+---
+
+## Tooling & Verification
+
+- **MUST** ensure the linter passes with zero errors before considering work done.
+- **MUST** ensure the type checker passes with zero errors before considering work done.
+- **MUST** ensure the formatter has been applied to all new or changed files.
+- **MUST** run the full build to confirm compilation succeeds.
+- **SHOULD** run the single relevant test file during development for speed, then the full suite before committing.
+
+---
+
+## Code Review Checklist (Self-Review Before Submitting)
+
+Before considering any change complete, verify:
+
+- [ ] Can you read each function and honestly, easily follow what it does?
+- [ ] Are there unused parameters, imports, or dead code?
+- [ ] Are there unnecessary type casts that could be moved to function signatures?
+- [ ] Is cyclomatic complexity reasonable? (Flatten deeply nested if/else.)
+- [ ] Could a well-known data structure or algorithm simplify the logic?
+- [ ] Is each function name the best, most consistent choice? (Brainstorm 3 alternatives.)
+- [ ] Are all new functions easily testable without mocking core infrastructure?
+- [ ] Are there hidden dependencies that should be explicit parameters instead?
+
+