From 56dc5ef3d63bc08d74a2c27e28635420a6650b66 Mon Sep 17 00:00:00 2001
From: zhi <zhi@dev.hangman-lab.top>
Date: Sat, 21 Mar 2026 14:14:10 +0000
Subject: [PATCH] docs: settle hf permission introspection strategy

---
 plans/harborforge-cli-go-plan.md | 48 ++++++++++++++++++++++++++++++++
 plans/hf-cross-project-todo.md   |  4 ++-
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/plans/harborforge-cli-go-plan.md b/plans/harborforge-cli-go-plan.md
index 6daa338..507fa17 100644
--- a/plans/harborforge-cli-go-plan.md
+++ b/plans/harborforge-cli-go-plan.md
@@ -423,6 +423,54 @@ For leaf commands, this behaves the same as `--help`:
 
 ---
 
+## Permission Introspection Strategy
+
+The permission introspection strategy is now considered **decided**.
+
+### Normal command permission model
+
+For normal authenticated commands, the CLI should determine permissions through the authenticated user context derived from the token:
+
+1. resolve the current user from the token
+2. obtain the user's role
+3. obtain that role's permissions
+4. use those effective permissions to determine:
+   - `--help` output
+   - `--help-brief` output
+   - whether a subcommand is shown normally or marked `(not permitted)`
+
+This applies to normal command groups such as:
+- `user` (except `user create`)
+- `role`
+- `project`
+- `milestone`
+- `task`
+- `meeting`
+- `support`
+- `propose`
+- `monitor`
+
+### Special-flow exception: `hf user create`
+
+`hf user create` does **not** use the normal user-token permission model.
+It remains a special account-manager-token flow.
+
+That means:
+- normal permission introspection from the current user token should not be the gating mechanism for `hf user create`
+- `hf user create` help visibility should be handled independently of ordinary `user.write` capability
+
+### Backend implication
+
+Backend support for this strategy should ensure the CLI can derive:
+- current user identity
+- current user's role
+- current role permissions
+
+Whether this comes from one endpoint or multiple backend calls is an implementation detail.
+The strategy itself is settled: **token → user → role → permissions**.
+
+---
+
 ## Credential / Auth Rules
 
 ## Normal authenticated commands
diff --git a/plans/hf-cross-project-todo.md b/plans/hf-cross-project-todo.md
index 7646f37..5cdcfaa 100644
--- a/plans/hf-cross-project-todo.md
+++ b/plans/hf-cross-project-todo.md
@@ -11,7 +11,9 @@
 - [ ] Finalize MVP scope for first shipping version of `hf`
 - [ ] Confirm which existing backend routes can be reused vs which new routes are needed
 - [ ] Define canonical code-first lookup policy across all resources
-- [ ] Define permission introspection strategy for `--help` / `--help-brief`
+- [x] Define permission introspection strategy for `--help` / `--help-brief`
+  - settled as: token → current user → user role → role permissions
+  - `hf user create` remains a special account-manager-token flow and is not gated by ordinary user-token write permission
 - [ ] Define JSON output contract for CLI list/get commands
 - [ ] Define CLI exit code / stderr conventions
 - [ ] Define local plugin↔monitor communication protocol over `monitor_port`