Telemachus — Feature Requirements

Status record, not an agenda. This began (Aug 2026) as a skeleton to be filled in from the predecessor's inventory. It is now a record of what the platform requires and where each requirement stands. Every line links to its design doc and, where it exists, its implementation. Checked means built and tested, not "decided".

Legend: [x] built · [~] partial, see note · [ ] not started

Inputs

• Odysseus feature inventory: ../../odysseus/Features.md (what the predecessor does).
• Design tenets: see the project README.md.
• Subsystem index + how they interlock: design/README.md.
• Decision log: design/decisions.md.

Platform requirements

• RBAC & teams — roles, groups, capability/data/management gating. One contract (can?) governs every resource. Design: design/rbac-and-teams.md · impl domain/authz/.
• Quotas — per-user / per-team limits; metered and enforced at admission. v1 dimensions are AI-first (tokens / requests / concurrency / rate) plus storage.bytes as a gauge. Design: design/quotas.md · impl domain/quota/.
• AI concurrency control — queuing of AI use and multi-step flows; rate/concurrency limits to prevent accidental self-DDOS or host/upstream max-out. Design: design/ai-queue-and-concurrency.md · impl domain/sched/.
• Queuing of resources to enable workload distribution, enforcement of any custom policy for system use. Same scheduler; a workload queue, not a message bus. Remote transport deliberately deferred (SCHED‑3).
• Persistence — SQLite for prototyping, PostgreSQL as the target; schema abstraction so no SQLite-only assumptions leak in. pkgs/db-kit/portable.rkt rewrites ?→$n; the unit suite and both smoke suites run on either dialect.

• [~] Management interface — per-feature admin surface; activate/deactivate contract every feature must satisfy. Built in practice (features registry, per-feature Admin surfaces, shared audit_log). The uniform contract is still unwritten — see the follow-up note in design/README.md.
• [~] Security model — auth, session, secret handling, plugin isolation, prompt-injection posture, multi-tenant data isolation. Built in practice: password+2FA, token scopes (RBAC‑4), sandboxed out-of-process plugins, org gate at step 0 of can?, SigV4 for S3, secrets handled at a stated trust boundary. No consolidated design doc yet — the posture is currently spread across the subsystem docs and CLAUDE.md.

• SDK contract — how third parties add tools, integrations, datasets, localizations; declaration vs execution; consent/scope enforcement. define-tool and define-workflow emit validated specs, plugin seams exist for tools/workflows/blob stores/onboarding, and the beta funnel ships a browser SDK. Published as reference/sdk.md and reference/plugins.md, generated with the rest.
• Backend APIs & protocols — the stable surface between swappable frontends and backends. Declared in server/routes.rkt (method, path, auth, permission, feature, one line of doc; the server refuses to boot if the table and the handlers disagree) and rendered to reference/api.md.
• Localization (i18n), top to bottom — every user-facing surface localizable; English at launch; then Japanese, Dutch, Latin American Spanish produced by the localization tool. Runtime: catalogs + ICU + fallback chain, instance default locale and off switch, localized server refusals, localized funnel copy. The console's own chrome is in the same catalogs (ui. namespace; English source in static/ui-strings.json, folded into en.json by the extractor; served pre-auth by GET /api/i18n/catalog, chain-resolved server-side) — so one extract, one Manager and one CI gate cover the server and the UI alike. English, Japanese, Dutch and Latin American Spanish ship, 190/190 each. nl and es-419 were produced by the Localization Manager: AI-drafted through the scheduler under the team's AI quota, every string human-reviewed (169 of 340 UI drafts corrected), exported, and passing the tool's own gate. That is the proof the flagship exists for. Design: design/localization.md · impl domain/i18n/.
• Documentation — generated, localizable project docs. telemachus-docs evaluates the tool registry, the plugin loader, the workflow specs, the permission catalog (every permission now carries a description beside its declaration) and the route table, and renders docs/reference/ — tools, workflows, permissions with the role matrix, the HTTP API, plugins, the SDK. Committed and drift-gated in CI; byte-identical from identical sources. Every description is a doc.* message in the catalogs (249 of them, via reference/strings.json), so the Localization Manager translates them and render --locale ja writes reference/ja/. Design: design/documentation-generation.md.

Generic applications

• Chat — console tab; real model via TELEMACHUS_MODEL_URL, deterministic fallback otherwise.
• Research — realized as the documents / repository app rather than a separate surface: binary documents of any format, team access control with creator-set visibility, content search across extracted text. Design: design/document-repository.md.
• Document translation — console tab with team history and a per-language glossary; meters AI spend through the usual quotas. Impl domain/apps/translate.rkt.
• Document Search — notes + repo objects by key, filename and extracted content, each row filtered by can?. Impl domain/apps/search.rkt; extraction via the index-documents workflow.
• Document sharing with permissions — view / edit / manage capabilities over the grants table; a user or a team in the same org as principal; optional expiry; only manage re-shares; derived documents inherit at creation. Design: design/document-sharing.md. The share dialog picks a person or a team in the org, a capability and an optional expiry; the Repository tab filters to "Shared with me".
• Document workflows (the first-user path) — a team uploads a file and a workflow processes it: text → fields validated against a JSON schema (refused on mismatch) → a filled form template → translations, every output a repository document beside the source with provenance and the source's grants. Shipped as the doc-pipeline plugin over four core tools, run by hand from any document or fired by an upload — console, shim or S3 — through a trigger (/api/doc-triggers: key prefix, content types, the workflow and its configuration; exactly once per version; as the uploader). The Workflows tab's Automations card manages triggers; every document carries a "Processed by" panel; form templates may be Markdown, HTML or DOCX; the e2e gate runs the invoice scenario end to end. Design: design/document-workflows.md. PDF output: doc_render {format: "pdf"} through pandoc + tectonic (DWF‑6, slice 68).
• Localization Manager — extract unlocalized strings, team-managed translation completion, AI-assisted drafts, CI gate on commits. Flagship that proves the platform can build tools. The extractor/lint, the telemachus-localize CLI, the CI gate, and (migration 0024) the team workflow: per-string status lifecycle with derived missing/stale, coverage dashboard, review gating that refuses self-approval, the Localize console tab, and AI drafting as scheduler jobs metered against the team's AI quota, with a structural guard that refuses drafts that lose or invent placeholders. Import/export keeps locales/*.json the shipping artifact; discard throws away a bad machine run without touching human work, and a queued draft reports the team's AI budget so an over-budget queue does not look like a hang. Used to produce nl and es-419, server and console (see the localization line above).
• Pull-model inference hosts — an executor that comes to the work: a worker holding a token scoped to one permission claims infer.chat jobs from the same queue everything else uses, under a lease with heartbeats, and posts the result; capability matching at claim; run-chat routes a named pull executor through it so every model-using tool works unchanged; per-org executors close TEN‑2e. Reference worker cli/telemachus-worker.rkt. Design: design/pull-executors.md.
• Knowledge Graph — entities and relations extracted from the team's documents, every fact traceable to the document and version that asserted it. Visibility is inherited from the sources through can? (a fact shows if any readable document mentions it; a private document's snippet stays private); a new version supersedes; deleting a document forgets its facts. Extracted by the index-knowledge workflow (the extractor refuses a reply whose snippets are not verbatim), surfaced in search, through the agent's kg_query tool with citations, and in the Knowledge tab. Design: design/knowledge-graph.md.

Out of scope / non-goals

• Open-core tiers — explicitly a non-goal (pure OSS, no held-back tier).

Reversed

• Cross-legal-entity multitenancy was listed here as out of scope (decision TEN: a deployment serves one organization, many teams OK). That is no longer true. Decision TEN‑2 supersedes it: an org layer sits above teams and TELEMACHUS_MULTITENANT=1 lets several companies share one instance, isolated by an org gate that runs before every permission, grant and token-scope check, with a superadmin plane and a per-company org-admin plane. An org admin manages but does not read (TEN‑2a); reading across a company's teams is the deliberately granted org_reader role (TEN‑2h), team-visible data only, via ?scope=org. Design: design/multi-tenancy.md · operators: ops/multi-tenancy-runbook.md. The hosted offering can now serve separate legal entities either way — one isolated instance per tenant, or several orgs on one instance.