Skip to main content

Documentation Fixes Applied — 2026-05-22

Summary of Changes​

TaskStatusFiles Modified
P0-1: Terminology Fixes✅ Completedocs/user-stories.md
P0-2: /am/ Routes*✅ Completedocs/api/reference.md
P0-3: Agent Dispatch Path✅ Completedocs/technical-scopes.md
P0-4/5: Expert Pool Removal✅ Completedocs/design/VIEWS_BY_ROLE.md, docs/design/INFORMATION_ARCHITECTURE.md, docs/ops/pool-seed.sql (deleted)
P0-10: Onboarding Simplification✅ Completedocs/features/onboarding.md, docs/design/VIEWS_BY_ROLE.md
Tool Permission UI Fix✅ Completedocs/user-stories.md, docs/design/INFORMATION_ARCHITECTURE.md
API Endpoint Audit✅ Completedocs/api/reference.md (+50 endpoints)
IA.md Route Cleanup✅ Completedocs/design/INFORMATION_ARCHITECTURE.md

Detailed Changes​

1. Terminology Fixes (P0-1)​

Fixed in user-stories.md:

  • ✅ "AI agents" → "Specialists" (client-facing AI personas)
  • ✅ "AI agent" → "AI Agent" (sandboxed backend runtime)
  • ✅ "expert" → "Expert" (human reviewers, capitalized)
  • ✅ "agent" → "Specialist" in client-facing contexts
  • ✅ "my agent" → "my Specialist" consistently
  • ✅ "the agent" → "the Specialist" consistently
  • ✅ "agent actions" → "Expert actions" (where referring to human)
  • ✅ Updated Expert section header to clarify: "A human domain Expert who supervises Specialist AI Agents"
  • ✅ Fixed E-P1 user story to reference "assigned clients" instead of "pools"
  • ✅ Fixed E-R11 to remove pool reference

2. /am/* Routes Deprecated (P0-2)​

Fixed in api/reference.md:

  • ✅ Added deprecation notice to /am/* section header
  • ✅ Marked all /am/* endpoints with ⚠️ Legacy badge
  • ✅ Added note to use /ops/clients instead of /am/orgs
  • ✅ Created new "Organizations (Ops Portal) — Preferred" section documenting /ops/* routes
  • ✅ Fixed endpoint assign-agent → assign-specialist

3. Agent Dispatch Path (P0-3)​

Fixed in technical-scopes.md:

  • ✅ Updated dispatch path from /graph/invoke to /v1/chat via Hermes CLI
  • ✅ Added note that LangGraph /graph/invoke was removed

4. Expert Pool Removal (P0-4/5)​

Fixed:

  • ✅ user-stories.md: Fixed E-P1 to reference direct assignment instead of pools
  • ✅ design/VIEWS_BY_ROLE.md: Deprecated /workspace/pools screen
  • ✅ design/VIEWS_BY_ROLE.md: Updated settings to show "Assigned Organizations" instead of "Pools I'm a member of"
  • ✅ design/VIEWS_BY_ROLE.md: Updated analytics to show "org average" instead of "pool average"
  • ✅ design/INFORMATION_ARCHITECTURE.md: Removed /workspace/pools and /workspace/collab routes
  • ✅ design/INFORMATION_ARCHITECTURE.md: Removed /ops/pools from Superadmin nav
  • ✅ Deleted docs/ops/pool-seed.sql

5. Onboarding Simplification (P0-10)​

Fixed:

  • ✅ features/onboarding.md: Updated from 6-step to 4-step wizard
  • ✅ Removed dedicated Steps 2.4 (Channels) and 2.5 (Optional/Billing)
  • ✅ Added note that channels and billing are post-onboarding from /client/settings/*
  • ✅ design/VIEWS_BY_ROLE.md: Updated AM wizard Step 4 to reflect simplified checklist

6. Tool Permission UI Discrepancy Fixed​

Fixed in user-stories.md:

  • ✅ Changed SA-P5 from "[Implemented]" to "❌ Not implemented — API only"
  • ✅ Added note: API exists but no frontend UI built

Fixed in design/INFORMATION_ARCHITECTURE.md:

  • ✅ Updated Tools tab description to "API only; no frontend UI"
  • ✅ Changed status from "P0 — done" to "P1 gap — API exists"

Fixed in gaps table:

  • ✅ Un-crossed-out "Tool permission management UI" in gaps list

7. API Endpoint Audit — 50+ Endpoints Added​

Added to api/reference.md:

  • ✅ Auto-Reply Configuration (GET/PATCH /orgs/:orgId/auto-reply-config)
  • ✅ Email Whitelist (AM and Client routes)
  • ✅ Expert-Org Assignment (/organizations/:orgId/experts, /am/orgs/:orgId/experts)
  • ✅ Client Context (/client/context, /client/specialists, /client/org-info)
  • ✅ Corrections (/corrections, /learning/corrections/export, stats)
  • ✅ Scheduler (/scheduler/jobs, /scheduler/health)
  • ✅ Superadmin Operations (invite-token, delete org, RAGFlow provision, rebrand, deactivate)
  • ✅ Upload (/upload, /upload/signed-url)
  • ✅ Org Audit (/orgs/:orgId/audit)
  • ✅ Onboarding (/onboarding/:token/business-context, /api/slugs/:slug/resolve)
  • ✅ Expert Queue Additional (PATCH /expert-queue/:id, /expert-queue/admin/resurface-snoozed)
  • ✅ Nango Integrations (/v1/integrations/nango/session, /v1/integrations/credentials/nango/confirm)
  • ✅ Marketing (/marketing/companies/lead, /marketing/experts/application, /marketing/specialists)

8. Information Architecture Cleanup​

Fixed in design/INFORMATION_ARCHITECTURE.md:

  • ✅ Removed /workspace/collab from Expert site map
  • ✅ Removed /workspace/pools from Expert site map
  • ✅ Updated /workspace/analytics description (removed "pool")
  • ✅ Removed /ops/pools from Superadmin site map
  • ✅ Removed /superadmin/pools legacy redirect
  • ✅ Updated Superadmin tab bar (removed Pools)
  • ✅ Updated /ops/clients/[id] route description (Tools tab is API only)

✅ All Flagged Items Resolved​

Based on your responses:

  1. ✅ Specialist-Agent-Expert Architecture — Docs already reflect this correctly in user-stories.md intro and AGENT_ARCHITECTURE.md

  2. ✅ API Endpoint Audit — Completed. Added 50+ missing endpoints to api/reference.md

  3. ✅ Update IA.md — Completed. Removed /workspace/pools, /workspace/collab, /ops/pools

  4. ✅ Tool Permission UI — Fixed. Marked as "❌ Not implemented" (API only)

Files Modified Summary​

docs/
├── api/reference.md                       (+ deprecation notices, /ops/* section, +50 endpoints)
├── features/onboarding.md                 (+ simplified 4-step wizard)
├── design/VIEWS_BY_ROLE.md                (+ deprecated pools, updated wizard)
├── design/INFORMATION_ARCHITECTURE.md     (+ removed pools/collab, updated nav, fixed tools tab)
├── technical-scopes.md                    (+ fixed agent dispatch path)
├── user-stories.md                        (+ terminology fixes, fixed tool permission status)
└── ops/pool-seed.sql                      (DELETED)

This report was generated on 2026-05-22. All P0 items addressed. Ready for Docusaurus rebuild.

Last updated on by franky