docs: document the advisor command and repository scoping

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- `actual advisor` command: ask the Advisor org-scoped architecture questions from the terminal and print the answer with any related ADRs (requires signing in with `actual login`)
+- Repository scoping for `actual advisor`: `--repo <name|owner/name|uuid>` to target a connected repository, automatic detection from the working tree's `origin` remote, a scope remembered per repository, the `none` and `auto` keywords to pin org-level or reset, and `--show-scope` to print the active scope
+- Documentation for the advisor command and repository scoping in the README and Getting Started guide
+
 ## [0.1.4] - 2026-03-31
 
 ### Fixed

README.md

@@ -116,10 +116,44 @@ you've written yourself.
 | Agents | `--output-format agents-md` | `AGENTS.md` |
 | Cursor Rules | `--output-format cursor-rules` | `.cursor/rules/actual-policies.mdc` |
 
+## Ask the Advisor
+
+Beyond generating context files, `actual` can answer architecture questions
+directly. `actual advisor` sends your question to the Advisor and prints a
+tailored answer, plus any related ADRs, in the terminal.
+
+The Advisor works against your Actual AI organization, so sign in first:
+
+```bash
+actual login
+actual advisor "Should new services talk over gRPC or REST?"
+```
+
+By default the answer is scoped to the repository you're standing in:
+`actual` reads the working tree's `origin` remote and, if a connected
+repository matches, scopes the question to it. If nothing matches, the
+question runs at the organization level.
+
+Set the scope explicitly with `--repo`:
+
+```bash
+actual advisor --repo actual-cli "..."       # scope to a repo by name
+actual advisor --repo owner/actual-cli "..." # disambiguate a shared name
+actual advisor --repo none "..."             # ask at the organization level
+actual advisor --show-scope                  # print the active scope and exit
+```
+
+The scope you choose is remembered per repository for later calls from the
+same working tree; `--repo auto` forgets the pin and returns to
+auto-detection. See
+[Getting Started](docs/GETTING_STARTED.md#ask-the-advisor) for the full flag
+reference.
+
 ## Commands
 
 ```
 actual adr-bot        # analyze repo & write AI context files
+actual advisor        # ask the Advisor an architecture question
 actual status         # check output file state (managed markers, staleness)
 actual auth           # verify authentication
 actual config show    # view current configuration

docs/GETTING_STARTED.md

@@ -111,10 +111,59 @@ By default, `actual adr-bot` writes to `CLAUDE.md`. Content is wrapped in manage
 | `--show-errors` | Stream runner subprocess stderr in real time |
 | `--api-url <URL>` | Override ADR bank API endpoint |
 
+## Ask the Advisor
+
+`actual advisor` asks the Advisor an architecture question about your organization's codebase and prints the answer, along with any related ADRs, to your terminal. Unlike `adr-bot`, this command talks to your Actual AI account rather than a local AI runner, so sign in first with `actual login`.
+
+```bash
+actual login
+actual advisor "When should we introduce a message queue?"
+```
+
+The command starts an Advisor job and polls until the answer is ready (up to a few minutes), writing progress to stderr and the final answer to stdout.
+
+### Scoping the question to a repository
+
+By default the question is scoped to the repository you're standing in. `actual` reads the working tree's `origin` remote and, if one of your organization's connected repositories matches, scopes the answer to that repo. If nothing matches (or you aren't inside a git repo), the question runs at the organization level.
+
+Override the scope with `--repo`, which accepts a repository **name**, an `owner/name` form (to disambiguate a name shared across owners), or a repo **UUID**:
+
+```bash
+actual advisor --repo actual-cli "..."        # by name
+actual advisor --repo owner/actual-cli "..."  # by owner/name
+actual advisor --repo 3f2a1c9e-... "..."      # by UUID
+```
+
+Two values are reserved keywords rather than repository names:
+
+| Value | Effect |
+|-------|--------|
+| `--repo none` | Pin the scope to the organization level (opt out of repo scoping) |
+| `--repo auto` | Forget any pin and return to git-remote auto-detection |
+
+The scope you choose is **remembered per repository** (keyed by the working tree's `origin` remote) and reused on later `actual advisor` calls from the same tree, so you don't have to repeat `--repo` each time. Inspect the active scope without asking a question:
+
+```bash
+actual advisor --show-scope
+```
+
+To scope to a repository literally named `none` or `auto`, pass its `owner/name` form or UUID instead of the bare keyword.
+
+### Advisor flags
+
+| Flag | What it does |
+|------|-------------|
+| `<QUERY>` | The architecture question to ask. Optional when the command is used only to change or show scope (`--show-scope`, or a bare `--repo` value with no question) |
+| `--repo <REPO>` | Scope to a connected repository by name, `owner/name`, or UUID; `none` pins org level, `auto` resets to auto-detection. Omit to auto-detect from the `origin` remote |
+| `--show-scope` | Print the remembered scope for the current repository and exit (reads local config only, no query) |
+| `--org <ORG_ID>` | Organization to scope to (defaults to your signed-in org). Passing `--org` without `--repo` runs a one-shot organization-level query without changing the remembered scope |
+| `--api-url <URL>` | Advisor API base URL (defaults to production; also settable via the `ACTUAL_API_URL` environment variable) |
+
 ## Commands
 
 ```bash
 actual adr-bot        # analyze repo & write AI context files
+actual advisor        # ask the Advisor an org-scoped architecture question
 actual status         # check output file state (managed markers, staleness)
 actual auth           # verify the configured AI runner is authenticated
 actual config show    # view current configuration