chore: archive completed checklist and add CLI go plan

- archive completed ZHI_TASKS checklist
- move HarborForge CLI planning into main repository
- update backend/frontend submodules for account role changes

plans/harborforge-cli-go-plan.md

@@ -0,0 +1,325 @@
+# HarborForge CLI (Go Binary) Plan
+
+## Goal
+
+Build a **Go-based HarborForge CLI binary**.
+
+This CLI is intended to work in two modes:
+
+1. **With padded-cell / pass_mgr available**
+   - agents can use it directly
+   - secrets and generated credentials can be managed automatically
+2. **Without padded-cell installed**
+   - humans can still use it by explicitly passing tokens/passwords
+
+> Important: do **not** directly migrate the old Python CLI from `HarborForge.Backend/cli.py` as-is.
+> The old CLI is only a reference for existing command coverage.
+> The new CLI should be implemented as a standalone Go binary.
+
+---
+
+## High-Level Direction
+
+- Language: **Go**
+- Delivery: **single binary**
+- Config file: `.hf-config.json`
+- Config location: **same directory as the CLI binary**
+- Secret manager integration: `pass_mgr`
+- Design goal:
+  - compatible with automated agent usage
+  - also usable manually without padded-cell/pass_mgr
+
+---
+
+## Binary / Config Model
+
+Assume CLI name is placeholder `<cli-name>` for now.
+
+### Config file location
+
+The command:
+
+```bash
+<cli-name> config --url <hf-url>
+```
+
+must write:
+
+```json
+{
+  "base-url": "<hf-url>"
+}
+```
+
+into:
+
+```text
+<binary-dir>/.hf-config.json
+```
+
+That means config resolution is based on the **directory where the binary lives**, not cwd and not home directory.
+
+### Config contents (initial)
+
+```json
+{
+  "base-url": "http://127.0.0.1:8000"
+}
+```
+
+Initial config scope is intentionally small.
+
+---
+
+## CLI Command Requirements
+
+## 1. Config command
+
+### Set HarborForge base URL
+
+```bash
+<cli-name> config --url <hf-url>
+```
+
+Behavior:
+- write/update `base-url` in `<binary-dir>/.hf-config.json`
+
+### Set account-manager token through pass_mgr
+
+```bash
+<cli-name> config --acc-mgr-token <token>
+```
+
+Behavior:
+- execute:
+
+```bash
+pass_mgr set --public --key hf-acc-mgr-token --secret $token
+```
+
+If this fails, terminate with:
+
+```text
+--acc-mgr-token can only be set with padded-cell plugin
+```
+
+This is intentionally a hard error because this path depends on `pass_mgr` availability.
+
+---
+
+## 2. Normal authenticated commands
+
+General form:
+
+```bash
+<cli-name> <command> <arg> [--token <token>]
+```
+
+### Token resolution order
+
+1. If `--token <token>` is explicitly provided, use it.
+2. Otherwise try:
+
+```bash
+pass_mgr get-secret --key hf-token
+```
+
+If this fails, print stderr and terminate with exactly:
+
+```text
+--token <token> required or execute this with pcexec
+```
+
+### Notes
+
+- Normal API commands should support optional `--token`
+- They should also support agent-oriented execution when `pass_mgr` exists
+- They should remain usable manually when users explicitly provide `--token`
+
+---
+
+## 3. Special command: create-account
+
+Command shape:
+
+```bash
+<cli-name> create-account --user <username> [--pass <password>] [--acc-mgr-token <account-mgr-token>]
+```
+
+### Special rules
+
+- `create-account` **cannot** accept `--token`
+- `create-account` should **not** attempt normal token auto-resolution
+- It uses **account-manager token** instead of the normal user token flow
+
+### Password resolution
+
+If `--pass <password>` is not explicitly provided, try:
+
+```bash
+pass_mgr generate --key hf --username $username
+```
+
+If this fails, print stderr and terminate with exactly:
+
+```text
+--pass <password> required or execute with pcexec
+```
+
+### Account-manager token resolution
+
+If `--acc-mgr-token <token>` is not explicitly provided, try:
+
+```bash
+pass_mgr get-secret --public --key hf-acc-mgr-token
+```
+
+If this fails, print stderr and terminate with exactly:
+
+```text
+--acc-mgr-token <token> required or execute with pcexec
+```
+
+### Purpose
+
+This command is meant to work very naturally with padded-cell-driven agent flows while still allowing manual operator input.
+
+---
+
+## pass_mgr Integration Rules
+
+The CLI should treat `pass_mgr` as an optional capability.
+
+### With padded-cell / pass_mgr
+
+Expected conveniences:
+- persistent token lookup from `hf-token`
+- public account-manager token lookup from `hf-acc-mgr-token`
+- password generation via `pass_mgr generate`
+
+### Without padded-cell / pass_mgr
+
+Expected fallback:
+- users manually pass `--token`
+- users manually pass `--pass`
+- users manually pass `--acc-mgr-token`
+
+### Error philosophy
+
+Do not silently ignore secret-manager failures.
+If the command depends on pass_mgr fallback and it is unavailable, fail with the exact operator-facing messages defined above.
+
+---
+
+## Backend / Permission Requirements
+
+The new CLI plan implies backend support for an **account-manager** capability.
+
+### New protected default role
+
+In addition to existing undeletable default roles:
+- `admin`
+- `guest`
+
+add:
+- `account-manager`
+
+### account-manager semantics
+
+- role is part of initial bootstrap/default roles
+- role cannot be deleted
+- role permissions should be limited to:
+  - **create account**
+
+This is intentionally narrow.
+It should not inherit general admin privileges.
+
+### Backend work implied by this plan
+
+- seed `account-manager` during initial role setup
+- protect it from deletion the same way default protected roles are protected
+- add a backend permission / route policy for account creation by account-manager
+- make sure CLI `create-account` maps onto this backend capability cleanly
+
+---
+
+## Proposed CLI Implementation Phases
+
+## Phase 1 — Foundation
+
+- create Go module
+- add binary entrypoint
+- add config loader/saver for `<binary-dir>/.hf-config.json`
+- add HTTP client wrapper
+- add token resolution helpers
+- add pass_mgr execution wrapper
+- define clear error handling / stderr behavior
+
+## Phase 2 — Auth + Config Flows
+
+- implement `config --url`
+- implement `config --acc-mgr-token`
+- implement shared `--token` resolution behavior
+- implement request auth injection
+
+## Phase 3 — Account Creation Flow
+
+- implement `create-account`
+- support `--user`
+- support optional `--pass`
+- support optional `--acc-mgr-token`
+- add pass_mgr-backed fallback logic
+- enforce exact required error messages
+
+## Phase 4 — Command Expansion
+
+Use existing `HarborForge.Backend/cli.py` only as feature inventory reference.
+Do **not** copy its architecture directly.
+
+Potential later commands:
+- projects
+- users
+- milestones
+- tasks
+- proposes
+- monitor-related commands
+- health / version
+
+## Phase 5 — Hardening
+
+- tests for config path resolution
+- tests for pass_mgr failure behavior
+- tests for explicit token/password override behavior
+- tests for exact stderr messages
+- packaging / release pipeline for binary builds
+
+---
+
+## Open Questions
+
+1. Final binary name:
+   - `harborforge`
+   - `hf`
+   - `harborforge-cli`
+   - or another name
+
+2. `create-account` backend API contract:
+   - new dedicated route?
+   - or reuse/extend current user creation route?
+
+3. Whether normal token lookup should support additional fallbacks later:
+   - env var
+   - config file token
+   - OS keychain
+
+Current plan intentionally keeps fallback logic narrow and explicit.
+
+---
+
+## Non-Goals (for now)
+
+- do not directly port old Python CLI architecture
+- do not require padded-cell for all usage
+- do not store auth token in `.hf-config.json`
+- do not make `account-manager` an admin-like role
+- do not broaden account-manager permissions beyond account creation in the initial design