Introduce bb CLI namespace

.ai-context/ARCHITECTURE.md

@@ -5,6 +5,8 @@
 - `src/bankbuddy/` contains banking domain code, the `bankbuddy` CLI, shared
   runtime helpers, SQLite access, migrations, importers, reports, and storage
   layout code.
+- `src/bankbuddy/bb/` contains the side-by-side v2 source namespace for new
+  `BB_` schema DAOs, records, and the `bb` CLI.
 - `src/bankbuddy/tax/` contains the TaxBuddy document-readiness slice.
 - `src/bankbuddy/migrations/` contains ordered SQL migrations.
 - `tests/` contains pytest coverage and `tests/validate.sh`.
@@ -84,8 +86,10 @@ future work unless a focused issue says otherwise.
 
 ## Financial Intelligence V2 Direction
 
-The accepted v2 direction keeps the product and CLI name as `bankbuddy` while
-moving the long-term architecture toward `Document`, `Entity`, `Observation`,
+The accepted v2 direction keeps the product name as BankBuddy while introducing
+the short `bb` CLI and `bankbuddy.bb` source namespace for new v2 work. Existing
+`bankbuddy` and `taxbuddy` command surfaces stay intact during the transition.
+The long-term architecture moves toward `Document`, `Entity`, `Observation`,
 and `Relationship` foundations. New schema proposals use `BB_`-prefixed
 singular table names and prefer normalized relational tables over JSON blobs.
 

.ai-context/COMMANDS.md

@@ -9,6 +9,7 @@ basectl setup bankbuddy
 basectl check bankbuddy
 basectl doctor bankbuddy
 basectl test bankbuddy
+basectl run bankbuddy bb -- status
 basectl run bankbuddy bankbuddy -- status
 basectl run bankbuddy taxbuddy -- status
 basectl activate bankbuddy
@@ -26,6 +27,19 @@ into `uv run` through `runner: uv`.
 `basectl activate bankbuddy` enters a project shell and sources
 `.base/activate.sh`, which defaults `BANKBUDDY_ENV=dev` when unset.
 
+## bb CLI
+
+Run the v2 financial intelligence CLI with:
+
+```bash
+bb --help
+bb status
+```
+
+`bb` is the side-by-side command surface for new `BB_` schema work. It should
+grow new document/entity/observation workflows while the legacy command
+surfaces remain available.
+
 ## BankBuddy CLI
 
 Run the banking CLI with:

.ai-context/STATUS.md

@@ -14,6 +14,8 @@ section is `Unreleased`.
 - Local data homes for `prod`, `dev`, and named environments.
 - Banking CLI commands for banks, accounts, statement refs, imports,
   transactions, categories, reports, exports, storage migration, and status.
+- Side-by-side `bb` CLI for v2 financial intelligence foundation status and
+  `BB_` schema visibility.
 - Supported banking imports for Bank of America PDF/CSV, Apple Card PDF, ICICI
   `.xls`, and HDFC `.xls`.
 - Statement inventory and statement coverage auditing.
@@ -26,6 +28,8 @@ section is `Unreleased`.
   while moving the target model toward documents, entities, observations, and
   relationships. Active design docs are the vision, architecture, and open
   questions documents.
+- Additive `bankbuddy.bb` source namespace and `bb` console script for v2 work,
+  leaving existing `bankbuddy` and `taxbuddy` commands in place.
 - Prospective relicensing from MIT to AGPL-3.0-or-later.
 - Canonical data-home layout with `database/`, `bank/`, and `tax/` directories.
 - First TaxBuddy CLI slice and `tax_documents` metadata index.

.ai-context/WORKFLOWS.md

@@ -33,6 +33,7 @@ The Base dogfood validation path is:
 ```bash
 basectl setup bankbuddy
 basectl test bankbuddy
+basectl run bankbuddy bb -- status
 basectl run bankbuddy bankbuddy -- status
 basectl run bankbuddy taxbuddy -- status
 ```

CHANGELOG.md

@@ -34,7 +34,10 @@ and versions are tracked in the repo-root `VERSION` file.
 
 - Added v2 financial document storage roots, document object metadata,
   generated human-readable document view metadata, path-resolution helpers,
-  and read-only managed-file guardrails under the `financial/` namespace.
+  and read-only managed-file guardrails under the `bankbuddy.bb` namespace.
+- Added the side-by-side `bb` console command and `bankbuddy.bb` source
+  namespace for financial intelligence v2 work, while leaving existing
+  `bankbuddy` and `taxbuddy` commands intact.
 - Added additive financial intelligence v2 foundation tables, seed type
   dictionaries, indexes, and DAO-based read/write helpers without dropping
   existing banking or tax tables.

README.md

@@ -29,6 +29,7 @@ basectl test bankbuddy
 Run uv-backed project commands through Base when you want one-command dispatch:
 
 ```bash
+basectl run bankbuddy bb -- status
 basectl run bankbuddy bankbuddy -- status
 basectl run bankbuddy taxbuddy -- status
 ```
@@ -42,6 +43,7 @@ Activate the project shell once, then run the CLI directly:
 
 ```bash
 basectl activate bankbuddy
+bb status
 bankbuddy --help
 bankbuddy status
 bankbuddy init
@@ -137,6 +139,11 @@ taxbuddy docs list --type 1099-INT
 taxbuddy docs show 1
 ```
 
+`bb` is the side-by-side v2 CLI for the financial intelligence foundation. It
+uses the additive `BB_` schema and `bankbuddy.bb` source namespace while the
+existing `bankbuddy` and `taxbuddy` commands remain available during the
+transition.
+
 ## Environments
 
 BankBuddy keeps separate local data homes for named environments. Outside an
@@ -147,6 +154,7 @@ which maps to `~/BankBuddy-dev`.
 Use `status` to confirm the active environment and database:
 
 ```bash
+bb status
 bankbuddy status
 ```
 

docs/financial_intelligence_architecture.md

@@ -11,7 +11,10 @@
 
 BankBuddy should evolve into the broader personal financial intelligence
 platform described in the product vision, while remaining in the existing
-BankBuddy repository and keeping the `bankbuddy` CLI name.
+BankBuddy repository and keeping BankBuddy as the product name. New v2 work
+should start behind the shorter `bb` CLI and the `bankbuddy.bb` source
+namespace so the existing `bankbuddy` and `taxbuddy` commands can keep working
+while the new model matures.
 
 The right target architecture is not a banking app with more tables. It is a
 local-first evidence graph:
@@ -34,7 +37,12 @@ need to be discarded just to make room for the new architecture.
 
 The following decisions define the current v2 direction:
 
-- Keep the product and CLI name as `bankbuddy`.
+- Keep the product name as BankBuddy.
+- Introduce `bb` as the side-by-side v2 CLI for financial intelligence
+  workflows. Keep the existing `bankbuddy` and `taxbuddy` commands intact until
+  the v2 command surface is stable enough for cleanup.
+- Put new v2 source files under `bankbuddy.bb` so new DAOs, domain records, and
+  CLI commands do not collide with legacy banking modules.
 - Use `Document`, `Entity`, `Observation`, and `Relationship` as the conceptual
   foundation, while allowing details to evolve during implementation.
 - Introduce the v2 foundation schema additively beside the existing legacy
@@ -942,6 +950,19 @@ This service is new and should be a first-class workflow, not an afterthought.
 
 ## 8. Proposed Package and Module Structure
 
+Near-term v2 code should live in a side-by-side namespace:
+
+```text
+src/bankbuddy/
+  bb/
+    cli.py
+    dao.py
+    records.py
+```
+
+This namespace is intentionally small at first. It gives v2 work a clean home
+without forcing a broad package refactor before the model is proven.
+
 Target structure:
 
 ```text
@@ -1035,49 +1056,51 @@ This can be reached gradually. Do not move everything in one PR.
 
 ## 9. Proposed CLI Evolution
 
-The CLI should remain `bankbuddy` until the platform shape is stable. Separate
-`taxbuddy` can remain temporarily, but the long-term command model should be
-one platform CLI with domain groups.
+The v2 command surface should start as `bb` while the legacy `bankbuddy` and
+`taxbuddy` CLIs remain available. This lets the new document/entity/observation
+model evolve without breaking the working banking and tax-document commands.
+After the v2 surface is stable, cleanup can decide whether `bb` becomes the
+only command or whether `bankbuddy` is kept as an alias.
 
 Target command families:
 
 ```text
-bankbuddy status
-bankbuddy init
-
-bankbuddy documents import FILE
-bankbuddy documents inbox --dry-run
-bankbuddy documents list
-bankbuddy documents show DOCUMENT_ID
-
-bankbuddy inspect documents --year YEAR
-bankbuddy inspect gaps --year YEAR
-bankbuddy inspect accounts --years 2024,2025
-bankbuddy inspect review
-
-bankbuddy review observations
-bankbuddy review accept OBSERVATION_ID
-bankbuddy review reject OBSERVATION_ID
-
-bankbuddy entities list
-bankbuddy entities show ENTITY_ID
-
-bankbuddy accounts list
-bankbuddy tx list
-bankbuddy report spending
-bankbuddy report net-worth
-
-bankbuddy tax sources
-bankbuddy tax gaps --year YEAR
-bankbuddy tax summary --year YEAR
+bb status
+bb init
+
+bb documents import FILE
+bb documents inbox --dry-run
+bb documents list
+bb documents show DOCUMENT_ID
+
+bb inspect documents --year YEAR
+bb inspect gaps --year YEAR
+bb inspect accounts --years 2024,2025
+bb inspect review
+
+bb review observations
+bb review accept OBSERVATION_ID
+bb review reject OBSERVATION_ID
+
+bb entities list
+bb entities show ENTITY_ID
+
+bb accounts list
+bb tx list
+bb report spending
+bb report net-worth
+
+bb tax sources
+bb tax gaps --year YEAR
+bb tax summary --year YEAR
 ```
 
 Potential later commands, only after the infer design is clarified:
 
 ```text
-bankbuddy infer document DOCUMENT_ID
-bankbuddy infer year YEAR
-bankbuddy infer compare --years 2024,2025
+bb infer document DOCUMENT_ID
+bb infer year YEAR
+bb infer compare --years 2024,2025
 ```
 
 Existing `bankbuddy import`, `bankbuddy tx`, `bankbuddy report`, and
@@ -1194,8 +1217,8 @@ Validation:
 
 Build:
 
-- `bankbuddy documents import`;
-- `bankbuddy documents inbox --dry-run`;
+- `bb documents import`;
+- `bb documents inbox --dry-run`;
 - document listing/show commands;
 - generic duplicate detection;
 - managed document archive paths;
@@ -1334,7 +1357,9 @@ CLI output, and defer durable text indexing until encryption is designed.
 
 Resolved decisions:
 
-1. Keep the user-facing product and CLI name as `BankBuddy` / `bankbuddy`.
+1. Keep the user-facing product name as BankBuddy, introduce `bb` as the
+   side-by-side v2 CLI, and keep `bankbuddy` / `taxbuddy` intact during the
+   transition.
 2. Use `Document/Entity/Observation/Relationship` as the foundation, with
    details refined during implementation.
 3. Introduce the v2 foundation schema additively beside existing legacy tables.

pyproject.toml

@@ -13,6 +13,7 @@ dependencies = [
 ]
 
 [project.scripts]
+bb = "bankbuddy.bb.cli:main"
 bankbuddy = "bankbuddy.cli:main"
 taxbuddy = "bankbuddy.tax.cli:main"