feat(contribute): select an active learnings namespace (#916)

docs/designs/multi-project-management.md

@@ -537,7 +537,10 @@ as "changed by you (kept by pull)".
   skills/rules/claudemd by the union; namespace-aware learnings sync + cleanup
   (`src/pull.ts:687-745`, which today copies the whole flat `learnings/`).
 - `src/push.ts` — `--project` landing point.
-- `src/contribute.ts` — landing-point priority (active project namespace → root).
+- `src/contribute.ts` — explicit `--namespace` must belong to the active projects'
+  learnings namespaces; otherwise default to the only active namespace or the
+  shared root. Persist the chosen relative path in the existing pending queue
+  so retries keep their destination. `projects list` shows the default and choices.
 - `src/utils/search-index.ts` — a namespace-aware learnings collector (root +
   active project subdirs), replacing the flat `collectFlatMdEntries` call at
   `src/utils/search-index.ts:549`.
@@ -604,8 +607,11 @@ works.
 5. **Learnings isolation (P2 core).** A learning contributed under `hai-inference`
    does **not** appear in dir B's `teamai recall`; a root-level learning appears in
    both.
-6. **Contribute landing.** `teamai contribute` in dir A lands under
-   `learnings/hai-inference/`; with no active project it lands at the root.
+6. **Contribute landing.** `teamai contribute` defaults to the only active
+   learnings namespace, or the root when there are none or several. With
+   `--namespace`, it accepts only an active learnings namespace (not necessarily
+   a project id); unavailable paths are refused before queueing. Preview and
+   offline retry retain the selected destination.
 7. **Namespace-aware index.** `teamai recall` in dir A scans root + `hai-inference/`
    subdir (proves the flat→recursive collector change).
 8. **Member roster append.** `init` in both dirs → `members/<user>.yaml` lists

docs/usage-guide.md

@@ -323,8 +323,10 @@ explicit `--project` skips the picker.
 - **Backward compatible.** A repo without `manifest/projects.yaml` behaves exactly
   as before; existing flat `learnings/*.md` stay shared with everyone (zero
   migration).
-- **`teamai contribute`** lands a learning under the active project's subdirectory
-  when exactly one project is active, otherwise at the shared root.
+- **`teamai contribute`** defaults to `learnings/<namespace>/` when the active
+  projects resolve to exactly one learnings namespace, otherwise to the shared
+  root. Pass `--namespace <ns>` to choose one of those active namespaces;
+  `teamai projects list` shows the default destination and accepted namespaces.
 
 `manifest/projects.yaml` example:
 
@@ -1387,8 +1389,16 @@ You can also specify a file manually:
 ```bash
 teamai contribute --file /tmp/session.md
 teamai contribute --file /tmp/session.md --scope project
+teamai contribute --file /tmp/session.md --namespace payments
 ```
 
+`--namespace` accepts only the selected scope's active learnings namespaces from
+`manifest/projects.yaml`, which can differ from project ids. An unavailable or
+unsafe namespace is rejected before the learning is queued. Without the flag,
+the default above is unchanged; when several namespaces are active the command
+lists them and explains how to choose one. `--dry-run` previews the selected
+path without writing, and an offline contribution keeps that path when retried.
+
 #### Turning the hint off
 
 Teams that route knowledge sharing through their own review flow (for example, a personal retrospective that opens ordinary PRs) can switch the hint off without touching the rest of the Stop hook — update checks, votes sync, and dashboard reporting keep running. Same two-tier pattern as recall:
@@ -1924,7 +1934,7 @@ If core graph extraction or writing fails, the import reports an error without m
 
 With `--dry-run`, `--from-repo` and `--from-repo-list` read each repo's target commit with `git ls-remote`, print `Would import <owner>/<repo> at <commit>` and whether the local cache is current, and stop there: nothing is cloned or fetched into the cache, the import lock is not taken, and no AI step runs. With `--incremental` and a cache containing `LAST_SYNC`, the preview queries that cache's current branch at its configured origin, matching the real fetch/reset. Full-clone previews, including a missing cache or `LAST_SYNC`, follow remote HEAD. If the cached branch was deleted remotely, a non-pruning wildcard fetch retains its cached origin ref; incremental preview uses that retained commit too. Pruning, an explicit deleted-branch fetch refspec, or a missing cached origin ref still selects the full-clone fallback. Other cached-branch query failures warn and preview the full-clone fallback. With `--output`, the preview reports the same `teamwiki/evidence/code/<slug>` destination beside the output file as a real import.
 
-`--from-mr` publishes its learning the way `teamai contribute` does, on the `teamai-learnings` branch: under `learnings/<namespace>/` when exactly one active project declares a learnings namespace, otherwise at the shared `learnings/` root. If that fails, the learning stays queued on this machine and the next `teamai pull` publishes it; when a learnings checkout teamai refuses stopped it, no pull can until you deal with that checkout as the message says.
+`--from-mr` publishes its learning the way `teamai contribute` does by default, on the `teamai-learnings` branch: under `learnings/<namespace>/` when the active projects resolve to exactly one learnings namespace, otherwise at the shared `learnings/` root. If that fails, the learning stays queued on this machine and the next `teamai pull` publishes it; when a learnings checkout teamai refuses stopped it, no pull can until you deal with that checkout as the message says.
 
 When the draft overlaps existing learnings, from the shared root or your active projects' namespaces, the command names them (`Possible duplicate: this learning overlaps N existing learning(s): <files>.`), with `--all` too. It is a notice only: nothing is marked or replaced. When `manifest/projects.yaml` cannot be read, the check compares the shared root only and says so.
 

docs/usage-guide.zh-CN.md

@@ -279,8 +279,9 @@ cd ~/work/billing       && teamai init <team-repo> --project billing
   `teamai projects set all` 走的是字面 id，仍能单独激活它。
 - **向后兼容。** 没有 `manifest/projects.yaml` 的仓库行为与之前完全一致；现存扁平
   的 `learnings/*.md` 继续对所有人共享（零迁移）。
-- **`teamai contribute`** 在恰好激活一个项目时，把经验落到该项目子目录，否则落到
-  共享的根目录。
+- **`teamai contribute`** 在激活项目合计解析出恰好一个 learnings namespace 时，
+  默认写入 `learnings/<namespace>/`，否则写入共享根目录。可用 `--namespace <ns>`
+  指定其中一个活跃 namespace；`teamai projects list` 会显示默认落点和允许的选项。
 
 `manifest/projects.yaml` 示例：
 
@@ -1245,8 +1246,14 @@ Consider running `/teamai share what this session taught me` to summarize what y
 ```bash
 teamai contribute --file /tmp/session.md
 teamai contribute --file /tmp/session.md --scope project
+teamai contribute --file /tmp/session.md --namespace payments
 ```
 
+`--namespace` 只接受所选 scope 在 `manifest/projects.yaml` 中声明的活跃 learnings
+namespace，它不一定等于项目 id。不可用或不安全的 namespace 会在经验入队前被拒绝。
+不传该参数时保持上述默认行为；存在多个 namespace 时，命令会列出它们并提示如何选择。
+`--dry-run` 只预览选中的路径，不写入；离线贡献在重试发布时仍保留该路径。
+
 #### 关闭提醒
 
 如果团队通过自己的评审流程沉淀知识（例如个人复盘后提交普通 PR），可以只关闭这条提醒，Stop hook 的其余功能（更新检查、votes 同步、dashboard 上报）照常运行。配置方式与 recall 相同，分两层：
@@ -1769,7 +1776,7 @@ teamai import --from-repo https://github.com/org/repo --skip-enrich
 
 加 `--dry-run` 时，`--from-repo` 与 `--from-repo-list` 用 `git ls-remote` 读取每个仓库的目标提交，打印 `Would import <owner>/<repo> at <commit>` 以及本地缓存是否最新，然后停止：不会 clone 或 fetch 到缓存，不会获取导入锁，也不会运行任何 AI 步骤。使用 `--incremental` 且缓存含 `LAST_SYNC` 时，预览会查询该缓存配置的 origin 上当前分支的提交，与真实 fetch/reset 一致。完整克隆预览（包括缺少缓存或 `LAST_SYNC`）跟随远端 HEAD。若缓存分支已从远端删除，不执行 prune 的通配 fetch 会保留缓存 origin 引用，增量预览也使用该保留提交。启用 prune、显式 fetch 已删除分支或缺少缓存 origin 引用时，仍预览完整克隆回退。其他缓存分支查询失败时，预览会警告并预览完整克隆回退。 指定 `--output` 时，预览会显示与真实导入相同的输出文件旁 `teamwiki/evidence/code/<slug>` 目标目录。
 
-`--from-mr` 与 `teamai contribute` 一样，把提取的经验发布到 `teamai-learnings` 分支：恰好一个激活项目声明了 learnings namespace 时放在 `learnings/<namespace>/` 下，否则放在共享的 `learnings/` 根目录。发布失败时，经验留在本机队列中，下次 `teamai pull` 会发布它；若阻止发布的是 teamai 拒绝使用的 learnings 检出，则在你按提示处理该检出之前，任何 pull 都无法发布它。
+`--from-mr` 与 `teamai contribute` 的默认行为一样，把提取的经验发布到 `teamai-learnings` 分支：激活项目合计解析出恰好一个 learnings namespace 时放在 `learnings/<namespace>/` 下，否则放在共享的 `learnings/` 根目录。发布失败时，经验留在本机队列中，下次 `teamai pull` 会发布它；若阻止发布的是 teamai 拒绝使用的 learnings 检出，则在你按提示处理该检出之前，任何 pull 都无法发布它。
 
 如果草稿与已有经验（共享根目录或当前激活项目的 namespace 中的）高度重叠，命令会列出这些文件（`Possible duplicate: this learning overlaps N existing learning(s): <files>.`），使用 `--all` 时同样如此。这只是提示：不会标记或替换任何已有经验。`manifest/projects.yaml` 无法读取时，只与共享根目录比较，并给出提示。
 

skill-data/core/references/commands.md

@@ -295,9 +295,10 @@ Generated: do not edit by hand. Regenerate with
 
 ## contribute
 
-- `teamai contribute` — Contribute session knowledge to team repo
+- `teamai contribute` — Contribute session knowledge to team repo; projects list shows the default destination and allowed namespaces
   - `--file <path>` — Path to the contribution document
   - `--title <title>` — Title for the contribution document
+  - `--namespace <ns>` — Write to an active learnings namespace (default: the only active namespace, or the shared root when none or several are active)
   - `--session-id <id>` — Session ID for dedup tracking
   - `--scope <scope>` — Target scope: user or project