feat(contribute): target a learnings namespace with --namespace

[yudongyouqing]

Summary

Adds teamai contribute --namespace <ns> so a member whose directory reads several learnings namespaces can file a learning under one of them, instead of always landing in the shared root (#916). The flag accepts only namespaces this directory already reads — a learning never lands where its author's recall would not find it — and refuses unknown values with the valid list. Without the flag, routing is unchanged; the ambiguous multi-namespace case now prints a one-line hint. teamai projects list names the default destination and the accepted namespaces.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature causing existing behavior to change)
• Documentation only
• Refactor / internal cleanup

Test Plan

• npx tsc --noEmit passes
• npm run lint passes
• npx vitest run — every suite whose code path this change touches passes locally (contribute* incl. the new file, projects*, learnings*, import, commands-reference, skill-content, recall, search-index); the 13 failures in the wider learnings subset reproduce identically on origin/main on this Windows machine (git-kind-learnings, learnings-import-remnants real-git staging cases, pending-learnings path-separator assertions, skill-content's npm pack --dry-run shell-out) — i.e. pre-existing and environment-specific, left to CI
• Added/updated tests for the change: src/__tests__/contribute-namespace.test.ts (10 cases: routing with/without flag, namespace ≠ project id, refusal with valid list, refusal when no namespace is active, queue lands under pending-learnings/<ns>/, hint on ambiguity, dry-run path) and projectsList destination output cases in src/__tests__/projects-cmd.test.ts
• Real-CLI verification (Windows, npm run build + built dist/index.js, single-repo mode, two projects with learnings namespaces svc-a + payments):
  • teamai projects list → Contribute destination for this directory: learnings/ (shared root) + Namespaces read here: svc-a, payments — pass \teamai contribute --namespace ` to file under one.`
  • teamai contribute --file note.md --namespace payments --dry-run → [dry-run] Would push: learnings/payments/payments-routing-2026-10-04-6eme8b.md
  • teamai contribute --file note.md --namespace nope --dry-run → Unknown learnings namespace "nope". Valid namespaces: svc-a, payments + pointer to projects list
  • teamai contribute --file note.md --dry-run → hint naming both namespaces, then the shared-root path
  • real contribute --namespace payments (offline) → learning queued at …/pending-learnings/payments/payments-routing-2026-10-04-i6q1k6.md, reported as saved locally and recallable
• skill-data/core/references/commands.md regenerated (npx vitest run commands-reference -u)

Related Issues

Closes #916

Notes for Reviewers

• The issue leaves the flag name open (--namespace vs something else). I went with --namespace as proposed — happy to rename if reviewers prefer another name.
• resolveLearningsSubdir is now a thin wrapper over the new resolveLearningsDestination (which also returns the namespace list the hint and error messages need); the two other callers (import --from-mr remnants, learnings-publish) keep the old signature and unchanged behavior.
• Guardrail is "must be one this directory reads", not "must match the project id", so alpha with learnings: [alpha-notes] accepts --namespace alpha-notes, per the issue.
• Docs synced in docs/usage-guide.md + docs/usage-guide.zh-CN.md; skill-data/share/SKILL.md got a one-line pointer (kept minimal — teamai contribute --help and the generated commands.md remain the source of truth).

🤖 Generated with Claude Code