# WIP: `feat/ai` — AI assistant client

**Branch:** `feat/ai` in cproof.
**Status:** in flight at the time of writing. Delete this file when the branch
merges to `master`; fold the relevant bits into the stable layer.

This file describes the delta `feat/ai` adds on top of `master`. Load it only
when working on the `feat/ai` branch.

## What the branch adds

A new module: `src/ai/`. A multi-provider AI assistant accessible via the
`/ai` command (OpenAI, Perplexity).

## New files

| Path | Role |
|---|---|
| `src/ai/ai_client.c` | Provider abstraction, request/response, provider registry. |
| `src/ai/ai_client.h` | Public surface. Notable: `char* ai_providers_find(const char*, gboolean, void*);` (stateless autocomplete callback). |
| `tests/unittests/test_ai_client.c` | Unit tests for the AI client. |
| `tests/unittests/test_ai_client.h` | Header pair for the above. |
| `tests/unittests/ai/stub_ai_client.c` | Stubs for `ai_client.*` consumers in other unit tests. |
| `tests/unittests/ui/stub_ai.c` | UI-side stub for the AI surface consumed by `src/ui/`. |

Plus added entries in:

| File | Addition |
|---|---|
| `src/command/cmd_defs.c` | `/ai` command record. |
| `src/command/cmd_funcs.{c,h}` | `cmd_ai` handler. |
| `src/command/cmd_ac.c` | `_ai_autocomplete` dispatcher; static `ai_subcommands_ac`, `ai_set_subcommands_ac`, `ai_remove_subcommands_ac`. |
| `tests/unittests/unittests.c` | Test registrations for `test_ai_*`. |

## Subcommand layout

```
/ai set    {provider|token|org}  <provider-name>  <value>
/ai remove provider               <provider-name>
/ai start  <provider-name>
/ai clear  <provider-name>
/ai correct <provider-name>
/ai providers
```

## Autocomplete

- `_ai_autocomplete` in `cmd_ac.c` is the per-command dispatcher.
- Top-level subcommand list: `ai_subcommands_ac` → `set`, `remove`, `start`,
  `clear`, `correct`, `providers`.
- Set subcommands: `ai_set_subcommands_ac` → `provider`, `token`, `org`.
- Remove subcommands: `ai_remove_subcommands_ac` → `provider`.
- Provider-name completion: `ai_providers_find()` (`src/ai/ai_client.c`) — a
  **stateless** callback (no `_last_match` global). On the `feat/ai`
  branch, this is the most current canonical example of a stateless
  autocomplete callback.

## CI deltas

`feat/ai` also brings (unrelated to AI itself):

- `0feacbc9d ci: simulate Pikaur flag duplication in Arch Linux CI` — adds a
  CI step that simulates the Pikaur duplicated-flag failure mode in the
  Arch Linux job. Survives independently of the AI feature.

If the AI work is merged but the CI delta is rebased separately, update
`build/ci.md` to mention this commit alongside `0722dc9e3`.

## On merge — what to fold into stable layers

When `feat/ai` lands on `master`, edit:

| File | Change |
|---|---|
| `architecture/source-map.md` | Add `src/ai/` row to the module table. |
| `architecture/overview.md` | Add AI to the optional integrations / module list; drop the "active feature branches" caveat. |
| `architecture/test-map.md` | Add `tests/unittests/ai/` stub directory; mention `test_ai_client.{c,h}`. |
| `patterns/autocomplete.md` | Optionally add `ai_providers_find` as a second canonical stateless-callback example (or leave `roster_contact_autocomplete` as the sole example). |
| `playbooks/add-autocomplete.md` | Same. |
| `gotchas.md` | Same. |
| `build/ci.md` | Mention the Pikaur CI simulation commit alongside the original Pikaur fix. |

Then **delete this file**. Update `INDEX.md` to drop the `wip/` row if no
other WIP entries remain.