chore: import upstream snapshot with attribution

2026-07-13 12:22:33 +08:00
commit fc4fcbab58
1848 changed files with 472303 additions and 0 deletions
@@ -0,0 +1,54 @@
+---
+summary: "Kilo provider data sources: app.kilo.ai API token and CLI auth-file fallback."
+read_when:
+  - Adding or modifying the Kilo provider
+  - Adjusting Kilo source-mode fallback behavior
+  - Troubleshooting Kilo credentials/auth sessions
+---
+
+# Kilo provider
+
+Kilo supports API and CLI-backed auth. Source mode can be `auto`, `api`, or `cli`.
+
+## Data sources + fallback order
+1. API (`api`)
+   - Token from `~/.codexbar/config.json` (`providers[].apiKey` for `kilo`) or `KILO_API_KEY`.
+   - Calls `https://app.kilo.ai/api/trpc`.
+2. CLI session (`cli`)
+   - Reads `~/.local/share/kilo/auth.json` and uses `kilo.access`.
+   - Requires a valid CLI login (`kilo login`).
+3. Auto (`auto`)
+   - Tries API first.
+   - Falls back to CLI only when API credentials are missing or unauthorized (401/403).
+
+## Settings
+- Preferences -> Providers -> Kilo:
+  - Usage source: `Auto`, `API`, `CLI`
+  - API key: optional override for `KILO_API_KEY`
+- In auto mode, resolved CLI fetches can show a fallback note in menu and CLI output.
+
+## CLI output notes
+- Kilo text output splits identity into `Plan:` and `Activity:` lines.
+- Auto-mode failures include ordered fallback-attempt details in text mode.
+
+## Troubleshooting
+- Missing API token: set `KILO_API_KEY` or provider `apiKey`.
+- Missing CLI session file: run `kilo login` to create `~/.local/share/kilo/auth.json`.
+- Unauthorized API token (401/403): refresh `KILO_API_KEY` or rerun `kilo login`.
+
+## Organizations
+
+CodexBar can show usage for any Kilo organization the API key belongs to.
+
+- Open Preferences → Providers → Kilo, set the API key, then click **Refresh
+  organizations**.
+- Toggle the organizations you want to display alongside Personal. Personal is
+  always shown.
+- When at least one organization is enabled, the menu renders one Kilo card per
+  enabled scope.
+- The CodexBar fetcher sends the standard `X-KILOCODE-ORGANIZATIONID` header on
+  every usage call to scope the response to that organization.
+- CLI source mode (`auth.json`): the header is applied to CLI-resolved tokens
+  as well. If a CLI token isn't authorized for the chosen organization, that
+  card surfaces an unauthorized error while Personal and other enabled scopes
+  continue to render normally.