Add gated submissions API and agent intake skill

[JasonWildMe]

Agents, partner apps and human users need durable uploads, validation previews and retry-safe import acceptance. This adds a disabled-by-default /api/v3/submissions resource alongside bulk import: draft, upload photos, supply JSON rows, validate, commit once, and retrieve source-row-to-record mappings. Existing bulk-import routes and defaults remain unchanged.

New submissions default to detection followed by individual identification matching. Explicit processing.mode=import-only skips both; saved submissions retain their original mode. Matching produces candidates for review, not automatic identity assignment.

Enrollment and human access

• Site administrators explicitly assign api-submission in the context0 user editor. No UUID configuration or restart is needed for enrollment changes; even administrators need the role.
• API Access offers Read data (default) and Data import. Data import requests submissions:write after password confirmation. The two token audiences remain separate.
• Persisted enrollment is checked for writes and before imports execute. Revocation blocks subsequent writes and unstarted imports; owner status reads remain available. Already executing imports and existing records are unaffected.
• Migration: submissions.allowedUserIds is ignored. Grant the role to existing pilot accounts during rollout. Global admission, commit and worker switches remain unchanged.

Included

• Reuses existing validators, media/importer and detection pipeline, with strict configured-value validation, owned drafts, revision checks, idempotency keys, private staging and durable worker/recovery state.
• Separate import, indexing, derivative and AI handoff statuses; dispatched reports handoff, not completed identification.
• Compose staging mount, commented private settings, OpenAPI, resumable Python client, and operator instructions.
• Imports page labels the column Source and identifies submission-origin imports as API.
• Public agent skills explain exact formats, field-specific validation failures, recovery and the new token UI; skills updated last.
• Actual Claude architecture, implementation and corrective reviews. Final correction approved. Role/UI review disposition.

Verification

• Full Java regression/WAR build: 1,132 tests, zero failures/errors, seven skipped. Final rename correction then passed 20 affected authorization, PostgreSQL and agent-skill tests and WAR packaging.
• API Access/token helper: 10 Jest tests passed; React production build completed with existing warnings. Contract checker passed all 11 operations and 21 examples.
• Prior Flakebook staging test: 150 encounters/media imported; independent Claude audit verified exposed fields and all 150 original-photo hashes/sizes. Detections and embeddings were present. Eight deliberate validation failures returned the expected field errors; invalid commit returned 422 without creating a job.
• Encounter search summaries remained partially stale after that live test; this is an outstanding indexing-consistency finding. Read-only evidence did not establish completion of every identification task.
• The role enrollment and token UI follow-up has not yet been deployed or live-tested.

Deployment

Apply SUBMISSION metadata (including nullable AI_STATE and AI_STARTED_AT for earlier pilot schemas), private staging mount/permissions and private global settings. Deploy the frontend build as well as the WAR. The WAR excludes WEB-INF/web.xml, so apply the servlet/Shiro mappings through the installation descriptor process. Restart after first enabling the worker. Assign api-submission to pilot accounts, then verify Data import token issuance, admission and role revocation before widening access.

Pilot runbook · Agent skill

[codecov-commenter]

Codecov Report

❌ Patch coverage is 88.88889% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 54.89%. Comparing base (dcf6f46) to head (b1408b2).

Files with missing lines	Patch %	Lines
frontend/src/models/auth/useMintToken.js	50.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1776      +/-   ##
==========================================
+ Coverage   54.84%   54.89%   +0.04%     
==========================================
  Files         314      314              
  Lines       12704    12717      +13     
  Branches     4006     4122     +116     
==========================================
+ Hits         6968     6981      +13     
  Misses       5441     5441              
  Partials      295      295              

Flag	Coverage Δ
backend	54.89% <88.88%> (+0.04%)	⬆️
frontend	54.89% <88.88%> (+0.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[naknomum]

looks good