krow_backend/docs/backend-implementation-plan.md

Krow backend — implementation plan

Status: blueprint. No code has been changed to produce it. Backend audited: /Users/apple/Krow/krow-backend @ cadea4b (branch main). Frontend audited: /Users/apple/Krow/krow-demo, normative inventory at krow-demo/docs/api-audit.md.

---

0. How to read this document

Every row is traced. A claim about the server names a Go file and, where it matters, a line; a claim about the browser names a file in krow-demo/src; a claim about the schema names a migration. Nothing here is inferred from a README — where a README and the code disagree, the code won, and the disagreement is recorded in §13.

Four labels are used throughout, and they are the whole of the taxonomy:

Label	Meaning
EXISTS	Registered and working on the server, and the frontend calls it. Nothing to do.
WIRE	Registered and working on the server. The frontend does not call it. Frontend-only work; zero server changes.
CHANGE	The endpoint exists but its behaviour is wrong, incomplete, or disagrees with the frontend. Server change to existing code.
NEW	No server capability exists at all. Proposed only where §10 justifies it.

Two rules were held to while writing this:

• No route is invented. Every recommendation either reuses a registered route, changes the behaviour behind one, or is listed in §10 with an explicit justification, request/response shape, service, repository, DB and migration impact.
• No duplicate API is proposed for functionality that already has one. Where a need could be met either by a new route or by changing an existing handler, the plan takes the existing handler. §5.2 (interview completion) is the clearest case: it is solved by extending POST /api/v1/ai-interviews, not by adding an endpoint.

---

1. Every registered backend endpoint

1.1 The exact route count, derived from source

Server.New registers GET /health first and then sums five helpers (go-api/internal/httpserver/server.go (Server.New, lines 146-148)):

mux.HandleFunc("GET /health", s.handleHealth)
s.endpoints = s.routeAuth(mux) + s.routeResources(mux) + s.routeMe(mux) +
    s.routeDefinitions(mux) + s.routeWorkflows(mux)

Group	Routes	Counted from
Health	1	internal/httpserver/server.go:146
Auth	2	internal/httpserver/auth.go:129-130 (return 2)
Entity CRUD	34	Ops bits over 14 resources, internal/domain/resources_gen.go
/me	4	internal/httpserver/me.go:83-86 (return 4)
Agent + skill definitions	10	internal/httpserver/definitions.go:11-21 (return 10)
Workflows	2	internal/httpserver/workflows.go:87-88 (return 2)
Total registered	53
Server.Endpoints() returns	52	health is registered before the sum

The 34 entity routes, by Ops bit:

Resource	List	Get	Create	Update	Delete	=
JobPosting	✓	✓	✓	✓		4
JobApplication	✓		✓	✓	✓	4
AIInterview	✓		✓			2
Staff	✓		✓	✓		3
WorkerProfile	✓		✓	✓		3
Course	✓	✓	✓	✓		4
LearningPath	✓					1
RoleCategory	✓		✓			2
Certification	✓		✓		✓	3
UserActivity	✓		✓			2
Evidence	✓		✓	✓		3
Assignment	✓		✓			2
ShiftRecord	✓					1
Badge						0
						34

Badge carries Ops: 0 and an empty policy on purpose (resources_gen.go Badge block; internal/domain/policy.go "badges": {}). The descriptor exists so the seeder can populate the table.

1.2 Transport contract, common to every route

• Envelope in: a bare JSON object. decodeBody (internal/httpserver/api.go decodeBody (:203)) caps the body at maxBodyBytes = 4 MiB (api.go:15) and reads it into an open domain.Record. decodeInto (api.go decodeInto (:183)) is the closed-struct variant used by login and assign.
• Envelope out, single record: {"data": {...}} — writeRecord, internal/httpserver/response.go:48.
• Envelope out, collection: {"data": [...], "meta": {total, limit, offset, returned, truncated}} — writePage, response.go writePage (:52).
• Errors: {"error": {code, message, details}} — writeError, response.go writeError (:91). Status mapping in statusFor, response.go statusFor (:66): unauthorized→401, forbidden→403, rate_limited→429, not_found→404, validation_failed→422, invalid_query→400, conflict→409, else 500.
• 404/405 from the mux are rewritten into the same envelope by jsonErrors (server.go jsonErrors).
• Auth: every path outside publicPaths (auth.go publicPaths (:289-293): /health, /api/v1/auth/login, /api/v1/auth/logout) requires the krow_session cookie. authenticate (auth.go authenticate) resolves it, re-reads the user row on every request, revokes on inactive, and puts authctx.Identity + orgctx on the context.
• Tenancy: org_id is taken from the session user's row, never the request (auth.go authenticate, internal/repo/repo.go Repo.Insert (:367)).
• Authorization: Server.authorize (api.go Server.authorize (:64)) reads users.role, consults domain.Policy.Allows, and answers 403 before any query runs. Row visibility is a SQL predicate in internal/repo, so an invisible row answers 404.

1.3 Health

Method	Path	Auth	Role	Request	Response	Tables
GET	/health	public	—	—	{"status": "ok"|"degraded"|"unavailable"} (200/200/503)	db.Check reads schema_migrations, information_schema

Handler server.go handleHealth. The body is deliberately one field; all diagnostic detail goes to the log (logHealth, server.go logHealth).

1.4 Auth (2)

Method	Path	Auth	Role	Request	Response
POST	/api/v1/auth/login	public	—	{email, password, remember_me} (loginRequest, auth.go loginRequest)	200 {data: <user + preferences>} + Set-Cookie: krow_session
POST	/api/v1/auth/logout	public	—	—	200 {data:{status:"signed_out"}} + cookie cleared

• Login order (auth.go handleLogin): shape validation → two rate limiters (per-email and per-address, internal/httpserver/ratelimit.go) → constant-time credential verify (internal/auth/credentials.go) → session issue → MarkLoggedIn best-effort.
• Every credential failure returns the identical 401 (domain.Unauthenticated()).
• The token is never in the body — auth.go handleLogin states this explicitly.
• Cookie attributes: HttpOnly, Path=/, SameSite from sessionSameSite() (auth.go sessionSameSite — None when a CORS allowlist is configured, else Lax), Secure when not development or when cross-site.
• Tables: users, sessions (migration 000004), user_preferences.

1.5 Current user (4)

Method	Path	Auth	Role	Request	Response
GET	/api/v1/me	session	any	—	{data: user} with preferences embedded
PATCH	/api/v1/me	session	any	{full_name?, account_type?}	{data: user}
GET	/api/v1/me/preferences	session	any	—	{data: preferences}
PATCH	/api/v1/me/preferences	session	any	any JSON object	{data: merged preferences}

• Projection: userColumns, me.go userColumns (:33) — id, legacy_id, full_name, email, role, account_type, status, created_date, updated_date, plus preferences.
• PATCH /me may write only full_name and account_type (updatableUserFields, me.go updatableUserFields (:54)). role was deliberately removed — the comment at me.go updatableUserFields (:54) records that leaving it in was a live privilege-escalation path. Attempts to write anything in serverOwnedUserFields (me.go serverOwnedUserFields (:69)) are ignored and logged.
• Preferences are split: owliverDefault, compactDensity, emailDigest are columns (preferenceColumns, me.go preferenceColumns (:26)); everything else lands in user_preferences.extra jsonb — which is where customSkills, customAgents, disabledSkills and removedSkills live today.
• PATCH /me/preferences is a shallow merge with an upsert (me.go handlePreferencesPatch). Booleans are type-checked; every other key is stored as-is, with no size bound and no schema.
• Tables: users, user_preferences.

1.6 Entity CRUD (34)

All 34 share four handlers — handleList, handleGet, handleCreate, handleUpdate, handleDelete (internal/httpserver/api.go handleList/handleGet/handleCreate/handleUpdate/handleDelete) — over one generic service (internal/service/service.go) and one generic repository (internal/repo/repo.go), driven by the descriptors in internal/domain/resources_gen.go.

Request shape, create/update: an open JSON object of column names. Validation is Service.validate (service.go Service.validate (:204)):

• an unknown field is rejected ("unknown field" → 422), not ignored;
• a ReadOnly column in the body is ignored, not rejected;
• null on a NotNull column is rejected;
• an enum value outside Column.Enum is rejected with the permitted list;
• on create, every Required column must be present and non-blank unless serverSupplies says the session fills it (service.go serverSupplies (:266)).

Response shape: the full stored row, every column projected through Column.SelectExpr (internal/domain/resource.go Column.SelectExpr (:115)) — uuid→text, numeric→float8, date→YYYY-MM-DD, timestamptz→YYYY-MM-DDTHH:MM:SS.mmmZ, citext→text, bigint→text.

List parameters (Service.ParseList, service.go ParseList (:55)): sort (prefix - for DESC; explicit empty ?sort= means no ordering), limit (capped at MaxLimit = 1000, service.go:28), offset, and every other parameter is a field filter. Array and JSON columns are not filterable (Resource.Filterable, resource.go Resource.Filterable (:92)). Repeated params become col = ANY(...).

Delete always answers 200 with {id} whether or not a row matched (service.go Service.Delete (:185)) — deliberate, matching the old client store.

Per-resource authorization, row scope and derived columns, all from internal/domain/policy.go:

Path	List	Get	Create	Update	Delete	Talent row scope	Server-derived on insert
job-postings	all	all	operators	operators	—	ScopeActivePostings on status	created_by ← user id
job-applications	all	—	all	operators	operators	ScopeEmail on email	email ← session email (talent only)
ai-interviews	all	—	all	—	—	ScopeOwnApplications via application_id	— (insert guarded, repo.go:332)
staff	operators	—	operators	operators	—	n/a	—
worker-profiles	all	—	all	all	—	ScopeUserID on user_id	user_id ← user id (talent only)
assignments	all	—	operators	—	—	ScopeEmail on worker_email	—
shift-records	all	—	—	—	—	ScopeEmail on worker_email	—
courses	all	all	admin	admin	—	none	—
learning-paths	all	—	—	—	—	none	—
role-categories	all	—	operators	—	—	none	—
certifications	all	—	operators	—	admin	none	—
user-activity	all	—	all	—	—	ScopeEmail on user_email	user_id, user_email, user_name, account_type
evidence	all	—	operators…	operators	—	ScopeEmail on worker_email	worker_email ← session email (talent only)
badges	—	—	—	—	—	—	—

(evidence Create is everyone; Update is operators.) all = {admin, employer, talent}; operators = {admin, employer}.

Backing tables are one-to-one with Resource.Table in resources_gen.go; all are created in migrations/000001_initial_schema.up.sql, except job_applications.interview_id (000002) and the dropped job_applications_screened_consistent CHECK (000003).

1.7 Agent and skill definitions (10)

Method	Path	Auth	Role
GET	/api/v1/agent-definitions	session	any (rows scoped)
POST	/api/v1/agent-definitions	session	any; visibility: organization needs non-talent
GET	/api/v1/agent-definitions/{id}	session	any (rows scoped)
PATCH	/api/v1/agent-definitions/{id}	session	any own; organization rows need non-talent
DELETE	/api/v1/agent-definitions/{id}	session	same as PATCH
GET	/api/v1/skill-definitions	session	any (rows scoped)
POST	/api/v1/skill-definitions	session	any; visibility: organization needs non-talent
GET	/api/v1/skill-definitions/{id}	session	any (rows scoped)
PATCH	/api/v1/skill-definitions/{id}	session	any own; organization rows need non-talent
DELETE	/api/v1/skill-definitions/{id}	session	same as PATCH

Handlers internal/httpserver/definitions.go; service internal/service/definitions.go; repository internal/repo/definitions.go; parser/validator internal/definition/; schema migrations/000005_agent_skill_definitions.up.sql.

These are NOT domain.Resource values. They are not in the policy table; their role checks are written inline in internal/service/definitions.go (server.go package doc states this explicitly).

• Create request: {"markdown": "<the definition, verbatim>", "visibility": "personal"|"organization"}. visibility defaults to personal (definitions.go CreateAgent (:138)). No projection field is accepted from the body — name, description, status, version, pages, definition_id are all parsed out of the markdown (definitions.go CreateAgent (:138)).
• Update request: {"markdown": ...} or {"status": ...}. Note the else if at definitions.go:241 / definitions.go:415: if markdown is present, a sibling status in the same PATCH is silently ignored. visibility is immutable after creation (definitions.go UpdateAgent (:194)).
• Delete: idempotent — a non-UUID or an invisible row returns {"id": <id>} and 200 (definitions.go DeleteAgent (:253)).
• Response: all columns — id, definition_id, org_id, visibility, owner_user_id, created_by, markdown, status, version (agents only), name, description, pages, created_date, updated_date (repo/definitions.go agentDefinitionColumns (:77) / skillDefinitionColumns (:92)).
• List parameters: visibility, status, definition_id, sort, limit, offset — and nothing else; an unknown parameter is a 400 (definitions.go allowedDefinitionFilters (:17), :44-49). Sortable columns: created_date, updated_date, name, definition_id, status, and version for agents. Default -created_date, limit 100.
• Row visibility predicate, applied on every read, update and delete (repo/definitions.go GetAgent (:182) and siblings): org_id = :org AND (visibility='organization' OR (visibility='personal' AND owner_user_id = :user)).
• Validation: definition.ValidateAgent (internal/definition/agent.go ValidateAgent (:489)) and definition.ValidateSkill (internal/definition/skill.go ValidateSkill (:279)).

1.8 Workflows (2)

Method	Path	Auth	Required operations (all-or-nothing)
POST	/api/v1/job-applications/{id}/hire	session	job-applications:Update + staff:Create + user-activity:Create
POST	/api/v1/job-postings/{id}/assignments	session	assignments:Create + job-applications:Update + user-activity:Create

Every pair resolves to operators today. Authorization is authorizeAll (internal/httpserver/workflows.go authorizeAll (:41)) — checked before any BEGIN.

Hire (internal/service/workflows.go WorkflowService.Hire (:123))

• Request: optional {phone?, role?, hire_date?, profile_tier?, status?, reviewer_name?}. Anything else is ignored; every other staff field is carried from the application.
• Response 201 {"data": {"application": {...}, "staff": {...}}}.
• Behaviour: reads the application inside the transaction; a second hire is a 409 (workflows.go Hire, the already-hired branch); missing name or email is a 422; writes staff, patches the application to hired, and writes a user_activity row — all in one transaction, all through repo.New(res, tx).
• Tables: job_applications, staff, user_activity.

Assign (internal/service/workflows.go WorkflowService.Assign (:261))

• Request: {"workers": [{worker_email, worker_name, starts_at, ends_at?, application_id?, worker_profile_id?, match_score?, source?}]} — the closed struct service.AssignRequest (workflows.go AssignWorker/AssignRequest (:233/:245)).
• Batch capped at maxAssignmentBatch = 200 (workflows.go:47); the whole batch is validated before BEGIN.
• Response 201 {"data": {"assignments": [...], "count": n}}.
• Behaviour per worker: insert assignments; if and only if application_id was supplied, patch that application to assigned; insert a user_activity row. Errors are annotated with the batch index (workflows.go annotate (:433)).
• Tables: job_postings (read), assignments, job_applications, user_activity.

---

2. Frontend → existing backend mapping

Traced from krow-demo/docs/api-audit.md §3–§9 against the router.

2.1 Already wired — EXISTS (39 routes exercised)

Frontend call site	Endpoint	Note
krowHooks.js:65,72 useJobPostings/useJobPosting	GET /job-postings, GET /job-postings/{id}
KrowAssistant.jsx:366, CreatePosition.jsx:33-34	POST /job-postings, PATCH /job-postings/{id}
krowHooks.js:80 useApplications	GET /job-applications (± job_posting_id)
krowHooks.js:202,213	POST/PATCH /job-applications/{id}
Candidate removal paths	DELETE /job-applications/{id}
krowHooks.js:90, AIInterviewModal.jsx:159	GET/POST /ai-interviews
krowHooks.js:112, hire path	GET/POST/PATCH /staff
krowHooks.js:583,589	GET/POST/PATCH /worker-profiles
krowHooks.js:345,349,362,371	GET/POST/PATCH /courses, GET /courses/{id}
krowHooks.js:533	GET /learning-paths
CreatePosition.jsx:38-39	GET/POST /role-categories
CertificationManager.jsx:10-11	GET/POST/DELETE /certifications
userTracking.js:45, UserTracking.jsx:10	GET/POST /user-activity
krowHooks.js:629,639	GET/POST/PATCH /evidence
krowHooks.js:388, useAssignWorkers	GET/POST /assignments
krowHooks.js:105	GET /shift-records
base44Client.js the shared hydration promise (:130) + 11 call sites	GET /me	one shared hydration promise
auth.updateMe, Profile.jsx	PATCH /me
auth.updatePreferences, useUpdatePreferences	PATCH /me/preferences
base44Client.js auth.login/logout	POST /auth/login, POST /auth/logout

2.2 Backend exists, frontend does not use it — WIRE (13 routes)

Endpoint	What the frontend does instead	Section
POST /job-applications/{id}/hire	useHireCandidate — two un-transactional calls, krowHooks.js useHireCandidate (:296)	§3.1
POST /job-postings/{id}/assignments	useAssignWorkers — 3n calls in a loop, krowHooks.js useAssignWorkers (:406)	§3.2
GET/POST/GET {id}/PATCH {id}/DELETE {id} /agent-definitions (5)	preferences.customAgents, lib/agents/useAgents.js stored (:29), save (:62), remove (:75)	§3.3
GET/POST/GET {id}/PATCH {id}/DELETE {id} /skill-definitions (5)	preferences.customSkills, 104 references across 23 files	§3.4
GET /me/preferences	reads preferences off GET /me + the krow_demo_user mirror	not a gap — auth.preferences() must answer synchronously (api-audit.md §5.3)

Also unused but not a gap: GET /health (registered and proxied by vite.config.js; no frontend code calls it).

2.3 Frontend dummy / localStorage / client-only

Thing	Where	Server today	Verdict
integrations.Core.InvokeLLM	src/api/aiEngine.js; 10 consumers in krowAi.js + provingGround.js	none	NEW — §10.1
integrations.Core.UploadFile → blob: URL	aiEngine.js; KrowIdentity.jsx, MediaChallenge.jsx, VideoRecorder.jsx	none	NEW — §10.2
Assistant stream	components/ai-assistant/provider.js:205; createLocalProvider() runs because VITE_ASSISTANT_ENDPOINT is unset	none	NEW — §10.3
Web search	agent webSearch: flag; the UI states plainly that no provider is configured	none	NEW — §10.4
analytics.track	base44Client.js analytics.track (:287), DEV-only console.debug	none	not a gap — real audit logging is POST /user-activity
customSkills, customAgents	user_preferences.extra via PATCH /me/preferences	tables exist and are unused	WIRE — §3.3/§3.4
disabledSkills, removedSkills	user_preferences.extra	correct location	not a gap — migration 000005 header says so verbatim
krow_demo_user, krow_assistant:history, krow_assistant_open/expanded/width, krow_assistant:agent, per-context thread keys	localStorage / sessionStorage	none	not a gap — UI state; api-audit.md §9
ROLE_CATEGORIES (7 strings)	src/lib/roleCategories.js:9	GET /role-categories returns the org's own	not dummy data bypassing the API — the static list is merged on top of the fetched list at both call sites; see §4.2
src/api/seed.js (1,928 lines)	retained for DEMO_USER.preferences only	entity data is in PostgreSQL	dead but harmless
src/api/store.js (173 lines)	imported by nothing	—	dead
useBadges (krowHooks.js:537)	zero consumers; Ops: 0 server-side	—	dead; would 404
User: 'users' in RESOURCE_PATHS (httpClient.js:96)	no call site; no backend resource	—	dead
meta.truncated	httpClient.js:226 returns payload.data and drops meta entirely	server already sends it	WIRE — §9.3

2.4 Genuinely missing backend capability

Only four, and all four are in §10: LLM inference, file storage, assistant streaming, web search. Nothing the frontend calls today is missing from the server.

---

3. Existing APIs that must be adopted

3.1 Hire — POST /api/v1/job-applications/{id}/hire

What the frontend does now (krowHooks.js useHireCandidate (:296), useHireCandidate):

1. computes tier from application.ai_score (>=80 Skilled, >=60 Cross-Trained, else Beginner);
2. PATCH /job-applications/{id} {status: 'hired'};
3. POST /staff with name, email, phone, role: job?.title || job?.role_category || 'Staff', profile_tier: tier, today's hire_date, application_id, job_posting_id, ai_score, status: 'onboarding';
4. logActivity('hire_candidate') → POST /user-activity.

A failure between 2 and 3 leaves an application marked hired with no staff row, and nothing notices.

What the backend already supports (internal/service/workflows.go WorkflowService.Hire (:123)): all four writes in one transaction, a 409 on a double hire, and an all-or-nothing role check before BEGIN.

Three behavioural differences that must be resolved before adoption:

#	Difference	Resolution
H-1	Backend writes event_type: "candidate_hired" (workflows.go:212). The frontend vocabulary is hire_candidate — and PRIVILEGED_EVENTS = ['hire_candidate', 'create_position'] (src/lib/activitySignals.js:31), read by activity.signals and activity.breakdown. The seed fixture also uses hire_candidate (seed/fixtures/seed.json:4763). Adopting as-is silently breaks anomaly detection and the activity feed's labels.	CHANGE workflows.go:212 to hire_candidate.
H-2	Backend defaults profile_tier to "Beginner" (workflows.go Hire, the staff record literal); the frontend derives it from ai_score.	Frontend sends profile_tier in the body — the field is already accepted by pick(). No server change.
H-3	Backend sets role from app["job_title"]; the frontend prefers the posting's title, then role_category, then "Staff".	Frontend sends role in the body. No server change.

Adoption plan: replace the body of useHireCandidate with one POST /job-applications/{id}/hire carrying {role, profile_tier}; drop the separate logActivity('hire_candidate') (the workflow writes it); keep the same onSuccess invalidations plus ['userActivity'].

3.2 Assign — POST /api/v1/job-postings/{id}/assignments

What the frontend does now (krowHooks.js useAssignWorkers (:406), useAssignWorkers), per worker, sequentially, with no transaction:

1. POST /assignments;
2. look for an existing application on (job_posting_id, lower(email)); if none, POST /job-applications with the worker's profile fields and status: 'assigned'; if one exists, PATCH it to assigned;
3. logActivity('assign_employee', {position_id, application_id, worker_email}).

What the backend already supports (internal/service/workflows.go WorkflowService.Assign (:261)): the whole batch in one transaction, capped at 200, validated before BEGIN, errors annotated by index.

Two blocking differences:

#	Difference	Resolution
A-1	The backend never creates a JobApplication. It patches one only when application_id is supplied (workflows.go Assign, the application branch). The frontend's own comment (krowHooks.js useAssignWorkers, the create-if-absent comment) explains why creation is required: an assigned worker with no application is unreachable — nothing to open, and no subject for an interview. Adopting the endpoint as-is loses that behaviour.	CHANGE — see below. This is the single largest existing-code change in the plan.
A-2	Backend writes event_type: "worker_assigned" (workflows.go:373); the frontend vocabulary is assign_employee.	CHANGE workflows.go:373 to assign_employee.

Recommended resolution for A-1 — extend the existing endpoint, do not add one.

service.AssignWorker gains one optional field, application: {...}, carrying the same fields the frontend builds at krowHooks.js useAssignWorkers, the application literal. Inside the transaction, per worker:

• application_id supplied → patch it to assigned (unchanged);
• application_id absent and application supplied → look the application up by (job_posting_id, email) — the pair is already UNIQUE (job_applications_posting_email_key, migration 000001) and already indexed (job_applications_org_email_idx) — patch it if found, insert it if not, then link the assignment to it;
• neither → insert the assignment with no application link (today's behaviour, preserved for the talent-pool case the code comments describe).

Because the handler may now insert a job_applications row, the authorization requirement list at internal/httpserver/workflows.go handleAssign (:127) must gain {"job-applications", domain.OpCreate}. It resolves to operators, so no caller's effective permissions change — but the check must be written down or the workflow performs a write it was not authorized for.

Files to change: go-api/internal/service/workflows.go, go-api/internal/httpserver/workflows.go. No migration. No new route.

3.3 Agent definitions — 5 endpoints

What the frontend does now. useAgents (src/lib/agents/useAgents.js) is the single writer for every agent screen. It reads preferences.customAgents (:29) — an array of {path: 'custom/<id>.md', raw: <markdown>} — runs readAgentRegistry(stored, {customSkills}), and every mutation (save, remove, publish, archive, restore, duplicate) ends in updatePreferences.mutateAsync({customAgents: next}) → PATCH /me/preferences → user_preferences.extra.

Consumers: pages/admin/Workspace.jsx, pages/admin/AgentDetail.jsx, components/ai-assistant/AgentContext.jsx, lib/agents/customAgents.js.

What the backend already supports. Everything above, with tenancy and ownership:

Frontend operation	Endpoint	Server-side equivalent
save(source) — new	POST /agent-definitions {markdown, visibility}	validates, parses, projects definition_id/name/description/status/version/pages
save(source) — existing	PATCH /agent-definitions/{id} {markdown}	re-validates and re-projects every column
remove(id)	DELETE /agent-definitions/{id}	idempotent
publish(id)	PATCH with the republished markdown	agentLifecycle.publishAgent already writes status/version into the frontmatter; the server re-parses both
archive/restore	PATCH with the rewritten markdown, or {status}	server accepts draft/published/archived
sourceFor(id)	GET /agent-definitions/{id} or list + markdown	markdown is returned verbatim
shadowing shipped ids	definition_id is unique per owner and per org, never globally	agent_definitions_personal_key / _org_key, migration 000005

validateAgentSource in the browser and definition.ValidateAgent (internal/definition/agent.go:489) are held to byte-identical messages by internal/definition/conformance_test.go, which replays the real JavaScript parser's output over all 37 shipped definitions plus testdata/oracle.json.

One conflict-detection gap to be aware of when wiring. publish compares against live.version held in the browser (useAgents.js publish (:90)). The server has no optimistic-concurrency predicate on PATCH — UpdateAgent (repo/definitions.go UpdateAgent (:270)) writes unconditionally. Two tabs publishing concurrently: last write wins. This is not a regression (preferences had no concurrency control either) and is listed in §12 Phase 3 as an optional follow-up, not a blocker.

3.4 Skill definitions — 5 endpoints

Identical shape, minus version. The frontend writer is src/lib/skills/customSkills.js (upsertCustomSkill, removeCustomSkill, customSkillSource) plus usePageSkills / useWorkforcePaths (src/lib/skills/usePageSkills.js), which read preferences.customSkills and preferences.disabledSkills on every page render.

104 references across 23 files write or read customSkills: pages/admin/{Workspace,WorkspaceSkills,SkillEditor,OwliverSkillEditor,AgentDetail}.jsx, components/skills/SkillSurface.jsx, components/agents/*, components/ai-assistant/{KrowAssistant,useAssistant,routing,AgentContext}.jsx, lib/skills/{catalog,tools,usePageSkills}.js, lib/agents/{registry,capabilityTest}.js.

Mapping is one-to-one with §3.3, with status ∈ {active, inactive} (SkillStatuses, internal/definition/vocabulary.go SkillStatuses (:128)) and no version column — migration 000005 states verbatim that inventing one would be inventing a concept the frontend does not have.

What stays in preferences, deliberately: disabledSkills and removedSkills. They are arrays of skill ids, mostly shipped ids, so they are suppression preferences over a namespace rather than definitions. Migration 000005's header says exactly this. Do not migrate them.

3.5 What adoption of §3.3/§3.4 buys, per migration 000005

Column	What the jsonb blob had	What the table gives
markdown	a string in an array	the authoritative artefact, length BETWEEN 1 AND 65536
definition_id	derived by re-parsing every entry	a column, CHECK (~ '^[a-z0-9][a-z0-9-]*$'), indexed, unique per tier
visibility	none — everything was personal	personal | organization with a CHECK
owner_user_id / org_id	none	tenancy + ownership; personal rows CASCADE with their owner
status	parsed	a column, CHECK-constrained, partial-indexed for the runtime's own query
version (agents)	parsed	a column, CHECK (version >= 1), sortable
name/description/pages	parsed on every read	server-parsed projections, never accepted from a body
size	unbounded, and returned in full by GET /me on every page load	bounded, and off the /me hot path

---

4. Create Position / Jobs

4.1 The complete CRUD flow, verified

Step	Frontend	Endpoint	Server
List	useJobPostings (krowHooks.js:65-70) list('-created_date', 100)	GET /job-postings	default sort -created_date, default limit 100 — resources_gen.go JobPosting
Read one	useJobPosting(id) (krowHooks.js:72-78)	GET /job-postings/{id}	Ops includes OpGet
Create	useCreateJobPosting; CreatePosition.jsx:33; also KrowAssistant.jsx createPosition (:366) (Owliver's guided flow)	POST /job-postings	created_by derived from the session (policy.go); title is the only Required column
Update	useUpdateJobPosting; CreatePosition.jsx:34; useGenerateJobDescription patches a draft (krowHooks.js useGenerateJobDescription (:276))	PATCH /job-postings/{id}	shallow merge, service.go Service.Update (:161)
Close	status transition to closed	PATCH	posting_status enum, migration 000001:34
Delete	no call site	—	Ops has no OpDelete → the mux answers 405. Correct.

Talent callers see only status = 'active' rows — TalentScope: {Kind: ScopeActivePostings, Column: "status"} (policy.go), so a draft is a 404 to them, never a 403.

vetting_criteria and skill_requirements are jsonb NOT NULL with a GIN index on skill_requirements (migrations/000001_initial_schema.up.sql:281). The Create Position form writes both through toPositionPayload (src/lib/positionModel.js).

4.2 Dummy data still bypassing the real API

One candidate, and it is not a bypass. ROLE_CATEGORIES (src/lib/roleCategories.js:9) is a static array of seven strings. Its own docstring records that custom categories come from the RoleCategory entity and are merged on top at both call sites — CreatePosition.jsx:38 reads useRoleCategories() and KrowAssistant.jsx:271 does the same. The static list is a seed vocabulary offered as options, not a replacement for the fetched list, and POST /role-categories is wired (CreatePosition.jsx:39).

If the seven defaults are wanted as real rows, the correct move is a seed change to seed/fixtures/seed.json plus deleting the constant in the frontend — not a backend change. That is optional and is listed in Phase 1 as such.

No other dummy data was found on this flow. Overview.jsx:48-57, Positions.jsx, PositionDetail.jsx and CreatePosition.jsx all read live query hooks.

4.3 Are any backend changes required for Create Position?

No. The four registered routes cover every call site, the defaults match, the enums match, created_by is derived, and delete is correctly absent. The only work on this flow is the AI description generation — useGenerateJobDescription calls the local generateJobDescription stub (src/lib/krowAi.js) before it PATCHes the draft. That is §10.1, not a job-posting problem.

---

5. Applications / Interviews / Staff / Talent / Assignments

5.1 Applications

Flow	Endpoint	Status
Talent applies (Apply.jsx:17)	POST /job-applications	EXISTS. email is derived from the session for talent (policy.go), so an applicant cannot file under someone else's address.
Operator screens one (useScreenCandidate, krowHooks.js useScreenCandidate (:223))	PATCH /job-applications/{id}	EXISTS. Writes status: 'ai_screened' plus seven ai_* fields.
Operator screens all (useScreenAllCandidates, krowHooks.js useScreenAllCandidates (:245))	n × PATCH	EXISTS, and correctly not a workflow — internal/service/workflows.go file header records the reasoning: a partial screen is not a corrupt state.
Move to interview (useMarkInterviewReady, krowHooks.js useMarkInterviewReady (:507))	PATCH + POST /user-activity	EXISTS.
Remove	DELETE /job-applications/{id}	EXISTS, operators only, idempotent 200.

Two defects found.

• AP-1 — missing validation, wrong layer. CHANGE. Service.serverSupplies (go-api/internal/service/service.go serverSupplies (:266)) iterates Policy.Derived and ignores Derived.TalentOnly. For job-applications, email is Required and Derived{TalentOnly: true}. Consequence: an operator who POSTs an application with no email skips the service's required-field check entirely, reaches SQL, and trips email citext NOT NULL. translate (repo/repo.go translate (:673)) turns that into a 422 "email must not be null", so the status code is right by accident, but the message and the details key differ from every other required-field refusal and the check is one layer too late. Fix: give serverSupplies the caller's role and skip a TalentOnly derivation for non-talent callers. Same defect applies to evidence.worker_email and would apply to any future TalentOnly required column. One file: go-api/internal/service/service.go. No migration.

• AP-2 — screened_at is written by nobody. Migration 000003 dropped job_applications_screened_consistent and its header explains why: the column came from the blueprint, not from repository evidence, and 9 of 24 seeded applications were being rejected by it. The column survives, nullable and unused. No action. Recorded so nobody re-adds the constraint.

5.2 Interviews — one real RBAC break

AIInterviewModal.finishInterview (src/components/krow/AIInterviewModal.jsx finishInterview (:155)) does two writes with no transaction:

1. POST /ai-interviews — the transcript, scores and verdict;
2. PATCH /job-applications/{id} {status:'interview', interview_id, ai_score}.

IV-1 — a talent user cannot complete an interview. CHANGE. Apply.jsx renders this modal for the talent flow. The policy table allows ai-interviews:Create to everyone but job-applications:Update to operators only (internal/domain/policy.go). So step 1 succeeds and step 2 returns 403: the interview row exists, the application still says applied, and interview_id is never set. InterviewAnalytics.jsx:9 and AnalyticsMetrics.jsx:8 both count status === 'interview' || a.interview_id, so the interview is invisible to analytics afterwards.

IV-2 — the two writes are not atomic, even for an operator. A failure between them leaves an orphan ai_interviews row.

Recommended fix — reuse the existing route, do not add one. Make POST /api/v1/ai-interviews link its application in the same transaction: after inserting the interview, update the named application_id to {status:'interview', interview_id: <new id>, ai_score: overall_interview_score} — performed by the server on the row the interview already names, so no widening of job-applications:Update is needed and a talent caller still cannot patch an application directly.

The insert is already guarded: Repo.guardInsert (go-api/internal/repo/repo.go guardInsert (:332)) refuses a talent caller creating an interview for an application that is not theirs, answering 404. That guard is exactly the ownership proof the linked update needs.

• Files: go-api/internal/service/service.go (or a small go-api/internal/service/interviews.go holding the special-cased Create for this one resource), and go-api/internal/httpserver/api.go only if the handler needs a transaction begun for it. Prefer routing this resource's Create through the transactional path already built in go-api/internal/service/workflows.go (WorkflowService.inTx).
• Alternative, rejected: adding talent to job-applications:Update with a column allowlist. Rejected because it puts a second authorization mechanism (per-column) beside the existing per-operation one, which internal/httpserver/workflows.go file header explicitly argues against.
• No new route. No migration.

ai_interviews has no OpUpdate and no OpGet — correct: the record is written once, and every consumer reads it from the list.

5.3 Staff

GET/POST/PATCH /staff, operators only. HiredHistory.jsx:41-42 reads staff and postings and writes ratings/reviews through PATCH. EXISTS, complete. Adopting §3.1 makes the create half transactional.

5.4 Talent / worker profiles

Flow	Endpoint	Status
useWorkerProfile — read-or-create on first access (krowHooks.js useWorkerProfile (:548))	GET /worker-profiles?email=&limit=1 then POST	EXISTS. user_id derived for talent.
useWorkerProfiles (krowHooks.js useWorkerProfiles (:580))	GET /worker-profiles -krow_score 500	EXISTS, matches the server default exactly.
useUpdateWorkerProfile, useCompleteCourse, useSubmitChallenge	PATCH /worker-profiles/{id}	EXISTS. Shallow merge replaces whole arrays, which useSubmitChallenge relies on (repo/repo.go Repo.Update (:429)).
Evidence submit (useSubmitChallenge, krowHooks.js useSubmitChallenge (:639))	POST /evidence then PATCH /worker-profiles/{id}	EXISTS, but two writes with no transaction. workflows.go file header names this as deliberately deferred. Low risk: a failed profile patch loses XP, not the evidence. No change proposed.
Supervisor verify (useVerifyEvidence)	PATCH /evidence/{id}	EXISTS, operators only.

TP-1 — a profile created by an operator locks its own subject out. CHANGE (deferred). worker_profiles.user_id is derived talent-only (policy.go), so a profile an admin creates for a candidate has user_id = NULL. The talent row scope is ScopeUserID on user_id, so that person's GET /worker-profiles?email=... returns empty — the row is invisible to them. useWorkerProfile (krowHooks.js useWorkerProfile (:548)) reads that empty list as "no profile yet" and POSTs one, which trips worker_profiles_org_email_key UNIQUE (org_id, email) (migrations/000001_initial_schema.up.sql:334). translate (repo/repo.go translate (:673)) turns the unique violation into a 409 conflict, and the query throws.

So the failure is not a duplicate row — the constraint prevents that correctly — it is a talent user who can neither see nor create their profile, with no path out from the UI. It is latent today only because the seed fixture attaches user_id to every profile it writes.

The fix needs a product decision (may an operator claim a profile on someone's behalf, and does signing in adopt an unclaimed one?), so it is scheduled in Phase 7 rather than earlier. Two candidate shapes, both without a new route: (a) widen the talent read scope to user_id = :user OR (user_id IS NULL AND email = :email) in internal/domain/policy.go + internal/repo/repo.go, and adopt the row on first write; or (b) claim it at login in internal/httpserver/auth.go. (a) is preferred — it is a predicate change in the layer that already owns predicates. See §11 for the DB impact of each.

TP-2 — no role gate on the admin console. Frontend. AdminRoute.jsx AdminRoute (:23) checks isAuthenticated and explicitly notes that a role check "will go in Phase 3D". It has not. An employer who signs in at /admin/login reaches KROW Forge (University.jsx:48-49), whose POST/PATCH /courses are admin-only (policy.go — employer is excluded on purpose, because a NULL-org_id course is the shared platform library). The same applies to DELETE /certifications. Result today: a 403 toast where the UI offers an action. Frontend work; the server is right.

5.5 Assignments

Flow	Endpoint	Status
List	GET /assignments -created_date 500	EXISTS, matches.
Create	POST /assignments in a 3n loop	WIRE → POST /job-postings/{id}/assignments, after the A-1/A-2 changes in §3.2.
Update / cancel	—	Not supported and not called. Ops is `List

One cosmetic difference to settle while wiring §3.2: the column default is source = 'owliver' (migrations/000001_initial_schema.up.sql:511) and the frontend sends 'owliver', but WorkflowService.Assign substitutes 'manual' for an empty value (internal/service/workflows.go:336). Harmless while the frontend always sends the field; worth aligning in the same edit.

The schema is ahead of the API here in a good way: assignments_period_gist (migrations/000001_initial_schema.up.sql:523) already indexes the [starts_at, ends_at) period, which is what an overlap check would need if double-booking ever becomes a rule. No such rule exists in the frontend today, so none is proposed.

---

6. Owliver / Agents / Skills — full audit

6.1 The two tables

migrations/000005_agent_skill_definitions.up.sql creates agent_definitions and skill_definitions. Two tables and not one, per its own header: agents have status ∈ {draft, published, archived} plus a monotonic integer version; skills have status ∈ {active, inactive} and no version at all.

Deliberately absent, and named as such in the migration: definition_versions, definition_permissions, agent_skills, agent_subagents, agent_knowledge, conversations. Do not add any of them in this plan. permissions: is parsed (internal/definition/agent.go normalizePermissions) and unenforced by design.

6.2 Ownership and tenancy — verified

Property	Where enforced	Verdict
org_id NOT NULL on both tiers, including personal	migration 000005; service/definitions.go CreateAgent (:138) sets it from ident.OrgID	correct — a personal definition is always inside a tenant
owner_user_id set iff visibility='personal'	CHECK ((visibility='personal') = (owner_user_id IS NOT NULL))	correct, and stated in one line so it cannot be half-satisfied
personal definitions cascade with the owner	owner_user_id ... ON DELETE CASCADE	correct
shared definitions survive their author	created_by ... ON DELETE SET NULL	correct
every read/write carries the org + ownership predicate	repo/definitions.go — ListAgents/GetAgent/UpdateAgent/DeleteAgent and the four skill twins	correct; an invisible row answers 404, never 403
a talent user cannot author an organization definition	service/definitions.go CreateAgent (:138) (create), :207-212 (update), :264-269 (delete), ×2 for skills	correct
visibility is immutable after create	service/definitions.go UpdateAgent (:194), :415-419	correct
a definition cannot name its own tenancy	internal/definition/definition.go package doc — the frontend ignores visibility: in frontmatter entirely	correct

6.3 Shadow-by-id — verified

definition_id is not globally unique. Two partial unique indexes: (owner_user_id, definition_id) WHERE visibility='personal' and (org_id, definition_id) WHERE visibility='organization'. So a personal definition may carry the same id as an organization one, which may carry the same id as a shipped one in krow-demo/src/skills/ — which is exactly the override mechanism useAgents.isOverridden (useAgents.js:41) already reports as shadowed.

Resolution precedence is implemented: GetAgentByDefinitionID / GetSkillByDefinitionID (repo/definitions.go GetAgentByDefinitionID (:209), :430-461) order by CASE WHEN visibility='personal' THEN 1 ELSE 2 END LIMIT 1 — personal wins. These two functions are reachable only from internal/runtime, which is not wired to any route (see §6.7).

6.4 Status, versioning

• Agents: status CHECK ('draft','published','archived'); version integer NOT NULL DEFAULT 1 CHECK (version >= 1); partial index agent_definitions_published_idx ... WHERE status='published'.
• Skills: status CHECK ('active','inactive'); partial index skill_definitions_active_idx ... WHERE status='active'. No version.
• Both are projections parsed out of the markdown, never accepted from a body — service/definitions.go CreateAgent (:138) builds the insert input entirely from definition.ParseAgent / ParseSkill output.
• PATCH {status} is accepted as a shortcut only when markdown is absent — the else if at service/definitions.go:241 and :415. Gap D-1 (CHANGE, minor): a PATCH carrying both markdown and status silently drops the status. It should either apply the markdown's parsed status (which it does) and say so, or refuse the combination as a 422. A silent drop is the one outcome that teaches nobody anything.
• No optimistic concurrency. UpdateAgent (repo/definitions.go UpdateAgent (:270)) writes unconditionally; useAgents.publish compares versions in the browser (useAgents.js publish (:90)). Two tabs publishing concurrently: last write wins. Not a regression from preferences. Optional Phase 3 follow-up: add AND version < :new_version to the agent update predicate and answer 409 on zero rows — a change to repo/definitions.go only, no migration.

6.5 Markdown parsing and validation

internal/definition/ is a deliberate port of the browser's parsers:

Concern	Backend	Frontend counterpart
document layer (BOM, line endings, fences, body)	frontmatter.go	src/lib/skills/registry.js
YAML subset (no YAML dependency, on purpose)	yaml.go	src/lib/skills/yaml.js
JS value semantics (jsString, jsTruthy, jsNumber, jsTrim)	jsvalue.go	JavaScript itself
agent parse + normalize	agent.go — port of parseAgent + normalizeAgent	src/lib/agents/registry.js, agentConfig.js
skill parse	skill.go — port of parseSkill	src/lib/skills/registry.js
closed vocabularies	vocabulary.go	src/lib/skills/surfaces.js, src/lib/agents/vocabulary.js

Compatibility is enforced, not asserted: internal/definition/conformance_test.go replays the actual JavaScript parser output (captured into testdata/oracle.json by scripts/oracle.mjs) against the Go parser over all 37 shipped definitions plus every adversarial case.

Deliberate asymmetries, all documented in source and not to be "fixed":

• Skill.Pages keeps the strings as the author wrote them; Agent.Pages are canonicalised (skill.go Skill.Pages (:28), agent.go Agent.Pages (:66)). The two frontend parsers differ the same way; reconciling here would make each side disagree with its own editor.
• pages: candidates (a bare scalar) is accepted for an agent and refused for a skill, because normalizeAgent coerces and parseSkill requires a sequence (agent.go asList (:112)).
• A skill's status: is a coercion, not a check — anything that is not inactive reads as active (skill.go ParseSkill (:107)).

Three rules are the backend's own, all listed as BackendOnly on the Rejection:

1. MaxMarkdownLength = 65536 characters — the markdown_size CHECK, which the editor does not enforce (definition.go:73, skill.go ValidateSkill (:279), agent.go ValidateAgent (:489)).
2. MaxVersion = 2147483647 — agent_definitions.version is a PostgreSQL integer; the editor accepts any whole number ≥ 1 (agent.go ValidateAgent (:489)).
3. "A definition with a ui: block needs an explicit pages: list" (skill.go ValidateSkill (:279)) — because parseSkill falls back to the ui: block's own pages, a fallback the backend cannot compute (§6.6).

6.6 Backend validation vs. the frontend Owliver vocabulary

This is the sharpest boundary in the system, and it is drawn on purpose.

What the backend mirrors exactly. SKILL_SURFACES — all 18 ids and their aliases (create-position←new-position, hired-history←hired, krow-forge←university/forge) — are transcribed into internal/definition/vocabulary.go pageSurfaces (:18), and normalizeKey (vocabulary.go normalizeKey (:70)) reproduces surfaces.js's own normalization (lower-case, spaces and underscores read as dashes). Verified against the live frontend: python3 over src/lib/skills/surfaces.js yields exactly those 18 ids in that order. The agent vocabularies — statuses, reasoning modes, knowledge kinds, access, permission roles, the 10 icons — are transcribed at vocabulary.go the agent vocabulary block (:94-113).

What the backend does not read at all. internal/definition/skill.go deferredBlocks (:235) (deferredBlocks) records the presence of ui: and owliver: on Skill.Deferred and checks nothing inside them.

Frontend vocabulary	Count	Source of truth	Backend equivalent
Page surfaces	18	src/lib/skills/surfaces.js SKILL_SURFACES	mirrored — vocabulary.go pageSurfaces (:18)
Owliver capabilities	10	surfaces.js OWLIVER_CAPABILITIES	none
Data sources	25	surfaces.js DATA_SOURCES	none
Section types	9	surfaces.js SECTION_TYPES	none
Periods	6	surfaces.js PERIODS	none
Placement→context rules	—	surfaces.js placementProvides()	none
owliver: normalization	—	src/lib/skills/owliverConfig.js	none
section normalization	—	src/lib/skills/uiConfig.js normalizeSection()	none

Consequence, stated precisely: if §3.3/§3.4 are adopted today, the server will store and round-trip an owliver: block byte-for-byte and validate the pages: list, but it will not reject an unknown capability, an unknown data source, an unknown period, or a capability that resolves no source. That validation stays in owliverConfig.js.

The one known divergence is pinned by a test: krow-demo/skill-examples/board-invalid-context.md is refused by the frontend (on a placement/data-source rule) and accepted by the backend. The conformance suite asserts it remains the only such case.

This is acceptable for Phase 3. The browser is the only renderer, so browser-side refusal is sufficient to keep a bad definition off a page. It stops being acceptable the moment the server answers an Owliver question — which is §7.

6.7 internal/runtime — built, tested, and not wired

go-api/internal/runtime/ (loader 237 lines, executor 129, types 103, tests 890) loads a definition by uuid or definition_id, re-validates it, resolves skill dependencies, refuses draft/archived agents and inactive skills, detects circular dependencies, and hands off to an AgentExecutor / SkillExecutor boundary. The default is UnavailableExecutor, which returns ErrExecutorUnavailable — "AI executor is unavailable (deferred to Phase 5)" (runtime/types.go ErrExecutorUnavailable).

grep -rn "internal/runtime" go-api --include='*.go' outside the package and its tests returns nothing. It is not constructed in Server.New (internal/httpserver/server.go Server.New) and has no route.

This is the designed seam for §7 and §10.3. Do not build a parallel one.

6.8 What is still frontend-only, definitively

1. All owliver: and ui: block semantics — capabilities, sources, periods, shapes, placements, inheritance, editable requiring both halves.
2. Every one of the 25 data-source resolvers (src/lib/skills/dataResolver.js, 1,214 lines).
3. disabledSkills / removedSkills suppression — correctly so.
4. Agent conversation state, history and panel layout (components/ai-assistant/*, localStorage/sessionStorage).
5. Shipped definitions themselves — krow-demo/src/agents/**, src/skills/**. Migration 000005's header states they must stay in Git: putting them in a table would trade git log, review and atomic deploy for nothing.

---

7. Owliver skill responses — what backend support would actually require

Nothing here is proposed for Phases 1–3. This section answers "what would it take", so the decision can be made with the cost visible.

7.1 The requirement

Today, provider.stream(request) (components/ai-assistant/provider.js) yields snapshots — the whole block array so far, not deltas, because a table or a KPI row has no meaningful half-state. createAssistantProvider() returns createHttpProvider only when VITE_ASSISTANT_ENDPOINT is set; it is unset, so createLocalProvider() runs and computes deterministic answers from the dashboard's own already-loaded data.

For a response to become backend-supported, three things must move server-side, and they are separable:

Layer	What it is	Cost
L1 — vocabulary	The closed tables in §6.6: 10 capabilities, 25 sources, 9 section types, 6 periods, and the placement→context rules	~600 lines of transcription + a conformance oracle, mirroring what vocabulary.go already does for the 18 surfaces
L2 — resolvers	25 data sources rewritten as SQL against job_applications, job_postings, worker_profiles, assignments, shift_records, staff, courses, user_activity	the real cost — dataResolver.js is 1,214 lines and depends on lib/workforce.js, lib/attendance.js, lib/activitySignals.js, lib/positionModel.js, lib/talentHome.js, lib/admin/positionInsights.js
L3 — transport	one streaming endpoint	small, and specified in §10.3

7.2 The security argument for doing it

api-audit.md §7 records that the fact sheet is deliberately not sent to the provider: dashboard data is to be read server-side from the caller's own session, so a client cannot ask about records it is not entitled to see, and an agent cannot widen that by being named in the body.

That property is only achievable server-side. L2 done in Go inherits the tenancy and talent-scope predicates that already live in internal/domain/policy.go and internal/repo/repo.go — the same predicates every list endpoint uses. Done any other way it has to be re-derived.

7.3 The one endpoint, if it is built

Specified in full in §10.3. No other route is required — a capability resolves to a section, a section resolves to a source, and the answer streams back as blocks. There is no second shape for "the chat version", by design (api-audit.md §6.1).

7.4 Order

L1 and L2 are useless without L3, and L3 without L2 answers nothing. But L2 can be built one source at a time behind a capability list the server advertises: a capability whose source has no server resolver is simply not offered, which is exactly the rule owliverConfig.js already applies (api-audit.md §6.1: "a capability that resolves no source is dropped, with a named error"). That makes this incremental rather than all-or-nothing, and it is why §12 Phase 4 is a phase rather than a single task.

---

8. Flow-chart data

8.1 Where it comes from today — traced

A flow is one of the 9 SECTION_TYPES and one of the 10 OWLIVER_CAPABILITIES. Its data is produced by resolveSkillData(section, context) (src/lib/skills/dataResolver.js:1196), which dispatches on section.source into the RESOLVERS table.

context is assembled in exactly two places, and both assemble it from live query hooks over registered endpoints:

• src/components/skills/SkillSurface.jsx:81-119 — useApplications, useJobPostings, useInterviews, useCourses, useWorkerProfiles, useStaff, useUserActivity, useAssignments, useShiftRecords, useCurrentUser, plus trainingPaths derived from courses + the profile.
• src/components/ai-assistant/KrowAssistant.jsx:300-343 — the same set for the panel.

ResponseBlocks.jsx:479 re-resolves the same section live for a chat answer.

8.2 Can existing backend resources provide it?

Yes — entirely, and they already do. Every collection above is a registered list endpoint with a matching default sort and limit:

Context key	Endpoint	Default sort / limit
applications	GET /job-applications	-ai_score / 200
positions	GET /job-postings	-created_date / 100
interviews	GET /ai-interviews	-created_date / 100
courses	GET /courses	-created_date / 200
workerProfiles / profiles	GET /worker-profiles	-krow_score / 500
assignments	GET /assignments	-created_date / 500
staff	GET /staff	-created_date / 100
activity	GET /user-activity	-created_date / 500
shifts	GET /shift-records	-created_date / 500

Periods are computed at read time from created_date (dataResolver.js periodRange (:48), inPeriod at :77-84) — never stored, never hard-coded. The server already returns created_date in the exact millisecond ISO-8601 form the resolvers parse (domain/resource.go Column.SelectExpr (:115)).

8.3 Recommendation

No new endpoint. No backend change. Flow-chart data is a client-side reading over records the API already serves, and the reading must stay wherever the renderer is. The only backend involvement flow data would ever need is §7 L2 — and that is a relocation of dataResolver.js, not a new resource.

One honest caveat, and it is §9.3's caveat too: a flow over shift-records reads at most 500 rows because that is the limit the frontend asks for, and the frontend discards the meta.truncated flag the server already sends. Fix that in the frontend.

---

9. Dashboard / analytics / activity

9.1 What is real

Surface	Values	Source
pages/Overview.jsx:48-57	active positions, total applications, screened, new, average AI score, hires	useJobPostings + useApplications — all real
pages/Overview.jsx:60-61	top candidates, active postings	same two, sorted/sliced client-side
pages/Analytics.jsx:13-16	funnel, interview analytics, hire metrics	useApplications, useInterviews, useStaff, useJobPostings — all real
pages/UserTracking.jsx:10	activity feed	useUserActivity — real
pages/TalentPool.jsx:9	pool, score bands	useWorkerProfiles — real
pages/HiredHistory.jsx:41-42	hires, tiers, reviews	useStaff + useJobPostings — real
lib/activitySignals.js	anomaly signals, privileged-event share	user_activity rows — real
lib/attendance.js	attendance, overtime, weekly trend	shift_records — real

Nothing on the dashboard is dummy or localStorage-backed. The only local values are UI state (§2.3).

9.2 Are the existing list APIs sufficient?

Yes. Every figure is a count, a filter, an average or a sort over one of the nine collections. All nine are registered; the frontend's requested limits match the server's declared defaults exactly (api-audit.md §3, verified against resources_gen.go).

No aggregation endpoint is proposed. Adding one would duplicate arithmetic that already exists and has to keep existing for the offline/local provider, and would create a second place for "how many were screened" to be defined.

9.3 The one real risk — and it is already solvable, in the frontend

writePage (internal/httpserver/response.go writePage (:52)) returns meta: {total, limit, offset, returned, truncated} on every list response, and truncated is computed as total > offset + len(records).

krow-demo/src/api/httpClient.js:226 returns payload.data and drops meta entirely. So when an organization exceeds 500 shift records or 200 applications, every dashboard figure silently under-reports and nothing says so.

• WIRE — surface meta through httpClient.request() and have the hooks refuse to render a total when truncated is true. Frontend only.
• No backend change. The server already answers the question; the client throws the answer away. internal/httpserver/response.go meta (:20) records that truncated exists precisely so this is fixable without a contract change.

9.4 Activity vocabulary — the one backend change

Covered as H-1 and A-2 in §3. Restated because it lands here: the two workflow endpoints write candidate_hired and worker_assigned; every other producer and consumer in the system — 9 frontend event types, PRIVILEGED_EVENTS, the seed fixture — uses hire_candidate and assign_employee. Two string literals in go-api/internal/service/workflows.go (:212, :373).

---

10. Real missing backend capabilities

Four, exactly as api-audit.md §13 concludes. Each is specified here to the level the "do not invent APIs" rule demands: why it is necessary, request, response, authorization, service, repository, DB impact, migration impact. None of them is required for Phases 1–3.

10.1 LLM / AI inference — NEW capability, route optional

Why. src/api/aiEngine.js implements integrations.Core.InvokeLLM in the browser with no network and no key: it recognises a workflow by the stable phrase its prompt opens with, reads the structured fields the prompt already carries, and scores deterministically. Ten consumers: generateJobDescription, buildResumeFromText, screenCandidate, generateInterviewQuestion, matchTalentForJob, evaluateInterview, owliverQuestion, buildProfileFromConversation (src/lib/krowAi.js), and challengeFollowUp, evaluateChallenge (src/lib/provingGround.js).

There is no route, no key and no config for this anywhere in the backend — internal/config/config.go has AppEnv, Log, HTTP, DB, Seed and nothing else.

Is a route necessary? Not for its own sake. Two of the ten consumers already have a natural home:

• screenCandidate → the screening PATCH it already performs.
• evaluateInterview → the interview creation in §5.2.

The rest are interactive authoring aids. The recommendation is: build the service first, no route. internal/llm with a single Complete(ctx, req) (Response, error) boundary and a deterministic StubProvider mirroring aiEngine.js, wired the same way runtime.UnavailableExecutor is — an interface with an honest default. Then each caller that needs it gets it inside a handler that already exists.

If a general-purpose route is later required it should be one, and it should be the assistant endpoint in §10.3, not a family of per-workflow routes.

• Service: new go-api/internal/llm/ (llm.go, stub.go, anthropic.go).
• Repository: none.
• DB: none. Migration: none.
• Config: go-api/internal/config/config.go gains an LLM block — provider, model id, API key, timeout, max tokens. The key must be loaded the same way DB.Password is (env only; no default; fail loudly).
• Wiring: go-api/cmd/api/main.go, go-api/internal/httpserver/server.go.
• Risk to state now: an LLM call inside a request handler makes that handler's latency unbounded. HTTPConfig.WriteTimeout must be revisited, and a per-call context.WithTimeout is mandatory.

10.2 File storage / upload — NEW, one route genuinely required

Why. integrations.Core.UploadFile({file}) returns {file_url, file_name, file_size} where file_url is a blob: URL from URL.createObjectURL. It is valid for the rest of the session and dies on reload. Consumers: src/pages/KrowIdentity.jsx (selfie), src/components/krow/proving/MediaChallenge.jsx and VideoRecorder.jsx (challenge media).

That URL is then persisted: into worker_profiles.selfie_url and evidence.media_url, both text NOT NULL columns (migrations/000001_initial_schema.up.sql). Every such row already in the database holds a dangling reference. This is the one missing capability that is actively corrupting stored data.

A route is genuinely necessary because there is no existing endpoint that accepts bytes: every registered handler reads a ≤4 MiB JSON body (internal/httpserver/api.go:15).

Field	Specification
Route	POST /api/v1/files
Auth	session required (not in publicPaths)
Authorization	any authenticated role. It is the reference that carries meaning, and the resources holding references are already scoped.
Request	multipart/form-data, one part file. Bounded by a new HTTP.MaxUploadBytes — not maxBodyBytes, which must stay 4 MiB for JSON.
Response	201 {"data": {"file_url": "...", "file_name": "...", "file_size": 12345, "content_type": "image/jpeg", "id": "<uuid>"}} — file_url, file_name, file_size verbatim so aiEngine.UploadFile's three call sites need no change beyond swapping the implementation.
Errors	413 over the size bound; 422 on a rejected content type; the existing envelope.
Content types	an allowlist derived from the three call sites: image/jpeg, image/png, image/webp, video/mp4, video/webm. Never trust the client's declared type — sniff.
Service	new go-api/internal/service/files.go
Repository	new go-api/internal/repo/files.go
Storage	an interface in new go-api/internal/storage/ with a local-filesystem implementation for development and an object-store implementation for deployment. Bytes must not go in PostgreSQL.
Read path	file_url should be a URL this API can serve or redirect from, so access stays behind the session. A public object-store URL would make every uploaded selfie world-readable — do not do that.

DB impact — one new table, one new migration.

migrations/000006_files.up.sql / .down.sql (next free number; depends on 000001 for organizations and users):

files
  id            uuid PRIMARY KEY DEFAULT gen_random_uuid()
  org_id        uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE
  uploaded_by   uuid     REFERENCES users(id) ON DELETE SET NULL
  storage_key   text NOT NULL          -- opaque; never the original filename
  file_name     text NOT NULL
  content_type  text NOT NULL
  file_size     bigint NOT NULL
  created_date  timestamptz NOT NULL DEFAULT now()

  CHECK (file_size > 0)
  CHECK (length(btrim(file_name)) > 0)
  UNIQUE (storage_key)
  INDEX files_org_created_idx (org_id, created_date DESC)

• Foreign keys: org_id CASCADE (tenancy, matching every other table); uploaded_by SET NULL (attribution survives the author leaving, matching job_postings.created_by and agent_definitions.created_by).
• No new enum. content_type is text with an application-level allowlist; the vocabulary will grow, and 000005's header already argues text+CHECK over ALTER TYPE ... ADD VALUE for exactly this reason.
• No FK from worker_profiles.selfie_url or evidence.media_url. They are text URLs today and every existing row holds a dead blob: value; adding a FK would require back-filling data that cannot be recovered. Leave them as URLs.
• Seed: none. Rollback: DROP TABLE files; — safe, because nothing references it. Blobs in the object store are not removed by the rollback; that is deliberate and must be documented in the down migration, as 000005 documents its own choices.

10.3 Assistant streaming — NEW, one route, and only after §7 L2

Why. createHttpProvider({endpoint}) (src/components/ai-assistant/provider.js) is written, tested and unused, because VITE_ASSISTANT_ENDPOINT is unset. Setting it at a route that does not exist would replace working local answers with Assistant request failed: 404.

Do not build this before §7 L2 has at least one real resolver. The endpoint without resolvers can only proxy an LLM, and the whole security argument for moving Owliver server-side (§7.2) is that the data is read from the caller's session.

Field	Specification
Route	POST /api/v1/assistant/stream
Auth	session required
Authorization	any authenticated role. Row visibility comes from the resolvers, which reuse internal/domain/policy.go scopes — a talent caller asking for candidates.pipeline gets their own rows or nothing.
Request	exactly what createHttpProvider already sends: {"contextId": "admin.positions", "capability": "flow", "question": "...", "agent": {...}, "owliverContext": {...}}. The fact sheet is deliberately absent and must stay absent.
Response	text/event-stream. Lines the client already parses: data: {"block": {...}}, data: {"delta": "..."}, data: [DONE]. Non-2xx throws client-side — so an error must be a status code, not an SSE frame.
Headers	Content-Type: text/event-stream, Cache-Control: no-store, X-Accel-Buffering: no.
Service	new go-api/internal/service/assistant.go, built on internal/runtime — runtime.Engine already loads a definition, checks eligibility, resolves dependencies and hands to an executor. Replace UnavailableExecutor with a real one; do not build a parallel loader.
Repository	reuses internal/repo/definitions.go (already has GetAgentByDefinitionID/GetSkillByDefinitionID with personal-over-organization precedence) and internal/repo/repo.go for the data reads.
DB impact	none for the endpoint itself. Conversation persistence is explicitly out of scope — migrations/000005's header lists conversations as deferred, and the frontend keeps history in localStorage under krow_assistant:history. Do not add a table until a product requirement asks for cross-device history.
Migration	none.
Config	HTTP.WriteTimeout must not apply to a stream — use http.ResponseController or a per-route timeout, or a long answer is cut mid-block.

10.4 Web search — NEW, lowest priority, no route of its own

Why. An agent may declare webSearch: true (internal/definition/agent.go parses it into Agent.WebSearch; migration 000005 stores nothing for it — it lives in the markdown). The frontend is honest about it: an agent with webSearch set gets a note saying no search provider is configured in this deployment, rather than an answer that quietly came from nowhere.

No route. Search is a tool the assistant executor calls, not a resource a client fetches. It belongs behind §10.3 as one more capability of the executor.

• Service: new go-api/internal/search/ with a provider interface and a NotConfigured default that returns the same honest refusal the UI already shows.
• Config: provider + key in go-api/internal/config/config.go.
• DB: none. Migration: none.

10.5 Other gaps found during this audit

#	Gap	Class	Where
G-1	Activity event-type mismatch (candidate_hired/worker_assigned)	CHANGE	internal/service/workflows.go:212,373
G-2	Assign cannot create the application the frontend requires	CHANGE	internal/service/workflows.go, internal/httpserver/workflows.go
G-3	Talent cannot complete an interview (403 on the linked PATCH)	CHANGE	§5.2
G-4	serverSupplies ignores Derived.TalentOnly	CHANGE	internal/service/service.go serverSupplies (:266)
G-5	PATCH on a definition silently drops status when markdown is present	CHANGE	internal/service/definitions.go:241,415
G-6	No optimistic concurrency on agent publish	CHANGE (optional)	internal/repo/definitions.go UpdateAgent (:270)
G-7	An operator-created worker profile locks its subject out	CHANGE (deferred)	§5.4 TP-1
G-8	internal/runtime is complete and unwired	not a defect — the seam for §10.3	internal/runtime/
G-9	meta.truncated discarded by the client	WIRE	krow-demo/src/api/httpClient.js:226
G-10	Admin console has no role gate	WIRE	krow-demo/src/pages/admin/AdminRoute.jsx AdminRoute (:23)
G-11	README.md:106 says "51 registered routes"; the router registers 53	doc drift	README.md
G-12	docs/api-contract.md §1 says "Auth: None in v1"	doc drift	docs/api-contract.md

---

11. Database impact, per required change

The schema is at 000005. The next free number is 000006. Every migration below depends on 000001 for organizations and users.

11.1 Changes requiring NO database work

This is most of the plan, and it is the point.

Change	Existing tables touched	New table	New column	FK	Index	Enum	Migration	Seed	Rollback
§3.1 Hire adoption (H-1/H-2/H-3)	job_applications, staff, user_activity	no	no	no	no	no	none	no	revert two string literals
§3.2 Assign adoption + application creation (A-1/A-2)	assignments, job_applications, user_activity, job_postings	no	no	no	no — reuses job_applications_posting_email_key and job_applications_org_email_idx	no	none	no	revert the handler
§3.3/§3.4 Definition adoption	agent_definitions, skill_definitions, user_preferences	no	no	no	no	no	none — 000005 already created everything	no	data written to the tables would need re-mirroring into user_preferences.extra; see 11.4
§5.2 Interview link (G-3)	ai_interviews, job_applications	no	no	no — job_applications.interview_id exists since 000002	no	no	none	no	revert the handler
§5.1 serverSupplies fix (G-4)	none	no	no	no	no	no	none	no	trivial
§6.4 definition PATCH semantics (G-5)	none	no	no	no	no	no	none	no	trivial
§6.4 publish concurrency (G-6)	agent_definitions	no	no	no	no	no	none	no	trivial
§8 Flow data	none	no	no	no	no	no	none	no	n/a
§9 Dashboard	none	no	no	no	no	no	none	no	n/a
§10.1 LLM service	none	no	no	no	no	no	none	no	n/a
§10.3 Assistant stream	reads only	no	no	no	no	no	none	no	n/a
§10.4 Web search	none	no	no	no	no	no	none	no	n/a

11.2 000006_files — the only migration this plan requires

Full shape in §10.2.

• Existing tables: organizations, users (referenced only).
• New table: files.
• New columns on existing tables: none.
• Foreign keys: files.org_id → organizations(id) ON DELETE CASCADE; files.uploaded_by → users(id) ON DELETE SET NULL.
• Indexes: UNIQUE (storage_key); files_org_created_idx (org_id, created_date DESC). No index on uploaded_by — attribution only, matching the reasoning already written into 000005 for created_by.
• Enums: none. content_type is text + an application allowlist.
• Seed: none. seed/fixtures/seed.json is untouched; the seeder (go-api/internal/seeder/) needs no change.
• make gen-resources: only if files is to become a domain.Resource. It should not be — it has a non-JSON request body and no list surface. Keep it hand-written, exactly as the definition endpoints are.
• Rollback: DROP TABLE files;. Blobs already written to the object store survive the rollback and must be removed out of band; state that in the .down file.

11.3 000007_worker_profile_claim — conditional, Phase 7 only

Only if TP-1 (§5.4) is resolved by claiming rather than by widening the read predicate. Widening the predicate needs no migration at all, which is why it is the recommended shape.

If claiming is chosen: no new table, no new column — the change is a UPDATE worker_profiles SET user_id = ... WHERE user_id IS NULL AND email = ... executed at login, plus a partial index (org_id, email) WHERE user_id IS NULL to make the lookup cheap. Rollback drops the index; the claimed user_id values are not reversible, which is the reason this needs a product decision first.

11.4 Rollback consideration for §3.3/§3.4 — the one that is not free

Adopting the definition endpoints creates rows in agent_definitions and skill_definitions that have no counterpart in user_preferences.extra. Reverting the frontend afterwards would make every definition authored in the meantime invisible.

Mitigations, in order of preference:

1. Dual-write during the cutover window. The frontend writes both the table and customSkills/customAgents for one release, reads from the table, then stops writing preferences. No server change; the merge is a client concern.
2. A one-off backfill. Read every user_preferences.extra.customSkills / customAgents entry, POST each to the corresponding endpoint. This is a script, not a migration — it must run through the API so that validation, parsing and the projections are applied by the code that owns them. Put it in scripts/, beside oracle.mjs.
3. Do not write a SQL migration that copies jsonb into the tables. It would have to re-implement internal/definition's parser in SQL to fill definition_id, name, description, status, version and pages.

user_preferences.extra keys must not be deleted by the cutover. Leaving the old blob in place costs a few kilobytes on GET /me and is the entire rollback plan.

---

12. Implementation order

Seven phases. Phases 1–3 need no migration and no new route. Phases 1, 2 and 5 are largely frontend work against a server that is already correct.

Phase 1 — Existing API / frontend wiring (no server change)

#	Task	Files	Class
1.1	Surface meta through request() and stop dropping truncated	krow-demo/src/api/httpClient.js:226 and the hooks in src/lib/krowHooks.js	WIRE
1.2	Role-gate the admin console — role ∈ {admin, employer} for operator screens, admin for KROW Forge authoring and certification deletion	krow-demo/src/pages/admin/AdminRoute.jsx	WIRE
1.3	Delete useBadges (krowHooks.js:537) and User: 'users' (httpClient.js:96) — both would 404	krow-demo	WIRE
1.4	Delete src/api/store.js (imported by nothing)	krow-demo	WIRE
1.5	Fix the two documentation drifts	README.md:106 (51→53), docs/api-contract.md §1 (auth)	doc
1.6	Optional: seed the seven ROLE_CATEGORIES as rows and delete the constant	seed/fixtures/seed.json, krow-demo/src/lib/roleCategories.js	seed

Exit criterion: no frontend call reaches a 404 or 405; a truncated list is visibly truncated; a non-admin cannot open an admin-only action.

Phase 2 — Workflow adoption

Server first, then frontend, in this order — the frontend cannot adopt Assign until A-1 lands.

#	Task	Files	Class
2.1	candidate_hired → hire_candidate; worker_assigned → assign_employee	go-api/internal/service/workflows.go:212,373	CHANGE
2.2	Align the assign source default with the column default (owliver)	go-api/internal/service/workflows.go:336	CHANGE
2.3	Extend AssignWorker with an optional application: payload; upsert by (job_posting_id, email) inside the transaction; link the assignment	go-api/internal/service/workflows.go	CHANGE
2.4	Add {"job-applications", domain.OpCreate} to the assign requirement list	go-api/internal/httpserver/workflows.go handleAssign (:127)	CHANGE
2.5	Fix serverSupplies to honour Derived.TalentOnly (G-4)	go-api/internal/service/service.go serverSupplies (:266)	CHANGE
2.6	Link the application from POST /ai-interviews, transactionally (G-3)	go-api/internal/service/service.go or new internal/service/interviews.go; reuse WorkflowService.inTx	CHANGE
2.7	Replace useHireCandidate with one call to POST /job-applications/{id}/hire, sending {role, profile_tier}; drop the separate logActivity	krow-demo/src/lib/krowHooks.js useHireCandidate (:296)	WIRE
2.8	Replace useAssignWorkers with one call to POST /job-postings/{id}/assignments	krow-demo/src/lib/krowHooks.js useAssignWorkers (:406)	WIRE
2.9	Remove the now-redundant PATCH from AIInterviewModal.finishInterview	krow-demo/src/components/krow/AIInterviewModal.jsx finishInterview (:155)	WIRE

Exit criterion: a hire is one request and one transaction; an assign of n workers is one request and one transaction; a talent user can complete an interview; activity.signals still recognises hire_candidate as privileged.

No migration. No new route.

Phase 3 — Agent / Skill migration

#	Task	Files	Class
3.1	Fix the silent status drop on a markdown PATCH (G-5)	go-api/internal/service/definitions.go:241,415	CHANGE
3.2	Optional: optimistic concurrency on agent publish (G-6)	go-api/internal/repo/definitions.go UpdateAgent (:270)	CHANGE
3.3	Point useAgents at /agent-definitions — save/remove/publish/archive/restore/duplicate/sourceFor	krow-demo/src/lib/agents/useAgents.js	WIRE
3.4	Point customSkills readers/writers at /skill-definitions — the single writer is src/lib/skills/customSkills.js; the readers are usePageSkills / useWorkforcePaths	krow-demo/src/lib/skills/{customSkills,usePageSkills}.js and the 21 consumers	WIRE
3.5	Dual-write for one release, then stop writing customSkills / customAgents	krow-demo	WIRE
3.6	Backfill script: read user_preferences.extra, POST each definition through the API	new scripts/backfill-definitions.mjs	script
3.7	Leave disabledSkills and removedSkills in preferences — migration 000005 says so	—	—

Exit criterion: an authored agent or skill survives a sign-in on another device; GET /me no longer carries an unbounded definition blob; an organization-visible definition is visible to colleagues and refused to talent authors.

No migration. Rollback plan in §11.4 — do not delete the preference keys.

Phase 4 — Owliver backend support

Only after Phase 3, because the server must hold the definitions before it can answer from them. Incremental by construction (§7.4).

#	Task	Files
4.1	Transcribe L1: capabilities (10), data sources (25), section types (9), periods (6), placement→context rules	new go-api/internal/definition/owliver.go, ui.go; extend vocabulary.go
4.2	Extend scripts/oracle.mjs to capture owliverConfig.js / uiConfig.js output; extend internal/definition/conformance_test.go	scripts/oracle.mjs, go-api/internal/definition/
4.3	Stop deferring — validate owliver: and ui: where L1 covers them; keep Skill.Deferred for whatever remains	go-api/internal/definition/skill.go deferredBlocks (:235)
4.4	L2, one source at a time, reusing internal/domain/policy.go scopes and internal/repo	new go-api/internal/service/sources/
4.5	Advertise only the capabilities whose sources have a server resolver	go-api/internal/service/assistant.go

No migration. No route until 4.5 has something to answer with.

Phase 5 — Dashboard / flow data

Nothing to do on the server (§8.3, §9.2). This phase exists so the decision is recorded rather than revisited.

#	Task
5.1	Confirm no aggregation endpoint is added. Every dashboard figure is a count/filter/average over one of nine registered lists.
5.2	Confirm no flow-data endpoint is added. resolveSkillData reads the collections SkillSurface.jsx:81-119 already loads.
5.3	If a figure is wrong, the cause is Phase 1.1 truncation, not a missing endpoint. Check meta.truncated first.

Phase 6 — AI / file / assistant integrations

Ordered by how much damage the absence is doing.

#	Task	Files	New route?	Migration
6.1	File storage — the only capability currently corrupting stored data (blob: URLs in worker_profiles.selfie_url, evidence.media_url)	new internal/storage/, internal/service/files.go, internal/repo/files.go, internal/httpserver/files.go; internal/config/config.go; cmd/api/main.go	yes — POST /api/v1/files	000006_files
6.2	Swap aiEngine.UploadFile to call it; the return shape is unchanged	krow-demo/src/api/aiEngine.js	no	—
6.3	LLM service with a deterministic stub default	new internal/llm/; internal/config/config.go; per-call context.WithTimeout	no	none
6.4	Use it inside handlers that already exist — screening, interview evaluation	internal/service/	no	none
6.5	Assistant streaming, built on internal/runtime by replacing UnavailableExecutor	new internal/service/assistant.go, internal/httpserver/assistant.go; cmd/api/main.go	yes — POST /api/v1/assistant/stream	none
6.6	Set VITE_ASSISTANT_ENDPOINT — not before 6.5 ships, or working local answers become 404s	krow-demo deployment config	no	—
6.7	Web search as an executor tool, NotConfigured by default	new internal/search/; internal/config/config.go	no	none

Two new routes total for the whole plan — 53 → 55. Both are justified above: one because no handler accepts bytes, one because the client already speaks a streaming protocol nothing serves.

Phase 7 — Tests and integration verification

#	Task	Files
7.1	Assert the route count. Nothing does today — Endpoints() is only logged (cmd/api/main.go:65). Add a test pinning 52/53 so a route cannot be added or lost silently.	go-api/internal/httpserver/server_test.go (new)
7.2	Workflow tests for the Phase 2 changes: assign-creates-application, assign-links-existing, talent completes an interview, event types	go-api/internal/httpserver/workflows_test.go, api_test.go
7.3	RBAC matrix regression — every (role, resource, op) triple against policy.go	go-api/internal/httpserver/rbac_test.go (exists, 730 lines — extend)
7.4	Conformance suite stays green through Phase 4 L1	go-api/internal/definition/conformance_test.go
7.5	Definition CRUD: shadow-by-id precedence, visibility immutability, talent refusal, size bound, idempotent delete	go-api/internal/httpserver/definitions_api_test.go (exists, 848 lines — extend)
7.6	Upload tests: size bound, content-type sniffing, tenancy on read	new
7.7	Resolve TP-1 (§5.4) — needs the product decision first	internal/domain/policy.go, internal/repo/repo.go, possibly 000007
7.8	End-to-end against a seeded database: make migrate-up && make seed, then the full hire → assign → interview → evidence loop	Makefile targets exist

---

13. Drift found, and where it belongs

Where	Issue	Fix in
README.md:106	"51 registered routes" — the router registers 53; the two workflow routes are missing from the tally	this repo, Phase 1.5
docs/api-contract.md §1	"Auth: None in v1. Every endpoint is unauthenticated." — sessions, argon2id and cookie middleware have existed since 000004 / internal/auth/	this repo, Phase 1.5
docs/api-contract.md §2	lists 34 Live + 4 "unreachable today" = the "38 endpoints" figure. It is a table of entity rows, not a count of registered routes.	clarify wording, Phase 1.5
krow-demo/src/api/store.js	173 lines, imported by nothing	krow-demo, Phase 1.4
krow-demo/src/api/seed.js	1,928 lines retained for one export, DEMO_USER.preferences	krow-demo — leave; the synchronous accessor needs it
krow-demo/src/lib/krowHooks.js:537	useBadges, zero consumers, no route	krow-demo, Phase 1.3
krow-demo/src/api/httpClient.js:96	User: 'users' names a resource that does not exist	krow-demo, Phase 1.3
krow-demo/src/pages/admin/AdminRoute.jsx AdminRoute (:23)	comment promises a Phase-3D role check that was never added	krow-demo, Phase 1.2

---

14. Backend file index — everything this plan would touch

File	Phase	Why
go-api/internal/service/workflows.go	2	event types (:212, :373), assign source (:363), AssignWorker.application + upsert
go-api/internal/httpserver/workflows.go	2	add job-applications:Create to the assign requirements (:141-145)
go-api/internal/service/service.go	2	serverSupplies must honour Derived.TalentOnly (:266-276); transactional Create for ai-interviews
go-api/internal/service/interviews.go	2	(new, optional) holds the interview→application link if it does not belong in service.go
go-api/internal/service/definitions.go	3	status-with-markdown PATCH semantics (:230, :415)
go-api/internal/repo/definitions.go	3	(optional) version predicate on agent update (:261-305)
go-api/internal/definition/vocabulary.go	4	extend with the Owliver/UI vocabularies
go-api/internal/definition/owliver.go, ui.go	4	(new) L1 transcription
go-api/internal/definition/skill.go	4	stop deferring what L1 now covers (:237)
go-api/internal/definition/conformance_test.go	4	extend to the new oracle cases
scripts/oracle.mjs	4	capture owliverConfig.js / uiConfig.js output
go-api/internal/service/sources/	4	(new) L2 resolvers
go-api/internal/storage/	6	(new) object-store boundary
go-api/internal/service/files.go	6	(new)
go-api/internal/repo/files.go	6	(new)
go-api/internal/httpserver/files.go	6	(new) POST /api/v1/files
go-api/internal/llm/	6	(new) inference boundary + deterministic stub
go-api/internal/search/	6	(new) search boundary + NotConfigured default
go-api/internal/service/assistant.go	6	(new) built on internal/runtime
go-api/internal/httpserver/assistant.go	6	(new) POST /api/v1/assistant/stream
go-api/internal/runtime/executor.go	6	replace UnavailableExecutor
go-api/internal/config/config.go	6	LLM, Storage, Search, HTTP.MaxUploadBytes
go-api/cmd/api/main.go	6	wire the new services
go-api/internal/httpserver/server.go	6	register the two new routes; keep Endpoints() honest
migrations/000006_files.up.sql / .down.sql	6	the only required migration
migrations/000007_worker_profile_claim.*	7	conditional — only if TP-1 is resolved by claiming
go-api/internal/httpserver/server_test.go	7	(new) pin the route count
go-api/internal/httpserver/{workflows,api,rbac,definitions_api}_test.go	7	extend
README.md, docs/api-contract.md	1	drift

---

15. Summary

• 53 routes are registered. 39 are exercised by the frontend, 13 exist and are ignored, 1 (GET /health) is public infrastructure.
• Nothing the frontend calls today is missing from the server.
• 12 of the 13 ignored routes should be adopted — 2 workflow endpoints that make hire and assign transactional, and 10 definition endpoints that are where authored agents and skills were always meant to live. The 13th (GET /me/preferences) is correctly unused.
• Phases 1–3 require no migration and no new route. They require six small server changes (§10.5 G-1…G-6) and a body of frontend wiring.
• Flow-chart data and every dashboard figure are already fully served by the nine existing list endpoints. No aggregation endpoint is proposed. The one real risk is silent truncation, and the server already reports it — the client discards the report.
• Four capabilities genuinely do not exist: LLM inference, file storage, assistant streaming, web search. Two new routes are proposed for them — POST /api/v1/files and POST /api/v1/assistant/stream — and one migration, 000006_files. File storage is first, because it is the only one currently writing dead references into worker_profiles and evidence.
• internal/runtime is already built for the assistant — loader, eligibility, dependency resolution, executor boundary, 890 lines of tests — and wired to nothing. It is the seam. Do not build a second one.