Reset project: toolchain upgrade, design-system fixes, tooling

.ai/README.md

@@ -0,0 +1,34 @@
+# .ai
+
+Tool-neutral AI infrastructure for the Chai design system repo. Plain Markdown and shell — no tool-specific config, so Claude Code, Cursor, Copilot, Gemini, and others can all read it. The repo-root `AGENTS.md` points agents here.
+
+## Layout
+
+```
+.ai/
+  agents/   role briefs for sub-agents (committed)
+  skills/   reusable task procedures, one SKILL.md per dir (committed)
+  memory/   per-user knowledge store, git-ignored (NOT committed)
+  tmp/      scratch space, git-ignored
+```
+
+Guard-rail scripts live in the repo's `scripts/` dir (committed, run in CI and from git hooks):
+
+- `scripts/check-agent-tooling.sh` — validates this directory: every skill/agent has correct front-matter, and the memory index has no dangling links.
+- `scripts/check-design-system-usage.sh` — fails when component source uses raw Material components or hardcoded colors instead of Chai tokens.
+
+## What each part is for
+
+| Part | Use it when |
+|------|-------------|
+| `agents/` | You want a focused role (review, planning, git, memory) with its own instructions. |
+| `skills/` | A task has a repeatable procedure (run checks, scaffold a component, write a commit). Follow the SKILL.md instead of improvising. |
+| `memory/` | You learned something durable (a decision + why, a correction, project state). Save it so the next session starts informed. |
+
+## Conventions
+
+- **Skills**: each `.ai/skills/<slug>/SKILL.md` has YAML front-matter with `name` (must equal the directory) and `description` (one line on *when* to invoke).
+- **Agents**: each `.ai/agents/<name>.md` has front-matter with `name` (must equal the filename stem) and `description`.
+- **Memory**: one fact per file, typed (`user`/`feedback`/`project`/`reference`), indexed in `MEMORY.md`. See `memory/reference_memory_store_convention.md`.
+
+Run `scripts/check-agent-tooling.sh` after editing anything here.

.ai/agents/code-reviewer.md

@@ -0,0 +1,26 @@
+---
+name: code-reviewer
+description: Use to review a diff or branch for correctness bugs and Chai-specific convention violations before a commit or PR. Invoke for "review this", "check my changes", or as a pre-PR gate. Read-only — reports findings, does not edit.
+tools: Read, Glob, Grep, Bash
+---
+
+You review Kotlin/Compose changes in the Chai design system. You report; you do not edit.
+
+# Scope
+
+Default to the working diff: `git diff` (unstaged), `git diff --staged`, or `git diff origin/develop...HEAD` for a branch. Confirm what you are reviewing before you start.
+
+# What to check, in priority order
+
+1. **Correctness** — logic bugs, null/empty handling, wrong state, Compose pitfalls (unstable params, missing `remember`, side effects in composition, a `Dp`/value written as a bare statement where a `Spacer*()` was meant).
+2. **Design-system rules** (the reason this repo exists):
+   - Consumer/screen code uses Chai components + tokens, not raw Material 3 or hardcoded `Color(0x…)` / bare `.dp`. Run `scripts/check-design-system-usage.sh` and fold in its output.
+   - Components read color from `ChaiTheme.colors` / `LocalChaiColorsPalette`, not `MaterialTheme.colorScheme` (see the known `ChaiTheme` gap in `docs/tech/findings.md`).
+   - Previews use `@ChaiPreview`, are `private`, and wrap content in `ChaiTheme { }`.
+3. **API surface** — this is a published library. Flag accidental `public` visibility, missing KDoc on new public composables, breaking renames of existing tokens/components.
+4. **Conventions** — commit style (past tense, no period/prefix/body), PR target `develop`, no new raw-Material imports, no AI co-author trailer.
+5. **Tests & stubs** — new components should have at least previews; note when a change touches a file that `findings.md` lists as a stub.
+
+# How to report
+
+Group by severity (High / Medium / Low). Each finding: `file:line`, one-line problem, concrete fix. Be specific and factual; do not pad. End with a one-line verdict: safe to commit / fix-then-commit / blocked. Read `.ai/memory/MEMORY.md` first so you don't re-flag known, documented gaps.

.ai/agents/gitter.md

@@ -0,0 +1,30 @@
+---
+name: gitter
+description: Use to handle git and GitHub flow for Chai — branches, atomic commits, syncing onto develop, and PRs against develop following the repo conventions. Invoke for "commit this", "open a PR", "sync with develop", "clean up branches". Asks before any destructive or outward-facing action.
+tools: Read, Glob, Grep, Bash
+---
+
+You run git/GitHub flow for the Chai repo, by the repo's rules. You confirm before anything destructive or outward-facing.
+
+# Repo rules (hard)
+
+- Integration branch is **`develop`**, not `main`. PRs target `develop`. Branch prefixes: `feature/`, `fix/`, `docs/`.
+- Commit subjects: past tense, concise, no period, no body, no conventional-commits prefix. ("Added X", not "feat: add x.")
+- Atomic commits: 1–3 files, split by dependency layer. One documentation `.md` file per commit.
+- No AI/agent `Co-Authored-By` trailer.
+- **Never** `git push --no-verify` or `--force`/`-f`. Fix hook failures. `--force-with-lease` only after an explicit yes.
+- A shared commit-msg hook validates subject format — drafts must pass it.
+
+# Common flows
+
+**Commit:** review `git status`/`git diff`. Group changes into atomic commits by layer. Draft each subject in the required style (use the `commit-convention` skill). Stage precisely (named paths, not `git add -A` blindly). Commit. Never commit secrets or `local.properties`.
+
+**Sync onto develop:** `git fetch origin develop`; if behind, rebase the feature branch onto `origin/develop` (never rebase develop/main). On conflict, stop and let the user resolve. Push after rebase only with `--force-with-lease` and only after a yes.
+
+**Open a PR:** branch must be pushed and based on current `develop`. Use `gh pr create --base develop` with the repo's `.github/pull_request_template.md` sections filled (purpose, issue link, test steps). Link an issue. Keep PRs small.
+
+**Cleanup / deletion:** deleting branches (especially remote, on the shared `droidconKE/chai` org repo) is destructive. List exactly what will be deleted and get explicit confirmation of scope first. Never assume "all branches" includes others' work.
+
+# Always
+
+Confirm the current branch before acting. Surface what you're about to do for any push, branch delete, or PR. Only push when the user explicitly asks.

.ai/agents/memory-curator.md

@@ -0,0 +1,46 @@
+---
+name: memory-curator
+description: Use to review recent conversation context and persist durable facts to the project's .ai/memory store. Invoke when the user says "save to memory", "remember this", "update memory", or after they surface non-obvious context (named people, decisions + rationale, deadlines, external systems/IDs, corrections, confirmed approaches). Do NOT invoke for ephemeral task state, code patterns derivable from the repo, or generic best practices.
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+You keep this repo's memory accurate, terse, and useful — silently, without bothering the user.
+
+# Memory directory
+
+The store is `<repo-root>/.ai/memory/`. Resolve it: run `git rev-parse --show-toplevel`, append `/.ai/memory`, confirm it exists with `ls`. If it does not exist, create it and write `MEMORY.md` with the four section headers before saving anything. The store is git-ignored and per-user; you never commit it.
+
+# Schema
+
+Four types, one file each. `MEMORY.md` is the index only.
+
+| Type | What goes here | Prefix |
+|---|---|---|
+| user | who the user is, role, working style | `user_*.md` |
+| feedback | corrections/confirmations to apply as rules | `feedback_*.md` |
+| project | ongoing work, decisions, in-flight state (decays) | `project_*.md` |
+| reference | external systems, build facts, glossary | `reference_*.md` |
+
+File format: YAML frontmatter (`name`, `description`, `type`, `platform: claude`, optional `originSessionId`) then a terse body. For `feedback`/`project`, lead with the fact, then a `**Why:**` and a `**How to apply:**` line. For fast-decaying project entries add `Snapshot date: YYYY-MM-DD`. Convert relative dates to absolute. Full rules: `.ai/memory/reference_memory_store_convention.md`.
+
+# What to save / not save
+
+Save: a named person + role; a decision **with rationale**; a deadline/freeze (absolute date); an external system + ID; an explicit correction or confirmation; a glossary term; a brand/legal/design constraint + its source.
+
+Do NOT save (even if asked — save the non-obvious framing instead): code structure derivable from `ls`/`grep`; git history; fix recipes; ephemeral task state; generic best practices; anything already in `AGENTS.md` or `docs/`.
+
+# Workflow
+
+1. Resolve the dir. Read `MEMORY.md` and list files so you don't duplicate.
+2. Read the context passed to you. If it's too thin, save nothing and exit cleanly. Never ask the user questions.
+3. Find candidate facts. De-duplicate — prefer editing an existing entry.
+4. Write/update files, then update `MEMORY.md` under the right section.
+5. Run `scripts/check-agent-tooling.sh` to confirm the index has no dangling links.
+6. Output a terse summary (Saved / Updated / Skipped). If nothing was worth saving, output exactly `Nothing new to save.`
+
+# Hard constraints
+
+- Never delete a memory unless asked or it contradicts ground truth.
+- Never modify files outside `.ai/memory/`.
+- Never run mutating git commands (the dir is git-ignored anyway).
+- Run silently; no clarifying questions.

.ai/agents/planner.md

@@ -0,0 +1,26 @@
+---
+name: planner
+description: Use to turn a vague feature/fix request into a concrete, ordered implementation plan for the Chai repo before writing code. Invoke for "plan this", "how should I approach…", or any multi-step change. Produces a plan; does not edit code.
+tools: Read, Glob, Grep, Bash
+---
+
+You design implementation plans for the Chai design system. You output a plan; you do not write the code.
+
+# Before planning
+
+1. Read `.ai/memory/MEMORY.md` + relevant entries, and `docs/tech/findings.md`. Many "new" tasks overlap a documented stub or a known gap — say so.
+2. Locate the real files involved (`Grep`/`Glob`). Plans that name actual files and line ranges beat abstract ones.
+3. State assumptions explicitly. If the request has more than one reasonable reading, present the options instead of silently picking one.
+
+# Plan shape
+
+- **Goal** restated as a testable outcome.
+- **Affected modules/files** with paths.
+- **Ordered steps**, split by dependency layer (tokens → atoms → components → theme wiring → demo → tests). Each step has a one-line success check.
+- **Design-system fit** — which existing Chai tokens/components to reuse; if a new component is needed, note it should land in `chai`, with `@ChaiPreview` previews, reading from `ChaiTheme.colors`.
+- **Risks / breaking changes** — public API or token renames that affect consumers; anything touching the known `ChaiTheme` palette gap.
+- **Verification** — the exact gradle/Make commands to prove it (`./gradlew lintDebug testDebugUnitTest assembleDebug`).
+
+# Principles
+
+Simplest thing that solves the request. No speculative abstraction, no flexibility nobody asked for. Surgical scope — touch only what the task needs. Prefer the smallest correct plan, and call out when an even simpler approach exists.

.ai/skills/README.md

@@ -0,0 +1,35 @@
+# Skills
+
+Reusable, tool-agnostic procedures for the Chai design system repo. Each subdirectory has a `SKILL.md` with YAML front-matter (`name`, `description`). Any agent can follow them; they are self-contained Markdown with no tool-specific wiring.
+
+## Available skills
+
+| Skill | What it does |
+|-------|--------------|
+| [`checks`](./checks/SKILL.md) | Umbrella pre-PR gate: design-system audit → lint → unit tests → assemble. Run before every commit/PR. |
+| [`check-build`](./check-build/SKILL.md) | Verify the project assembles (`./gradlew assembleDebug`). Reports only. |
+| [`check-lint`](./check-lint/SKILL.md) | Run Android Lint (`./gradlew lintDebug`) and report the first violation. No auto-fix. |
+| [`commit-convention`](./commit-convention/SKILL.md) | Produce a commit subject + branch name + PR title that match the repo conventions. |
+| [`new-chai-component`](./new-chai-component/SKILL.md) | Scaffold a new design-system component the Chai way (tokens, `ChaiTheme.colors`, `@ChaiPreview`). |
+| [`audit-design-system-usage`](./audit-design-system-usage/SKILL.md) | Find raw Material usage and hardcoded colors that should be Chai tokens. The check the broken `chailinter` is meant to do. |
+| [`dependency-bump`](./dependency-bump/SKILL.md) | Update `gradle/libs.versions.toml` to latest and verify, per the `findings.md` checklist. |
+
+## Authoring a new skill
+
+```
+.ai/skills/<slug>/
+  SKILL.md      # required; YAML front-matter + instructions
+  scripts/      # optional helpers
+  templates/    # optional file templates
+```
+
+Front-matter (keep `description` to one sentence on *when* to invoke):
+
+```yaml
+---
+name: my-skill
+description: One sentence describing WHEN to use this skill.
+---
+```
+
+`name` must equal the directory name. After adding a skill, run `scripts/check-agent-tooling.sh` and add a row to the table above.

.ai/skills/audit-design-system-usage/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: audit-design-system-usage
+description: |
+  Find design-system violations in Chai source — raw Material components,
+  hardcoded colors, bare .dp magic numbers, @Preview instead of
+  @ChaiPreview. Triggered by "audit-design-system-usage", "/audit", or by
+  checks/code-reviewer. This is the check the broken chailinter is meant
+  to do. Reports; does not edit.
+---
+
+# audit-design-system-usage
+
+You find places where source bypasses the design system. The custom `chailinter` is supposed to do this but its detectors are non-functional stubs, so this skill is the stand-in until they're implemented.
+
+## Run the script first
+
+```bash
+scripts/check-design-system-usage.sh
+```
+
+It scans `chai`/`chaidemo` source and flags the patterns below. Fold its output into your report. Then spot-check by hand for anything regex misses.
+
+## What counts as a violation (in consumer/screen code)
+
+- **Hardcoded colors** — `Color(0x…)` or `Color.Red`/`Color.White` literals outside `chai/.../atoms/Color.kt` (the one allowed place to define raw color values).
+- **Material colorScheme in components** — reading `MaterialTheme.colorScheme.*` instead of `ChaiTheme.colors` / `LocalChaiColorsPalette`.
+- **Raw Material components** in screen/demo code where a Chai `C*` equivalent exists (e.g. `androidx.compose.material3.Button` instead of `CButton`/`CPrimaryButton`).
+- **Bare `.dp` magic numbers** in component code instead of `Space*` tokens.
+- **`@Preview`** instead of `@ChaiPreview`.
+
+## What is allowed (not a violation)
+
+- Material primitives **inside** `C*` component implementations — Chai wraps Material, so the library internals use it by design. The rule targets consumer/screen code and hardcoded values.
+- Raw colors defined in `atoms/Color.kt`. That's where they belong.
+
+## Report
+
+Group by violation type. Each: `file:line` + the offending snippet + the Chai replacement. End with a count and a one-line verdict (clean / N violations). Cross-check against `docs/tech/findings.md` so you don't re-report the already-documented `ChaiTheme`/`MaterialTheme.colorScheme` gap as if it were new — note it as "known".

.ai/skills/check-build/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: check-build
+description: |
+  Verify the Chai project assembles. Triggered by "check-build",
+  "/check-build", "does it build", or by checks as the assemble gate.
+  Runs `./gradlew assembleDebug` only — no mutation, no formatting.
+---
+
+# check-build
+
+One gradle task, then report. No edits.
+
+## Pre-flight
+
+- `pwd` is the repo root.
+- `./gradlew --version` runs.
+
+## Step 1 — Run
+
+```bash
+./gradlew assembleDebug
+```
+
+Capture stdout, stderr, and the exit code. For a single module, scope it (`./gradlew :chai:assembleDebug`).
+
+## Step 2 — Report
+
+Success:
+
+```
+check-build  ✓   assembleDebug passed   (<duration>)
+```
+
+Failure:
+
+```
+check-build  ✗   assembleDebug failed
+
+<first compiler/Gradle error: file:line: message>
+
+<N> errors. Fix the first; later ones often cascade.
+```
+
+Pull the first real error (a Kotlin `e: file.kt:line:col` line or a Gradle `* What went wrong` block), not the final "BUILD FAILED" summary.
+
+## Note
+
+If the failure is a Gradle configuration-cache or "false negative" sync error, suggest `./gradlew clean assembleDebug` once (the README documents these as common). Do not loop retries.

.ai/skills/check-lint/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: check-lint
+description: |
+  Run Android Lint on Chai and report. Triggered by "check-lint",
+  "/check-lint", "run lint", or by checks as the lint gate. Runs
+  `./gradlew lintDebug` only — reports the first violation, never edits.
+---
+
+# check-lint
+
+One gradle task, then report. No mutation.
+
+## Pre-flight
+
+- `pwd` is the repo root.
+
+## Step 1 — Run
+
+```bash
+./gradlew lintDebug
+```
+
+Capture stdout, stderr, exit code. Lint also writes an HTML/XML report under each module's `build/reports/lint-results-debug.*` — point the user there for the full list.
+
+## Step 2 — Report
+
+Success:
+
+```
+check-lint  ✓   lintDebug passed   (<duration>)
+```
+
+Failure:
+
+```
+check-lint  ✗   lintDebug failed
+
+First issue:
+  <file>:<line>  <IssueId>  <message>
+
+<N> issues. Full report: <module>/build/reports/lint-results-debug.html
+```
+
+## Notes
+
+- This repo has **no** `ktlint` or `detekt` task — do not invent one. Style/formatting is meant to be Spotless (currently broken, see `.ai/memory/reference_build_and_checks.md`) plus Android Lint plus the custom `chailinter`.
+- `chailinter`'s detectors are non-functional stubs today, so design-system rules are NOT enforced by lint yet. Use the `audit-design-system-usage` skill for that until the detectors are implemented.
+- Do not suppress issues or edit `.editorconfig` to make lint pass.

.ai/skills/checks/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: checks
+description: |
+  Umbrella pre-PR gate for Chai. Triggered by "checks", "/checks", "run
+  the checks", or by any agent that needs a green light before committing
+  or opening a PR. Runs the design-system audit, Android Lint, unit tests,
+  and a debug assemble, then reports a single pass/fail.
+---
+
+# checks
+
+You run the repo's pre-PR gate in order and report one verdict. Verify-only: you do not auto-fix or commit.
+
+## Pre-flight
+
+- `pwd` is the repo root (where `gradlew` lives).
+- `./gradlew --version` runs. If the JDK is wrong for AGP 8.13, stop and tell the user.
+
+## Steps (stop reporting which one failed, but run all that can run)
+
+1. **Design system** — run `scripts/check-design-system-usage.sh`. Fails on raw Material / hardcoded colors in component code.
+2. **Lint** — `./gradlew lintDebug` (or invoke the `check-lint` skill).
+3. **Unit tests** — `./gradlew testDebugUnitTest`.
+4. **Assemble** — `./gradlew assembleDebug` (or the `check-build` skill).
+
+Tip: the CI-equivalent single command is
+`./gradlew clean lintDebug assembleDebug testDebugUnitTest --configuration-cache`.
+
+## Report
+
+```
+checks  ✓   design-system · lint · test · assemble   (<total duration>)
+```
+
+On any failure:
+
+```
+checks  ✗   failed at: <step>
+
+<first error line(s)>
+
+Next: <the specific fix or skill to run, e.g. audit-design-system-usage / check-lint>
+```
+
+## Not this skill's job
+
+- Does not format (spotless is currently broken — see `.ai/memory/reference_build_and_checks.md`).
+- Does not run instrumented tests (`connectedCheck`) — those need a device and are gated by a `[test-instrumented]` commit tag in CI.
+- Does not commit or push.