@ait-co/console-cli 0.1.21 → 0.1.23

package/README.md

@@ -58,6 +58,41 @@ aitcc upgrade --force    # reinstall the latest release even if versions match
 
 Planned commands — `deploy`, `logs`, `status` — are tracked in [TODO.md](./TODO.md).
 
+### Project context (`aitcc.yaml`)
+
+App- and workspace-scoped commands (`app status`, `app deploy`, `app certs ls`, `keys ls`, …) accept an explicit `--workspace <id>` and positional `<appId>`, but you can also drop an `aitcc.yaml` (or `aitcc.json`) at the root of your project and let the CLI find it by walking up from the current directory:
+
+```yaml
+# aitcc.yaml
+workspaceId: 3095
+miniAppId: 31146
+```
+
+Resolution priority (highest first):
+
+- **workspace**: `--workspace` flag → `AITCC_WORKSPACE` env → yaml `workspaceId` → session selection (`aitcc workspace use`)
+- **mini-app**: positional/flag `<appId>` → `AITCC_APP` env → yaml `miniAppId`
+
+Each command prints a one-line context header to stderr so you always see what was resolved (suppressed under `--json` so machine-readable output is unaffected):
+
+```
+[workspace: 3095 (from aitcc.yaml) · app: 31146 (from aitcc.yaml)]
+```
+
+The walk stops at the nearest `.git` directory and never crosses `$HOME`. Passing `--workspace` overrides any yaml `miniAppId` (it may belong to a different workspace), but `AITCC_WORKSPACE` keeps it.
+
+When `aitcc app register` succeeds, the returned `miniAppId` is written back into the resolved `aitcc.yaml`/`aitcc.json` (comments and key order in YAML are preserved). Subsequent commands can then run without `--app`. The write-back is skipped under `--dry-run` and silently no-ops when the file already pins the same id; if no project file exists in the tree, the CLI prints a one-line stderr hint instead of creating one.
+
+To bootstrap an `aitcc.yaml` from scratch, run `aitcc app init`. The command asks for the required manifest fields interactively (workspace is picked from the live API list), validates each value against the same constraints that `register` enforces, and lays the optional fields (`homePageUri`, `logoDarkMode`, `keywords`, `horizontalScreenshots`) as commented-out lines for later edits. Image paths (`./assets/logo.png`, `./assets/thumbnail.png`, `./assets/screenshot-{1,2,3}.png`) are written as placeholders — drop the actual files into `./assets/` before running `aitcc app register`. `init` requires an interactive TTY and refuses `--json` / non-TTY runs with `interactive-required` (exit 2).
+
+```sh
+mkdir my-app && cd my-app
+aitcc app init           # interactive prompt → ./aitcc.yaml
+# (drop logo/thumbnail/screenshots into ./assets/)
+aitcc app register       # creates the mini-app and writes miniAppId back
+aitcc app status         # works with no flags — context comes from aitcc.yaml
+```
+
 ### Login details
 
 `aitcc login` launches a Chrome-family browser via the Chrome DevTools Protocol, navigates it to the Apps in Toss developer console sign-in URL, and waits for the main frame to reach the post-login workspace page. Once it does, the CLI dumps all cookies over CDP (including `HttpOnly` auth cookies that JavaScript can't see) and persists them to the local session file. The browser runs against a temporary, isolated `--user-data-dir` that is wiped on exit, so your everyday browser profile is never touched.
@@ -75,6 +110,21 @@ The containing directory is created with mode `0700`. Cookies captured during lo
 
 See [CLAUDE.md](./CLAUDE.md) for the rationale behind using a plain `0600` file instead of an OS keychain.
 
+## Continuous integration
+
+For one-shot CI runs (e.g. `aitcc app deploy` from a workflow), seed the runner with a session captured on a desktop machine:
+
+```sh
+# Desktop (already logged in):
+aitcc auth export --format env >> $GITHUB_ENV       # or: aitcc auth export --format env  → store as a secret
+# CI (with the secret exposed as $AITCC_SESSION):
+aitcc app deploy --bundle ./dist/app.zip --json
+```
+
+When `AITCC_SESSION` is set, every command reads the session from that env var instead of the local file. `logout` / `workspace use` / other write paths are silenced under env mode so a CI host never materialises a session file. Use `aitcc auth import --from-env` if you actually want the blob persisted to disk (mainly for restoring a desktop after a wipe).
+
+> **KR-only**: console session cookies are bound to KR residential IPs. The same `AITCC_SESSION` blob succeeds from a Korean machine but **fails with `401` / `errorCode: 4010`** from non-KR egress, including GitHub-hosted runners (Azure US/EU). Use a KR self-hosted runner or run the command yourself. See [`docs/api/auth-session.md`](./docs/api/auth-session.md).
+
 ## Update notifications
 
 When running interactively, `aitcc` occasionally checks for a newer release and prints a one-line notice on stderr if one exists. The check is rate-limit friendly: