astra-cli-agent 0.1.2__tar.gz → 0.1.3__tar.gz

{astra_cli_agent-0.1.2 → astra_cli_agent-0.1.3}/.env.example

@@ -9,6 +9,13 @@ GROQ_API_KEY=
 # Local Ollama server (optional last-resort fallback)
 OLLAMA_HOST=http://localhost:11434
 
+# Optional GitHub API access (the git agent's github_* tools: create/delete repos, issues,
+# pull requests, and authenticated push/pull against private repos). Generate a fine-grained
+# personal access token at https://github.com/settings/tokens with repo scope. Leaving
+# GITHUB_TOKEN unset simply disables these tools; local git operations (status/diff/commit/
+# push to a public or already-authenticated remote/etc.) work without it.
+GITHUB_TOKEN=
+
 # Optional general web search (the research agent's `web_search_general` tool). Uses SerpApi
 # (https://serpapi.com) to run a real Google search. Leaving SERPAPI_KEY unset simply disables
 # `web_search_general`; the GitHub/StackOverflow/fetch tools work without it.

{astra_cli_agent-0.1.2 → astra_cli_agent-0.1.3}/HANDOFF.md

@@ -6,9 +6,14 @@ The living architecture doc is [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) —
 too for the full target design. This file is the "where are we right now" companion.
 
 Last updated: 2026-07-11, end of Phase 18 + a post-18 hardening pass (see §7) that closed
-six of the "known simplifications" from §3, plus a post-18 addendum (see §5) that verified
-CI is actually live on GitHub, resolved a PyPI naming collision (renamed to
-`astra-cli-agent`), and added first-run `astra setup` provider onboarding.
+six of the "known simplifications" from §3, a post-18 addendum (see §9) that verified CI is
+actually live on GitHub, resolved a PyPI naming collision (renamed to `astra-cli-agent`),
+and added first-run `astra setup` provider onboarding, and a public-release pass (see §10)
+that actually published `astra-cli-agent` to PyPI (v0.1.0–v0.1.2), stood up a public
+README-only GitHub repo, and gave the CLI a real ASCII-logo presence. **The project is
+fully shipped and installable** (`pip install astra-cli-agent`) — everything left open is
+either a nice-to-have (LangSmith tracing needs a working key) or infra the user owns
+(kubernetes cluster for a handful of skipped tests).
 
 ---
 
@@ -1388,138 +1393,9 @@ running on every future `pytest -q`, whereas the manual checks in Phases 3–16
 ~~17. Full test pass — integration + e2e tests (`tests/integration/`, `tests/e2e/`).~~ —
     **done, see Phase 17 above.**
 ~~18. Packaging/CI/CD — GitHub Actions (`.github/workflows/`), PyPI trusted-publishing release
-    automation.~~ — **code-complete, see Phase 18 above. Not yet proven against real GitHub/PyPI
-    infrastructure — no remote pushed yet, no trusted publisher registered on PyPI yet.**
-
----
-
-## 5. Post-Phase-18 addendum (2026-07-11): CI verified live, PyPI rename, first-run onboarding
-
-This session found Phase 18's "known gap" note (§4 above, "CI never run on real GitHub
-infrastructure") was **stale** — a remote had since been added and pushed outside of a
-tracked phase. Checked directly: `git remote -v` shows `origin` →
-`github.com/Subharjun/astra-cli` (private), `git log` shows two commits already pushed to
-`main`, and `gh run list` shows both pushes triggered a real `CI` workflow run on GitHub's
-infrastructure — both green. **Nothing left to do for CI itself.** Whoever picks this up
-next should open PRs against `main` going forward rather than pushing directly, now that
-CI is live and would actually gate them.
-
-**PyPI blocker found and resolved**: `astra-cli` (the name Phase 18 assumed would be
-registered) is already taken on PyPI by an unrelated project (a different "Astra agent
-framework" CLI, owned by a different PyPI user). Confirmed via `curl
-https://pypi.org/pypi/astra-cli/json` returning a real, different project's metadata, not
-a 404. **Renamed the PyPI distribution name to `astra-cli-agent`** (confirmed available via
-a 404 check first) in `pyproject.toml`'s `[project].name` — **the installed console command
-stays `astra`** (`[project.scripts]` unchanged), so this is a packaging-metadata-only
-rename, not a UX change. `docs/ARCHITECTURE.md`'s install-target line and `README.md`
-updated to match; `.github/workflows/release.yml` needed no changes since it reads the name
-from `pyproject.toml` rather than hardcoding it. **Still needs a human**: registering
-`astra-cli-agent` on PyPI, adding the trusted-publisher entry (repo + `release.yml` +
-`pypi` environment name), and creating the `pypi` GitHub Environment — none of that is
-executable from inside a coding session. Step-by-step instructions for that are now in
-README.md's "Releasing (maintainers)" section.
-
-**New: `astra setup` — first-run provider onboarding**, the same "prompt for what's needed
-before doing anything else" pattern other terminal AI CLIs use, since Astra previously just
-failed with a raw `AllProvidersFailedError` if no `.env` had been hand-edited yet.
-- `core/onboarding.py`: `configured_providers()` (which of `GROQ_API_KEY`/
-  `ANTHROPIC_API_KEY`/`OPENAI_API_KEY` are non-empty in the environment) and
-  `is_provider_configured()`. Ollama needs no key, so a completed wizard run always writes
-  an `ASTRA_SETUP_COMPLETE=true` marker to `~/.astra/.env` regardless of which provider was
-  chosen — otherwise an Ollama-only setup would trigger onboarding forever.
-- `cli/setup.py`: `astra setup` — an interactive loop over Groq/Anthropic/OpenAI/Ollama.
-  For a cloud provider, the key is tested with one real, cheap completion call
-  (`temperature=0, max_tokens=5`, "reply with exactly: ok") **before** being saved, using
-  the same `LiteLLMClient`/`OllamaClient` adapters the real router uses — not a separate
-  validation path that could drift from what actually works. A failed test doesn't silently
-  discard the key; the user is asked whether to save it anyway (e.g. a transient network
-  blip). `_write_env_vars()` updates `~/.astra/.env` in place, preserving unrelated lines
-  and replacing an existing key rather than duplicating it, and applies the same values to
-  `os.environ` immediately so the rest of that process sees them with no restart needed.
-  Loops until the user declines "configure another provider" (recommended, since
-  `FallbackRouter` only has something to fall back to if more than one is configured).
-- `ensure_provider_or_prompt()` is called at the top of `ask`, `run` (i.e. `astra
-  "<prompt>"`), and `chat` — the three commands that actually make an LLM call — before
-  they touch the graph/router at all. If nothing is configured, it offers to run the wizard
-  right there (`typer.confirm`, default yes); declining prints how to run `astra setup`
-  later and exits cleanly (code 1) instead of a raw provider-chain stack trace. `hello`
-  deliberately does **not** force this (it's meant to stay a side-effect-free sanity check)
-  — it now just reports provider status passively (`LLM provider configured: groq` or a
-  yellow "run astra setup" nudge).
-- `"setup"` added to `cli/app.py`'s `_KNOWN_COMMANDS` (same manual-upkeep gotcha flagged in
-  §3 — every new top-level command needs an entry here or `resolve_argv` mis-rewrites it).
-
-Tests: `tests/unit/test_onboarding.py` (5, pure env-var logic), `tests/unit/test_setup.py`
-(12, `monkeypatch`-injected fake `LiteLLMClient`/`OllamaClient` + a `typer.prompt`/
-`typer.confirm` fake-queue harness + a `tmp_path`-redirected `USER_CONFIG_DIR` — covering
-the env-file write/preserve/replace behavior, a working-key save, a bad-key decline, a
-bad-key "save anyway", Ollama configuration, an empty-key skip, the full wizard's
-save-marker-after-one-provider path, and all three `ensure_provider_or_prompt` branches),
-plus one new case in `tests/unit/test_cli.py` (`setup` recognized by `resolve_argv`). Full
-suite: 289 passed + 36 skipped (unchanged kubernetes-cluster skip count), `ruff check .` and
-`mypy src` (strict) both clean.
-
-**Verified live** (real Groq calls, two disposable `$HOME` sandboxes, never touching the
-real `~/.astra`): direct call to `_test_cloud_provider("groq", ...)` with the real key from
-this repo's `.env` → genuine `'ok'` response, proving the wizard's key-test path itself
-works against the real API, not just mocked tests. Full interactive wizard end-to-end via a
-piped-stdin `astra setup` run against a real Groq key in a fresh sandbox `$HOME` → real
-`✓ got a real response from groq/llama-3.3-70b-versatile: 'ok'`, key + completion marker
-written to that sandbox's `~/.astra/.env`. Separately, `astra ask "hello"` in a **different**
-fresh sandbox `$HOME` with zero providers configured → the auto-prompt fired
-("No LLM provider is configured yet... Run the setup wizard now?"), walked through the full
-wizard with a deliberately invalid key, correctly reported the real Groq `invalid_api_key`
-error, saved it anyway on user confirmation, then proceeded to actually attempt the real
-request — which failed for the expected reason (bad key) with the real
-`AllProvidersFailedError` chain, proving `ensure_provider_or_prompt()` actually gates the
-call rather than just running cosmetically. `astra hello` confirmed to report
-`LLM provider configured: groq` correctly in this repo's own already-configured environment
-without prompting (passive path).
-
-**Caught by real CI, not by local testing**: pushing the onboarding change broke 8 of the
-10 `tests/integration/` tests on GitHub's runner (green locally beforehand) —
-`ensure_provider_or_prompt()` only checks provider API-key env vars, so it didn't know
-`patch_router()` (the integration suite's helper for swapping in a `FakeRouter`) had
-already made the pipeline fully working; it blocked on a real `typer.confirm` prompt with
-no piped stdin and aborted. Invisible locally because this repo's own `.env` (real Groq
-key, gitignored) always made `is_provider_configured()` true regardless of the bug —
-GitHub's runner has no such file, by design (§4 item 15/CI notes: no `GROQ_API_KEY` secret
-configured, deliberately, so CI never spends real API money). Fixed by having
-`tests/integration/_helpers.py`'s `patch_router()` also `monkeypatch.setenv("GROQ_API_KEY",
-"test-fake-key")` — it's already simulating a working provider, so the gate should see one
-too. Reverified **the actual failure mode**, not just the fix, by temporarily moving this
-repo's real `.env` aside and re-running `tests/integration/` in a fresh `$HOME`: all 10
-failed the same way pre-fix, all 10 passed post-fix — then pushed again and confirmed the
-real GitHub Actions run went green. This is exactly the kind of gap `tests/integration/`
-(Phase 17) exists to catch and mostly did — except a gate that behaves differently based on
-ambient env state needs either a credential-free CI runner (which this repo already has) or
-a local repro with the same env, and this session's first local check used the wrong one.
-
-⚠️ **Unrelated pre-existing issue noticed, not fixed (out of scope for this session)**:
-during the bad-key live test above, the fallback chain's `anthropic` attempt failed with
-`litellm.UnsupportedParamsError: claude-sonnet-5 does not support temperature=0.2. Only
-temperature=1 is supported.` — `defaults.yaml`'s `llm.temperature: 0.2` default is
-incompatible with the `claude-sonnet-5` model name in the same file's fallback chain.
-Whoever next touches `llm/router.py` or `config/defaults.yaml` should either drop
-`temperature` for Anthropic calls or pin a different default model — flagging here so it
-isn't mistaken for something this session broke.
-
-All 18 phases from the architecture doc's phase list are now built. What's left:
-1. ~~**Prove `ci.yml` actually runs**~~ — **closed in §8**: a GitHub remote now exists
-   (`https://github.com/Subharjun/astra-cli`, private), pushed, and the push-triggered `ci.yml`
-   run went fully green on real GitHub-hosted infrastructure (checkout → Python 3.12 → `uv`
-   install → ruff → mypy → pytest, 3m32s). See §8 for the run details.
-2. **Prove `release.yml` actually publishes**: register `astra-cli` as a PyPI project, add a
-   trusted publisher entry pointing at this repo (see Phase 18's section above for the exact
-   fields needed), create the `pypi` GitHub Environment, then cut a real `v0.1.0` GitHub Release
-   and confirm the package actually lands on PyPI.
-3. **Live-verify Phase 15's LangSmith tracing** if a working `lsv2_...` key turns up — both keys
-   tried in that session were rejected with `403 Forbidden`, so this is still only code-complete,
-   not confirmed working end-to-end.
-
-Neither remaining item blocks calling the project "done" in the sense the original 18-phase plan
-meant — they're external-account-setup steps (PyPI trusted-publisher registration, a valid
-LangSmith key) that fall outside what a coding session alone can complete.
+    automation.~~ — **fully proven, not just code-complete — see §8 (CI verified live on real
+    GitHub infrastructure) and §9/§10 (PyPI package actually published and installable as
+    `astra-cli-agent`, real GitHub Releases cut for v0.1.0/v0.1.1/v0.1.2).**
 
 ---
 
@@ -1750,3 +1626,290 @@ credential-blocked live search test now passes for real instead of skipping), `r
 
 **Verified live**: `gh run list` / `gh run watch` against the real run — every step (`Ruff`,
 `Mypy`, `Pytest`) shows a genuine ✓ from the GitHub-hosted runner.
+
+---
+
+## 9. Post-Phase-18 addendum (2026-07-11): CI verified live, PyPI rename, first-run onboarding
+
+This session found Phase 18's "known gap" note (§4 above, "CI never run on real GitHub
+infrastructure") was **stale** — a remote had since been added and pushed outside of a
+tracked phase. Checked directly: `git remote -v` shows `origin` →
+`github.com/Subharjun/astra-cli` (private), `git log` shows two commits already pushed to
+`main`, and `gh run list` shows both pushes triggered a real `CI` workflow run on GitHub's
+infrastructure — both green. **Nothing left to do for CI itself.** Whoever picks this up
+next should open PRs against `main` going forward rather than pushing directly, now that
+CI is live and would actually gate them.
+
+**PyPI blocker found and resolved**: `astra-cli` (the name Phase 18 assumed would be
+registered) is already taken on PyPI by an unrelated project (a different "Astra agent
+framework" CLI, owned by a different PyPI user). Confirmed via `curl
+https://pypi.org/pypi/astra-cli/json` returning a real, different project's metadata, not
+a 404. **Renamed the PyPI distribution name to `astra-cli-agent`** (confirmed available via
+a 404 check first) in `pyproject.toml`'s `[project].name` — **the installed console command
+stays `astra`** (`[project.scripts]` unchanged), so this is a packaging-metadata-only
+rename, not a UX change. `docs/ARCHITECTURE.md`'s install-target line and `README.md`
+updated to match; `.github/workflows/release.yml` needed no changes since it reads the name
+from `pyproject.toml` rather than hardcoding it. **Still needs a human**: registering
+`astra-cli-agent` on PyPI, adding the trusted-publisher entry (repo + `release.yml` +
+`pypi` environment name), and creating the `pypi` GitHub Environment — none of that is
+executable from inside a coding session. Step-by-step instructions for that are now in
+README.md's "Releasing (maintainers)" section.
+
+**New: `astra setup` — first-run provider onboarding**, the same "prompt for what's needed
+before doing anything else" pattern other terminal AI CLIs use, since Astra previously just
+failed with a raw `AllProvidersFailedError` if no `.env` had been hand-edited yet.
+- `core/onboarding.py`: `configured_providers()` (which of `GROQ_API_KEY`/
+  `ANTHROPIC_API_KEY`/`OPENAI_API_KEY` are non-empty in the environment) and
+  `is_provider_configured()`. Ollama needs no key, so a completed wizard run always writes
+  an `ASTRA_SETUP_COMPLETE=true` marker to `~/.astra/.env` regardless of which provider was
+  chosen — otherwise an Ollama-only setup would trigger onboarding forever.
+- `cli/setup.py`: `astra setup` — an interactive loop over Groq/Anthropic/OpenAI/Ollama.
+  For a cloud provider, the key is tested with one real, cheap completion call
+  (`temperature=0, max_tokens=5`, "reply with exactly: ok") **before** being saved, using
+  the same `LiteLLMClient`/`OllamaClient` adapters the real router uses — not a separate
+  validation path that could drift from what actually works. A failed test doesn't silently
+  discard the key; the user is asked whether to save it anyway (e.g. a transient network
+  blip). `_write_env_vars()` updates `~/.astra/.env` in place, preserving unrelated lines
+  and replacing an existing key rather than duplicating it, and applies the same values to
+  `os.environ` immediately so the rest of that process sees them with no restart needed.
+  Loops until the user declines "configure another provider" (recommended, since
+  `FallbackRouter` only has something to fall back to if more than one is configured).
+- `ensure_provider_or_prompt()` is called at the top of `ask`, `run` (i.e. `astra
+  "<prompt>"`), and `chat` — the three commands that actually make an LLM call — before
+  they touch the graph/router at all. If nothing is configured, it offers to run the wizard
+  right there (`typer.confirm`, default yes); declining prints how to run `astra setup`
+  later and exits cleanly (code 1) instead of a raw provider-chain stack trace. `hello`
+  deliberately does **not** force this (it's meant to stay a side-effect-free sanity check)
+  — it now just reports provider status passively (`LLM provider configured: groq` or a
+  yellow "run astra setup" nudge).
+- `"setup"` added to `cli/app.py`'s `_KNOWN_COMMANDS` (same manual-upkeep gotcha flagged in
+  §3 — every new top-level command needs an entry here or `resolve_argv` mis-rewrites it).
+
+Tests: `tests/unit/test_onboarding.py` (5, pure env-var logic), `tests/unit/test_setup.py`
+(12, `monkeypatch`-injected fake `LiteLLMClient`/`OllamaClient` + a `typer.prompt`/
+`typer.confirm` fake-queue harness + a `tmp_path`-redirected `USER_CONFIG_DIR` — covering
+the env-file write/preserve/replace behavior, a working-key save, a bad-key decline, a
+bad-key "save anyway", Ollama configuration, an empty-key skip, the full wizard's
+save-marker-after-one-provider path, and all three `ensure_provider_or_prompt` branches),
+plus one new case in `tests/unit/test_cli.py` (`setup` recognized by `resolve_argv`). Full
+suite: 289 passed + 36 skipped (unchanged kubernetes-cluster skip count), `ruff check .` and
+`mypy src` (strict) both clean.
+
+**Verified live** (real Groq calls, two disposable `$HOME` sandboxes, never touching the
+real `~/.astra`): direct call to `_test_cloud_provider("groq", ...)` with the real key from
+this repo's `.env` → genuine `'ok'` response, proving the wizard's key-test path itself
+works against the real API, not just mocked tests. Full interactive wizard end-to-end via a
+piped-stdin `astra setup` run against a real Groq key in a fresh sandbox `$HOME` → real
+`✓ got a real response from groq/llama-3.3-70b-versatile: 'ok'`, key + completion marker
+written to that sandbox's `~/.astra/.env`. Separately, `astra ask "hello"` in a **different**
+fresh sandbox `$HOME` with zero providers configured → the auto-prompt fired
+("No LLM provider is configured yet... Run the setup wizard now?"), walked through the full
+wizard with a deliberately invalid key, correctly reported the real Groq `invalid_api_key`
+error, saved it anyway on user confirmation, then proceeded to actually attempt the real
+request — which failed for the expected reason (bad key) with the real
+`AllProvidersFailedError` chain, proving `ensure_provider_or_prompt()` actually gates the
+call rather than just running cosmetically. `astra hello` confirmed to report
+`LLM provider configured: groq` correctly in this repo's own already-configured environment
+without prompting (passive path).
+
+**Caught by real CI, not by local testing**: pushing the onboarding change broke 8 of the
+10 `tests/integration/` tests on GitHub's runner (green locally beforehand) —
+`ensure_provider_or_prompt()` only checks provider API-key env vars, so it didn't know
+`patch_router()` (the integration suite's helper for swapping in a `FakeRouter`) had
+already made the pipeline fully working; it blocked on a real `typer.confirm` prompt with
+no piped stdin and aborted. Invisible locally because this repo's own `.env` (real Groq
+key, gitignored) always made `is_provider_configured()` true regardless of the bug —
+GitHub's runner has no such file, by design (§4 item 15/CI notes: no `GROQ_API_KEY` secret
+configured, deliberately, so CI never spends real API money). Fixed by having
+`tests/integration/_helpers.py`'s `patch_router()` also `monkeypatch.setenv("GROQ_API_KEY",
+"test-fake-key")` — it's already simulating a working provider, so the gate should see one
+too. Reverified **the actual failure mode**, not just the fix, by temporarily moving this
+repo's real `.env` aside and re-running `tests/integration/` in a fresh `$HOME`: all 10
+failed the same way pre-fix, all 10 passed post-fix — then pushed again and confirmed the
+real GitHub Actions run went green. This is exactly the kind of gap `tests/integration/`
+(Phase 17) exists to catch and mostly did — except a gate that behaves differently based on
+ambient env state needs either a credential-free CI runner (which this repo already has) or
+a local repro with the same env, and this session's first local check used the wrong one.
+
+⚠️ **Unrelated pre-existing issue noticed, not fixed (out of scope for this session)**:
+during the bad-key live test above, the fallback chain's `anthropic` attempt failed with
+`litellm.UnsupportedParamsError: claude-sonnet-5 does not support temperature=0.2. Only
+temperature=1 is supported.` — `defaults.yaml`'s `llm.temperature: 0.2` default is
+incompatible with the `claude-sonnet-5` model name in the same file's fallback chain.
+Whoever next touches `llm/router.py` or `config/defaults.yaml` should either drop
+`temperature` for Anthropic calls or pin a different default model — flagging here so it
+isn't mistaken for something this session broke.
+
+All 18 phases from the architecture doc's phase list are now built. What's left:
+1. ~~**Prove `ci.yml` actually runs**~~ — **closed in §8**: a GitHub remote now exists
+   (`https://github.com/Subharjun/astra-cli`, private), pushed, and the push-triggered `ci.yml`
+   run went fully green on real GitHub-hosted infrastructure (checkout → Python 3.12 → `uv`
+   install → ruff → mypy → pytest, 3m32s). See §8 for the run details.
+2. ~~**Prove `release.yml` actually publishes**~~ — **closed in §10**: the user registered
+   `astra-cli-agent` (not `astra-cli` — see the PyPI-blocker paragraph above) as a PyPI pending
+   publisher and created the `pypi` GitHub Environment; `v0.1.0` was tagged and released, and
+   the package landed on PyPI for real, confirmed via a fresh-venv `pip install`. See §10.
+3. **Live-verify Phase 15's LangSmith tracing** if a working `lsv2_...` key turns up — both keys
+   tried in that session were rejected with `403 Forbidden`, so this is still only code-complete,
+   not confirmed working end-to-end. **Still open** as of §10.
+
+Neither remaining item blocks calling the project "done" in the sense the original 18-phase plan
+meant — they're external-account-setup steps (PyPI trusted-publisher registration, a valid
+LangSmith key) that fall outside what a coding session alone can complete.
+
+---
+
+## 10. Public release (2026-07-11): PyPI v0.1.0–v0.1.2 shipped, public README repo, big banner
+
+Continuation of §9 in the same calling session. §9 left two things pending on the user: register
+`astra-cli-agent` as a PyPI pending publisher, and create the `pypi` GitHub Environment. Both
+confirmed done — `gh api repos/Subharjun/astra-cli/environments` showed a real `pypi` environment
+(created `2026-07-11T11:57:25Z`, no protection rules).
+
+### v0.1.0: first real PyPI publish
+
+- Tagged `v0.1.0`, pushed the tag, `gh release create v0.1.0 --generate-notes` — publishing that
+  Release fired `release.yml` for real. Green on the first try (`build` → sdist+wheel →
+  `publish` via PyPI trusted-publishing/OIDC, no token anywhere in the repo).
+- **Verified live, not just "the workflow said success"**: fresh `python3 -m venv` +
+  `pip install astra-cli-agent` from the real public index, `astra version` → `astra 0.1.0`,
+  `astra hello`, `astra --help` all worked, including the onboarding nudge
+  ("No LLM provider configured yet. Run astra setup to get started.") firing correctly for a
+  genuinely fresh install.
+- Downloaded the actual published wheel from `files.pythonhosted.org` and grepped its contents
+  for `.env`/secret/key patterns — zero matches, confirming no credentials ship in the package
+  (the user asked directly whether this was possible; answered from direct inspection, not
+  inference).
+
+### Public-repo privacy discussion, and what actually got built
+
+The user wants the source private but still wants a public, installable package. Clarified for
+the record: the private GitHub repo (`Subharjun/astra-cli`) staying private does **not** make the
+PyPI package private — PyPI is a public index, and the wheel/sdist contain full `.py` source
+regardless of GitHub visibility, since Python isn't compiled/obfuscated. There is no "private
+PyPI project with public `pip install`" without a separate private index (Gemfury/Cloudsmith/
+self-hosted devpi) or installing straight from the private GitHub repo via `pip install
+git+https://...`. Presented these options; **user chose to publish to PyPI anyway** (source
+downloadable via `pip download`/wheel inspection is an accepted tradeoff) but wanted the
+**GitHub side to show a separate public repo containing only usage instructions, not source**.
+
+- Created `Subharjun/astra-cli-agent` as a new public GitHub repo (separate from the private
+  `Subharjun/astra-cli`, which stays the real working repo and stays private).
+- **First attempt was wrong and had to be corrected**: initially pushed the *entire* private
+  repo's history (all source, all commits, the `v0.1.0` tag) to the new public repo — a
+  misreading of "public repo" as "public mirror." User corrected explicitly: *"no no public repo
+  just readme.md file no other just instructions."*
+- **Fix**: deleted the `v0.1.0` tag from the public repo. Attempted `gh repo delete` to start
+  clean, but `gh`'s token lacks the `delete_repo` scope, and granting it requires an interactive
+  browser OAuth step this non-interactive session can't complete (`gh auth refresh -h github.com
+  -s delete_repo` needs a device-code confirmation in a browser). Instead, sanitized the existing
+  repo: built a fresh orphan git history (`git init` in a scratch dir, one commit containing only
+  `README.md`) and `git push --force` to replace `main` entirely. Verified after the fact via the
+  GitHub API: `main` has exactly 1 commit, `contents/` lists only `README.md`, zero other
+  branches, zero tags. ⚠️ **Known residual caveat, disclosed to the user**: force-replacing history
+  makes the old source-containing commit unreachable from any ref (so it won't appear anywhere in
+  GitHub's UI/history), but without the `delete_repo`+recreate path there's no hard guarantee
+  GitHub has garbage-collected the underlying git objects yet — a direct-SHA lookup could
+  theoretically still resolve for some window. Full delete+recreate remains the only airtight fix,
+  and needs the user (or a session with `delete_repo` scope granted interactively) to do it.
+- The public repo's `README.md` is a trimmed variant of the main README: badges (PyPI version +
+  Python version only — no CI badge, since no workflow lives in this repo; no license badge/file,
+  since "no other files" was explicit), the same feature table, install/quickstart/config/MCP
+  sections, no "Contributing/development" section (there's no source here to clone/build).
+
+### README beautification + LICENSE + pyproject metadata (private repo)
+
+- `README.md` (private repo) rewritten: leads with badges (PyPI version, Python version, CI
+  status, MIT license), a feature table per agent domain (git/filesystem/shell/docker/k8s/web/
+  debug/docs/MCP), a proper quickstart walking through `astra setup` → example commands → the
+  confirmation-gate behavior, an MCP-server config example, and a "Contributing/development"
+  section — replacing the old stub that just said "early scaffold" and listed two commands.
+- Added `LICENSE` (MIT) — `pyproject.toml` had declared `license = { text = "MIT" }` since Phase 2
+  but no `LICENSE` file had ever actually been created; added now that the project has real public
+  surface area.
+- Added `[project.urls]` (`Homepage`, `Issues`) to `pyproject.toml`, pointing at the new public
+  `astra-cli-agent` GitHub repo — no `Repository` key, since that repo is README-only and calling
+  it "the repository" would be misleading about where the source actually lives.
+- **Real build-breaking bug caught by CI, not locally**: the first `[project.urls]` edit placed
+  the table header *before* the existing `dependencies = [...]` list inside `[project]` — in TOML,
+  a table header ends the previous table, so `dependencies` silently became a key under
+  `[project.urls]` instead of `[project]`. `hatchling` rejected this outright at build time
+  (`TypeError: URL 'dependencies' of field 'project.urls' must be a string`), breaking `pip
+  install`/`uv pip install -e .` entirely. Invisible locally because the dev venv already had the
+  package installed from before the bad edit — first surfaced when CI ran `uv pip install --system
+  -e ".[dev]"` from scratch on the newly-created public-repo push and failed at the install step.
+  Fixed by moving `[project.urls]` after `[project.optional-dependencies]`; reverified with a real
+  `uv pip install -e ".[dev]"` from scratch plus the full test suite before pushing again.
+
+### Big ASCII banner (user-requested: "make it appear big... typer or rich")
+
+User feedback: the CLI's presence "doesn't feel like Claude" and asked for something bigger, using
+Typer or Rich. `print_banner()` previously wrapped the word "Astra" in a one-line-tall bordered
+`Panel` — replaced with a real figlet wordmark:
+
+- New runtime dependency `pyfiglet` (pure Python, zero transitive deps) — lazy-imported inside
+  `print_banner()`, same "pay for it only where it's used" convention `litellm`/
+  `sentence-transformers`/`mcp` already follow, since only three interactive commands need it.
+- `cli/rendering.py`: `print_banner()` now renders `pyfiglet.figlet_format("ASTRA", font="slant")`
+  as a Rich `Text`, coloring each line with a fixed cyan→violet gradient (`_BANNER_GRADIENT`,
+  5 hex stops, purely cosmetic — no meaning attached to the specific colors), followed by the
+  "your terminal AI developer assistant" tagline in dim italic.
+- Wired into `hello` and `setup` (already had the old banner) and **newly into `cli/chat.py`'s
+  `run_chat()`** startup, which previously printed only a plain one-line `"Astra chat"` label with
+  no banner at all.
+- Deliberately **not** added to `ask`/`run` (`astra "<prompt>"`) — those are also used
+  non-interactively/scripted/piped, and a multi-line ASCII banner on every scripted invocation
+  would be noise, not polish.
+
+### Shipped as v0.1.1 — then a real bug found in production, fixed as v0.1.2
+
+- Bumped `pyproject.toml` to `0.1.1`, tagged, released — `release.yml` published it for real.
+- **Live-verified in a fresh venv, and this is what caught the bug**: `astra hello` showed the new
+  banner correctly, but `astra version` printed `astra 0.1.0` — one version behind what was just
+  explicitly installed (`pip install astra-cli-agent==0.1.1`).
+- **Root cause**: `src/astra/__init__.py`'s `__version__` was a hardcoded string literal,
+  completely disconnected from `pyproject.toml`'s `version` field — nothing had ever wired them
+  together, all the way back to Phase 2. It happened to read `"0.1.0"` and nobody had bumped it
+  during any of the version changes this session, since local dev testing via `pip install -e .`
+  never surfaces the mismatch the way a real "install a specific released version and check what
+  it reports" test does.
+- **Fixed properly, not just patched for this one instance**: `__version__` now resolves via
+  `importlib.metadata.version("astra-cli-agent")` at import time (falls back to a hardcoded
+  constant only if run from a source checkout with no installed distribution metadata at all,
+  which shouldn't happen via any normal install path). This makes future drift structurally
+  impossible for anyone who installs the package normally — `astra version` will always match
+  whatever's actually installed.
+- Bumped to `0.1.2`, tagged, released, published. **Live-verified again** in a completely fresh
+  venv (`pip install astra-cli-agent==0.1.2`): `astra version` → `astra 0.1.2` correctly, banner
+  renders correctly. This is the version currently live and correct on PyPI.
+
+### Verification discipline held throughout
+
+Every step in this section (banner change, LICENSE/README/pyproject edits, the TOML bug fix, the
+`__version__` fix) went through the same loop before being pushed: local `ruff check .` + `mypy
+src` (strict) + `pytest -q` all green (**289 passed, 36 skipped**, unchanged kubernetes-cluster
+skip count throughout), push, wait for real GitHub Actions CI to go green, *then* proceed — never
+assumed a fix worked from local state alone once a real CI failure had already been observed once
+this session (the `[project.urls]` TOML bug). Every PyPI publish was confirmed with a genuinely
+fresh `python3 -m venv` + `pip install` from the real index, not just "the release workflow
+reported success."
+
+### Housekeeping: this document's own section numbering
+
+This session found a pre-existing numbering collision in this very file: an earlier addendum had
+been inserted as "## 5. Post-Phase-18 addendum," directly colliding with an already-existing,
+differently-scoped "## 5. Environment state" section further down (itself part of an older
+5→6→7→8 sequence: Environment state, Working agreements, the post-18 hardening pass, and the
+web-search/GitHub-push section). Fixed by relocating that addendum to become **§9** (after §8,
+where it chronologically belongs — it discovered/confirmed work §8 had already done), and this
+section is **§10**. `§1`–`§8`'s existing numbers and every cross-reference to them elsewhere in
+this document were left untouched to avoid a much larger, riskier rewrite across ~1700 lines;
+only the previously-misnumbered/misplaced section was moved and renumbered.
+
+**Final state as of this section**: all 18 phases built (§2), all known simplifications tracked
+(§3) with six closed in §7 and more in §9/§10, CI proven live on real GitHub infrastructure (§8),
+`astra-cli-agent` actually published and installable from PyPI at `v0.1.2` (this section),
+first-run provider onboarding shipped (§9), and a real ASCII-logo presence shipped (this
+section). Remaining open items are genuinely external: a working LangSmith key (§9 item 3) and,
+per §5's environment notes, a local kubernetes cluster to un-skip a handful of tests — neither
+blocks calling this project done and publicly usable.

{astra_cli_agent-0.1.2 → astra_cli_agent-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: astra-cli-agent
-Version: 0.1.2
+Version: 0.1.3
 Summary: Astra — a terminal AI assistant that understands natural language and drives your dev tools.
 Project-URL: Homepage, https://github.com/Subharjun/astra-cli-agent
 Project-URL: Issues, https://github.com/Subharjun/astra-cli-agent/issues
@@ -63,7 +63,7 @@ wrapping a shell call.
 
 | Domain | Agent | Capabilities |
 |---|---|---|
-| Git | `GitAgent` | status, diff, log, blame, branch, commit (auto-generates messages), push, merge, checkout, stash |
+| Git | `GitAgent` | status, diff, log, blame, branch, commit (auto-generates messages), push, merge, checkout, stash, plus GitHub API: create/delete repos, issues, pull requests (needs `GITHUB_TOKEN`) |
 | Filesystem & code | `FileAgent` | read/write/move/delete files, lint & format (`ruff`), run tests (`pytest`), symbol search |
 | Shell | `FileAgent` | runs arbitrary commands behind a hard denylist + confirmation gate |
 | Docker | `DockerAgent` | ps, images, build, run, logs, exec, inspect, rm/rmi, prune |
@@ -73,6 +73,27 @@ wrapping a shell call.
 | Documentation | `DocumentationAgent` | writes docstrings, README sections, usage guides |
 | MCP | `MCPAgent` | connects to any configured MCP server (stdio, HTTP, or SSE) and discovers/calls its tools |
 
+**Example prompts by domain** — every one of these routes automatically, no flags needed
+beyond `--yes` for anything risky:
+
+| Domain | Example prompt |
+|---|---|
+| Git | `astra "what's the git status here, and diff the uncommitted changes"` |
+| Git | `astra "commit my staged changes with a good message" --yes` |
+| Git | `astra "list the open issues on this github repo"` (needs `GITHUB_TOKEN`) |
+| Filesystem & code | `astra "create a file called notes.md with a todo list"` |
+| Filesystem & code | `astra "run the linter and the test suite on this project"` |
+| Shell | `astra "run df -h and tell me how much disk space is free" --yes` |
+| Docker | `astra "list all running docker containers"` |
+| Docker | `astra "build a docker image from the Dockerfile in this directory" --yes` |
+| Kubernetes | `astra "list the pods in the default namespace"` |
+| Kubernetes | `astra "scale the api deployment to 3 replicas" --yes` |
+| Web research | `astra "search stack overflow for how to fix a detached HEAD in git"` |
+| Web research | `astra "find github repos for a python rate limiter library"` |
+| Debugging | `astra "here's a stack trace, find the root cause and propose a fix: <paste>"` |
+| Documentation | `astra "write a README section documenting the config file format"` |
+| MCP | `astra "list the tools available from my configured MCP servers"` |
+
 Also included:
 
 - **Safety by default** — risky operations (`git push`, file delete, shell, container/exec
@@ -88,7 +109,9 @@ Also included:
 - **Cost/token tracking** — `astra memory costs` shows a real per-provider/per-model
   breakdown and daily spend trend, no external service required.
 - **First-run onboarding** — `astra setup` walks you through picking a provider and tests
-  your key with a real request before saving it.
+  your key with a real request before saving it. Optionally continues into GitHub API
+  (`GITHUB_TOKEN`) and general web search (`SERPAPI_KEY`) setup, same real-tested-before-saved
+  flow.
 
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full design and
 [HANDOFF.md](HANDOFF.md) for exactly what's built, what's tested, and what's left.
@@ -131,6 +154,11 @@ is the fastest way to try Astra.
 If you skip this step, the first command that actually needs an LLM (`ask`, a bare prompt,
 or `chat`) will offer to run the wizard for you automatically.
 
+The wizard then offers an optional second stage for feature-unlocking keys — a GitHub
+personal access token (`GITHUB_TOKEN`, for the `github_*` tools) and a SerpApi key
+(`SERPAPI_KEY`, for general web search) — same real-request-before-saving flow, skippable,
+default no. Run `astra setup` again any time to add these later.
+
 Then just talk to it — **from inside whatever project directory you want it to act on**,
 since every tool call is scoped to your current working directory:
 
@@ -185,6 +213,34 @@ mcp:
 
 `astra mcp tools` lists everything discovered from your configured servers.
 
+## All commands
+
+Beyond natural-language prompts, every subcommand below is a direct, non-LLM entrypoint:
+
+```bash
+astra hello                       # install/config/provider sanity check
+astra version                     # print the installed version
+astra setup                       # interactive onboarding wizard (LLM provider + optional integrations)
+astra ask "<prompt>"              # one-shot LLM call, bypasses the agent pipeline
+astra chat                        # interactive REPL with streaming + history
+astra ingest [path]               # index a codebase for retrieval (defaults to .)
+
+astra memory history [-n N]       # recent conversation history
+astra memory clear                # wipe conversation history
+astra memory costs                # per-provider/per-model cost & token breakdown
+astra memory projects             # list ingested (RAG-indexed) projects
+astra memory search "<query>"     # test retrieval directly against an ingested project
+astra memory prefs set <k> <v>    # store a preference
+astra memory prefs get <k>        # read a preference
+astra memory prefs list           # list all preferences
+
+astra mcp servers                 # list configured MCP servers
+astra mcp tools                   # list tools discovered from configured MCP servers
+```
+
+Any bare prompt (`astra "..."`) or `astra run "<prompt>"` triggers the full
+router→planner→execute→reviewer→memory pipeline described above.
+
 ## Contributing / development
 
 ```bash