# SpecThread API for the web app The ASP.NET Core API in app/api owns product data and its rules (ADR-002, ADR-040). This page summarizes the contract. The authoritative schema is the OpenAPI document, served in Development at `/openapi/v1.json`. ## Calling the API from Next.js Call it from server code only (server components, server actions, route handlers): ```ts import { apiFetch } from "@/lib/api"; const response = await apiFetch("/projects"); if (!response.ok) { /* handle 400, 403, 404, 409 below */ } const projects: Project[] = await response.json(); await apiFetch(`/projects/${projectId}/requirements`, { method: "POST", body: JSON.stringify({ title, description, acceptanceCriteria }), }); ``` `apiFetch` exchanges the user's Better Auth session for a short-lived JWT and sends it as `Authorization: Bearer `. It needs `SPECTHREAD_API_URL` (server-only; see app/web/.env.example). For local development run the API with `dotnet run --project app/api --urls http://localhost:5000`, with `Auth__Issuer` set to the web origin (`http://localhost:3000`) and `ConnectionStrings__Database` configured (docs/DATABASE.md). Do not call the API from client components; there is no CORS. ## Endpoints All endpoints require a signed-in user (401 otherwise). "Member" means the user belongs to the project's team in any role; non-members get 404 as if the project did not exist. "Editor" means a member whose team role is Owner, Admin, or Member; Reviewers and Observers get 403 with "Your role on this team can read this project but not change it." (ADR-058). Recording a decision needs any role except Observer. | Method | Path | Who | Body | Success | |---|---|---|---|---| | GET | `/projects` | any user | | 200 `Project[]` (active only, by name) | | POST | `/projects` | team Owner/Admin with completed onboarding | `{ name, teamId }` | 201 `Project` in that team | | GET | `/projects/{projectId}` | member | | 200 `Project` (archived included) | | PATCH | `/projects/{projectId}` | team Owner/Admin | `{ name }` | 200 `Project` | | POST | `/projects/{projectId}/archive` | team Owner/Admin | | 200 `Project` (idempotent) | | POST | `/projects/{projectId}/restore` | team Owner/Admin | | 200 `Project` (idempotent) | | GET | `/teams/{teamId}/projects` | team member | query `archived=true` for archive; default false | 200 `Project[]`, by name then ID | | GET | `/projects/{projectId}/requirements` | member | query `archived=true` for archived only; default active only; `milestone=` for one label | 200 `RequirementSummary[]` (oldest first) | | POST | `/projects/{projectId}/requirements` | editor | `{ title, description?, acceptanceCriteria, documentIds?, milestone? }` | 201 `Requirement` | | GET | `/requirements/{requirementId}` | member | | 200 `Requirement` | | PUT | `/requirements/{requirementId}` | editor | `{ title, description?, acceptanceCriteria, documentIds?, version, confirmCriteriaChange? }` | 200 `Requirement` (409 `accepted_criteria_change`) | | GET | `/requirements/{requirementId}/criteria-versions` | member | | 200 `CriteriaVersion[]` (newest first) | | GET | `/requirements/{requirementId}/criteria-versions/{number}` | member | | 200 `CriteriaVersion` | | PUT | `/requirements/{requirementId}/milestone` | editor | `{ milestone }` (null or empty clears) | 200 `{ milestone }` | | GET | `/projects/{projectId}/milestones` | member | | 200 `string[]` (labels on active requirements, in order) | | GET | `/requirements/{requirementId}/follow-ups` | member | | 200 `FollowUps` | | POST | `/requirements/{requirementId}/follow-ups` | editor | `{ originalRequirementId }` | 201 `FollowUpLink` | | DELETE | `/requirements/{requirementId}/follow-ups/{originalRequirementId}` | editor | | 204 | | GET | `/requirements/{requirementId}/comments` | member | | 200 `Comments` | | POST | `/requirements/{requirementId}/comments` | member, any role | `{ body, parentId? }` | 201 `Comment` (409 when archived or the parent was deleted) | | PATCH | `/requirements/{requirementId}/comments/{commentId}` | the comment's author | `{ body }` | 200 `Comment` (409 when archived or deleted) | | DELETE | `/requirements/{requirementId}/comments/{commentId}` | the author, team Owner/Admin | | 204 (404 once deleted; 409 when archived) | | POST | `/requirements/{requirementId}/archive` | editor | | 200 `Requirement` (idempotent) | | POST | `/requirements/{requirementId}/restore` | editor | | 200 `Requirement` (idempotent; 409 in an archived project) | | GET | `/projects/{projectId}/members` | member | | 200 `ProjectMember[]` (owner first, then by name) | | POST | `/projects/{projectId}/members` | member | | 410 (retired) | | DELETE | `/projects/{projectId}/members/{userId}` | member | | 410 (retired) | | POST | `/github/repositories` | any user | `{ githubToken }` | 200 `{ installUrl, repositories: AvailableRepository[], truncated }` | | GET | `/projects/{projectId}/repository` | member | | 200 `{ repository: ProjectRepository \| null }` | | PUT | `/projects/{projectId}/repository` | team Owner/Admin | `{ installationId, repositoryId, githubToken }` | 200 `{ repository: ProjectRepository }` | | DELETE | `/projects/{projectId}/repository` | team Owner/Admin | | 204 (idempotent) | | GET | `/requirements/{requirementId}/evidence` | member | | 200 `Evidence[]` (oldest first by GitHub's created time) | | GET | `/requirements/{requirementId}/evidence/search` | member | query `q`: words from a title | 200 `{ items: EvidenceSearchItem[] }` (at most 20) | | GET | `/requirements/{requirementId}/evidence/history` | member | | 200 `EvidenceEvent[]` (newest first) | | GET | `/requirements/{requirementId}/evidence/suggestions` | member | | 200 `EvidenceSuggestion[]` (undecided, by number) | | POST | `/requirements/{requirementId}/evidence/suggestions/scan` | editor | | 200 `EvidenceSuggestion[]` | | POST | `/requirements/{requirementId}/evidence/suggestions/{suggestionId}/confirm` | editor | | 201 `Evidence` (`source: "suggested"`) | | POST | `/requirements/{requirementId}/evidence/suggestions/{suggestionId}/reject` | editor | | 204 | | POST | `/requirements/{requirementId}/evidence/{evidenceId}/move` | editor | `{ targetRequirementId }` | 200 `Evidence` | | POST | `/requirements/{requirementId}/evidence` | editor | `{ reference }` | 201 `Evidence` | | POST | `/requirements/{requirementId}/evidence/refresh` | editor | | 200 `Evidence[]` | | DELETE | `/requirements/{requirementId}/evidence/{evidenceId}` | editor | | 204 | | GET | `/requirements/{requirementId}/reviews` | member | | 200 `Review[]` (newest first) | | POST | `/requirements/{requirementId}/reviews` | member except Observer | `{ decision, note?, version }` | 201 `Review` | | GET | `/projects/{projectId}/documents` | member | | 200 `Document[]` (active only, newest first) | | POST | `/projects/{projectId}/documents` | editor | multipart: `file`, optional `title` | 201 `Document` | | GET | `/documents/{documentId}` | member | | 200 `Document` (archived included) | | GET | `/documents/{documentId}/content` | member | | 200 file bytes, as an attachment | | POST | `/documents/{documentId}/archive` | editor | | 200 `Document` (idempotent) | Documents (ADR-047) are PDF, DOC, or DOCX files of at most 4 MiB. The API checks the file's leading bytes against its extension and stores the content type for that extension. A missing title becomes the file name without its extension. Upload with `apiFetch(path, { method: "POST", body: formData })`; `apiFetch` sets a JSON content type only for string bodies. Downloads stay available for archived documents and projects; the web serves them, read in full, through `/projects/{projectId}/documents/{documentId}/download`. `reference` is an issue or pull request number (`42` or `#42`), a commit SHA of 7 to 40 hex digits, a release tag, or the github.com address of any of them, in the project's connected repository (ADR-033, ADR-034, ADR-037). It is read in that order: digits alone are a number, 7 to 40 hex digits are a SHA, and any other text without spaces is a release tag, so a tag that looks like a number or a SHA must be given as its release address. The API reads the item from GitHub before saving. Unknown items and links to another repository are 400 on `reference`. Refresh re-reads issues, pull requests, and releases, the check results of pull requests and commits (ADR-035), and what each release contains; a commit itself is not re-read. `source` in the request is ignored: links made through this endpoint are always `manual` (ADR-036). 409 carries the reason in `detail`: already linked, 50 links reached, no repository connected, the app uninstalled, an archived requirement or project, or the evidence or connected repository changed while GitHub was being read (reload and retry). 502 and 503 mean the same as for repositories. Search (ADR-054) finds issues and pull requests of the connected repository whose titles contain every word of `q` (1 to 200 characters, at most 10 words; quotes are ignored), through GitHub's search API. Each word is searched for as text, so a qualifier such as `repo:` in `q` cannot reach another repository; results from any other repository are dropped. It links nothing: link a result by its number. An empty `q`, or one of more than 10 words, is 400 on `q` (words are never dropped); no repository connected is 409; 502 and 503 as above, including GitHub's search rate limit. Linking and unlinking each add an `EvidenceEvent`, which stays after the link is removed; refresh adds none. Suggestions (ADR-056) are pull requests of the connected repository whose description closes an issue linked to the requirement (close, fix, or resolve in GitHub's forms, before `#N`, `owner/name#N`, or the issue's address). Scan and refresh bring the undecided ones up to date, and answer 409 if the linked issues change while GitHub is read. They are not evidence: no evidence list, count, review, or Evidence complete includes them. Confirm links the pull request as GitHub reports it now; reject keeps it from being suggested again, though it can still be linked by hand. Either adds an `EvidenceEvent`. A suggestion decided already, or a pull request gone from GitHub, is 409, as are no repository connected and an archived requirement or project; 502 and 503 as above. Linking a suggested pull request by hand removes its suggestion. Move takes a link to another active requirement of the project in one step. The link keeps its ID, `linkedBy` and `linkedAt` become the mover and now, and `source` becomes `manual`. Each requirement gets an `EvidenceEvent`, and decisions on both become `outdated`. A target that is missing, the same requirement, or in another project is 400 on `targetRequirementId`. An archived target, the item already linked there, 50 links there, no repository connected, or the link or the target's links changing during the move is 409. A pull request moved away is not suggested again for that requirement; a decision already made on it stays as it was. Link and refresh read GitHub first and only then take the team lock and save, so a large refresh may take tens of seconds; the web app allows these two calls 55 seconds (ADR-048). Every evidence, review, and repository write serializes with archiving and membership changes in the project's team, like requirement writes. `githubToken` is the signed-in user's own GitHub token for the SpecThread GitHub App (ADR-032). In the web app use `gitHubAccess()` from `@/lib/github-data`; never send the token to the browser. The API uses it for that request only. A token GitHub rejects is 400 on `githubToken`; a repository GitHub does not show that user through that installation is 400 on `repositoryId`; an installation the app can no longer act on is 400 on `installationId`. GitHub being unreachable is 502. Missing or rejected app credentials are 503. Every team member can read every project. Owners, Admins, and Members edit its requirements, documents, and links; Reviewers also record decisions; Observers only read (ADR-058). Only the team Owner/Admin manage projects. `teamId` is required on creation and immutable on rename. Missing/empty IDs return 400 field errors; unknown/inaccessible teams return 404, and a Member, Reviewer, or Observer receives 403. Project membership reads reflect team members. Legacy POST/DELETE membership routes return 410 with `code: "team_membership_required"` after membership checking; outsiders still receive 404. These routes never add or remove a team member. Joins require invitation acceptance. A requirement needs a title and at least one acceptance criterion: an empty or missing `acceptanceCriteria` is 400 on that field, on create and on save. `PUT` replaces the requirement: send the full criteria list in display order, the full `documentIds` list (omitting it unlinks every document), and the `version` you loaded. Criteria get new IDs on every save; a document that stays linked keeps its `linkedBy` and `linkedAt` (ADR-049). `documentIds` holds at most 20 distinct IDs of documents in the requirement's own project. A document can be newly linked only while it is active; one archived after it was linked stays linked. Anything else is 400 on `documentIds`. Every saved change to the ordered, trimmed criteria texts adds a criteria version; creating writes version 1 (ADR-051). When the latest decision accepted the current criteria version, a `PUT` that changes the criteria is 409 with `code: "accepted_criteria_change"` and `acceptedCriteriaVersion`, and changes nothing, unless it sends `confirmCriteriaChange: true`. The decision then stays as it was, and the list reports `review.criteriaChanged`. A requirement has at most one `milestone` label of up to 100 characters (ADR-053); longer is 400 on `milestone`. Setting it through `/milestone` does not change the version or `updatedBy`. `?milestone=` matches the trimmed label exactly. A follow-up link (ADR-052) needs an active requirement of the same project, other than itself and not already following it up; it is 400 on `originalRequirementId` otherwise, and at most 20 per requirement. A link that exists already, or an archived requirement or project, is 409. Links do not change the version. Create and every save set `updatedBy` to the caller and `updatedAt` to now (ADR-050). An archived requirement stays readable but refuses saves, evidence changes, and review decisions with 409 until it is restored. Restoring is not an edit: it keeps the version, `updatedBy`, `updatedAt`, and the recorded decisions. Neither archive nor restore is possible while the project is archived (409). ## Shapes ```ts type Project = { id: string; name: string; ownerUserId: string; createdAt: string; archivedAt: string | null; teamId: string; teamName: string; teamRole: "owner" | "admin" | "member" | "reviewer" | "observer"; requirementCount: number; }; type RequirementSummary = { id: string; projectId: string; title: string; version: number; createdAt: string; updatedAt: string; archivedAt: string | null; // How many evidence links of any kind the requirement has. Only on the list. evidenceCount: number; // The latest decision, or null. Only on the list; a requirement's page reads /reviews. // criteriaChanged: the criteria changed after it, so it needs review (ADR-051). review: { decision: Decision; decidedBy: string; decidedAt: string; outdated: boolean; criteriaChanged: boolean; criteriaVersion: number | null } | null; milestone: string | null; // ADR-053 criteriaVersion: number | null; // the current criteria version; null only for one created during a deploy // Whether the evidence meets the team's Evidence complete rule, and the parts it does not // meet, in this order (ADR-057). evidenceComplete is true exactly when evidenceMissing is empty. evidenceComplete: boolean; evidenceMissing: ("issue" | "merged_pull_request" | "passing_checks" | "release")[]; }; type CriteriaVersion = { number: number; criteria: string[]; createdBy: string; createdAt: string }; type FollowUpLink = { requirementId: string; title: string; archivedAt: string | null; linkedBy: string; linkedAt: string }; type FollowUps = { followUpOf: FollowUpLink[]; // requirements this one follows up, by title followedUpBy: FollowUpLink[]; // requirements that follow this one up, by title // Every link added or removed that touches this requirement, newest first. requirementId is the follow-up. history: { id: string; requirementId: string; requirementTitle: string; originalRequirementId: string; originalTitle: string; action: "added" | "removed"; actor: string; occurredAt: string }[]; }; // A comment, or a reply when parentId is set; replies are one level deep (ADR-059). body is // trimmed, 1 to 5,000 characters, and "" once deleted. Comments never change the requirement. type Comment = { id: string; parentId: string | null; authorId: string; body: string; createdAt: string; editedAt: string | null; deletedAt: string | null; deletedBy: string | null }; type Comments = { comments: Comment[]; // oldest first, deleted ones included // Every comment created, edited, or deleted, newest first; earlier text is not kept. // parentId and authorId describe the comment, actor who made the change. history: { id: string; commentId: string; parentId: string | null; authorId: string; action: "created" | "edited" | "deleted"; actor: string; occurredAt: string }[]; }; type Decision = "accepted" | "rejected" | "more_evidence"; type Review = { id: string; requirementId: string; decision: Decision; note: string; requirementVersion: number; // the version the reviewer saw criteriaVersion: number | null; // the criteria version it was made against; null when not recorded (ADR-051) // The evidence links as they were when the decision was made. label is "#9", a short SHA, or a tag. evidence: { id: string; kind: string; label: string; title: string; state: string | null }[]; decidedBy: string; decidedAt: string; }; type Requirement = Omit & { description: string; createdBy: string; // createdAt and updatedAt come from RequirementSummary updatedBy: string; // who saved the current version; the creator until someone edits it acceptanceCriteria: { id: string; text: string; position: number }[]; // Linked project documents, by title. archivedAt is the document's own archive time. documents: { id: string; title: string; fileName: string; contentType: string; archivedAt: string | null; linkedBy: string; linkedAt: string }[]; }; type Document = { id: string; projectId: string; title: string; fileName: string; contentType: string; sizeBytes: number; uploadedBy: string; uploadedByName: string; uploadedAt: string; archivedAt: string | null; }; type ProjectMember = { userId: string; name: string; email: string; joinedAt: string; isOwner: boolean; role: "owner" | "admin" | "member" | "reviewer" | "observer" }; type AvailableRepository = { installationId: number; repositoryId: number; owner: string; name: string; fullName: string; isPrivate: boolean; }; type ProjectRepository = AvailableRepository & { url: string; connectedBy: string; connectedAt: string }; type EvidenceCommit = { sha: string; message: string; author: string | null; date: string; url: string }; type EvidenceCheck = { name: string; result: "passed" | "failed" | "running" | "skipped" | "cancelled" | "neutral"; url: string | null; // only when the check has a page on github.com completedAt: string | null; kind: "check" | "status"; }; type Evidence = { id: string; requirementId: string; kind: "issue" | "pull_request" | "commit" | "release"; number: number | null; // issues and pull requests state: "open" | "closed" | "merged" | null; // issues and pull requests sha: string | null; // a commit, a pull request's latest commit, or a release's tagged commit tag: string | null; prerelease: boolean | null; // releases // Releases: evidence ID of each compared commit or merged pull request -> whether the release's history includes it. // A linked change with no entry was not compared (an unmerged pull request, or one from another repository). contains: Record | null; title: string; author: string | null; url: string; repository: string; additions: number | null; deletions: number | null; changedFiles: number | null; // pull requests and commits commitCount: number | null; commits: EvidenceCommit[] | null; // pull requests (first 100 commits) // Pull requests (latest commit) and commits. checks is null when GitHub would not let them be read; // checkCount is GitHub's total and may exceed the 100 stored. All three are null for issues. checks: EvidenceCheck[] | null; checkCount: number | null; checksReadAt: string | null; source: "manual" | "suggested"; // linkedBy is the person who added or confirmed the link githubCreatedAt: string; githubUpdatedAt: string; githubClosedAt: string | null; linkedBy: string; linkedAt: string; refreshedAt: string; }; type EvidenceSearchItem = { number: number; kind: "issue" | "pull_request"; title: string; state: "open" | "closed" | "merged"; author: string | null; url: string; linked: boolean; // linked to this requirement when the search ran }; type EvidenceEvent = { id: string; evidenceId: string; // for a rejection, the suggestion's ID action: "added" | "removed" | "confirmed" | "rejected" | "moved_in" | "moved_out"; // The link as it was then: label is "#9", a release tag, or a short SHA. kind: Evidence["kind"]; label: string; title: string; actor: string; occurredAt: string; otherRequirementId: string | null; otherRequirementTitle: string | null; // the other side of a move }; type EvidenceSuggestion = { id: string; number: number; title: string; state: "open" | "closed" | "merged"; author: string | null; url: string; reference: string; // what was found, such as "Closes #184" foundAt: string; }; ``` Review decisions (ADR-038): `note` may have up to 2,000 characters and is required for `rejected` and `more_evidence`. `version` is the requirement version the reviewer was shown; any other current version is refused with 409. The requirement's author may record a decision (ADR-058 replaces ADR-038's author rule); an Observer gets 403 with "Observers can read decisions but not record them.", and an archived requirement or project 409. Decisions are only added: there is no update or delete. A decision is `outdated` when the requirement's version, or the set of its evidence link IDs, differs from what was reviewed; refreshing evidence does not change that. `ownerUserId` on Project is retained historical creator provenance. Use `teamRole` for management controls; project creation does not grant independent ownership. `requirementCount` counts active requirements. Timestamps are ISO 8601 UTC strings. Text is trimmed before saving. ## Errors Errors are problem details (`application/problem+json`) with `title`, `status`, and `detail`. | Status | Meaning | Suggested UI | |---|---|---| | 400 | Validation failed; `errors` maps fields such as `title`, `file`, or `acceptanceCriteria[2]` to messages | Show the messages next to the fields | | 401 | Missing or invalid token | Send the user to sign in | | 403 | Insufficient team role, a decision by the requirement's author, or the account record is missing | Show the `detail` | | 404 | Not found, or not a member | Show a not-found state | | 409 | Archived item, stale `version`, or onboarding required | Reload, or finish onboarding | | 410 | Individual project membership writes retired | Manage membership through the team | Limits: project names and requirement titles 1-200 characters, descriptions up to 10,000, up to 50 acceptance criteria of 1-2,000 characters each, emails up to 254 characters, document titles up to 200 characters, and file names up to 255. An upload body well over 4 MiB returns 413. ## Teams navigation and onboarding (ADR-039/040) | Method | Path | Who | Body | Success | |---|---|---|---|---| | GET | `/teams` | any user | | 200 `Team[]`, only the caller's memberships, by name then ID | | POST | `/teams` | existing account | `{ name, description? }` | 201 `Team`; caller is the sole owner and first member | | GET | `/teams/{teamId}` | team member | | 200 `Team`; missing and inaccessible teams both return 404 | | PATCH | `/teams/{teamId}` | Owner/Admin | `{ name, description? }` | 200 `Team` | | GET | `/teams/{teamId}/members` | team member | | 200 `TeamMember[]`, Owner first, then name and user ID | | PATCH | `/teams/{teamId}/members/{userId}` | Owner | `{ role: "admin" \| "member" \| "reviewer" \| "observer" }` | 200 `TeamMember` | | DELETE | `/teams/{teamId}/members/{userId}` | permitted manager, or that user leaving | | 204 | | POST | `/teams/{teamId}/ownership` | Owner | `{ userId }` existing other member | 200 `Team`; previous Owner is now Admin | | PATCH | `/teams/{teamId}/preferences` | team member | `{ isFavorite?, isExpanded? }` | 200 `Team`; affects only the caller's membership | | GET | `/onboarding` | existing account | | 200 `{ completed: boolean }` | | POST | `/onboarding` | incomplete existing account | `{ name, description? }` | 201 `Team`; saves initial team and completion atomically | ```ts type Team = { id: string; name: string; description: string; ownerUserId: string; createdAt: string; role: "owner" | "admin" | "member" | "reviewer" | "observer"; memberCount: number; isFavorite: boolean; isExpanded: boolean; }; type TeamMember = { userId: string; name: string; email: string; role: "owner" | "admin" | "member" | "reviewer" | "observer"; joinedAt: string; }; ``` Creation saves the team, its owner's membership, and initial onboarding completion when needed in one transaction. The request cannot set ownership or a role. Names use the existing 1-200-character limit; descriptions are optional, trimmed, and up to 10,000 characters. An absent description is stored as an empty string. A token with no account row receives 403 on creation. Validation uses the same 400 field-error format as projects. Timestamps retain the PostgreSQL precision used by the other write endpoints. `role` is relative to the caller. A single `ownerUserId` determines ownership; non-owner membership roles are `admin`, `member`, `reviewer`, or `observer` (ADR-058). Only the Owner changes roles. Admins remove Members, Reviewers, and Observers; only the Owner removes Admins. Any non-owner can leave voluntarily. Nobody removes the Owner or changes their membership role (409); transfer ownership first. Transfer selects any existing other member and makes the previous Owner an Admin. These mutations lock the team row and recheck membership within a transaction, so concurrent removal/promotion/transfer cannot orphan ownership or evade role restrictions. There is no immediate-add endpoint; joining requires invitation acceptance. Team membership grants access to all projects and requirements inside the team. Next.js uses server-only `apiFetch` for all team reads and creation. The browser's same-origin `GET /api/teams` checks the session and proxies the membership list for the sidebar; `PATCH /api/teams/{id}/preferences` checks the session and forwards only personal preference fields. Neither exposes a JWT. The create form uses an authenticated server action. Team routes require a session and real membership, including planned sections. Initial onboarding returns 409 if already completed or if a concurrent first-team request won. Failed validation never completes it. The unique completion key prevents two concurrent initial-team writes from both succeeding. GET completion persists even when the caller no longer has a membership. The proxy redirects incomplete accounts from protected pages to /onboarding, and POST /projects returns 409 with `code: "onboarding_required"` for an incomplete existing account. Anonymous requests remain 401, and an account without a user row remains 403. Project access follows the containing team as described above. Not yet available: a general activity and audit history. The only change histories kept are criteria versions (ADR-051), follow-up link changes (ADR-052), evidence link changes (ADR-054, ADR-056), and comment changes (ADR-059). Team management uses authenticated server actions. Role changes require explicit Save in a row; removal and leave require a named native confirmation dialog. Team settings is one page with name/description, ownership transfer, and Leave team. Member accounts see general settings as read-only. Transfer confirmation names the team and recipient and explains the previous Owner becomes an Admin. Leaving opens Teams and preserves onboarding completion. Menus/headers refresh after changes. The team archive offers Owner/Admin Restore buttons with confirmation naming the project and team. The server action validates project/team scope before calling the existing restore endpoint, which rechecks current permissions. Members can view the archive but have no restore controls. Restoration refreshes the archive and active-project lists. ## Team invitations (ADR-040) | Method | Path | Who | Body | Success | |---|---|---|---|---| | GET | `/teams/{teamId}/invitations` | Owner/Admin | | 200 `Invitation[]`, all statuses, newest first | | POST | `/teams/{teamId}/invitations` | permitted manager | `{ email, role: "admin" \| "member" \| "reviewer" \| "observer" }` | 201 `{ invitation, token, teamName }` | | POST | `/teams/{teamId}/invitations/{invitationId}/resend` | permitted manager | | 200 `{ invitation, token, teamName }`, fresh link | | DELETE | `/teams/{teamId}/invitations/{invitationId}` | permitted manager | | 204, idempotent revocation | | GET | `/invites/{token}` | public | | 200 `InvitationPreview`; invalid/replaced/unknown token 404 | | POST | `/invites/{token}/accept` | verified matching account | | 200 `Team`, joins and completes onboarding atomically | ```ts type InvitationStatus = "pending" | "accepted" | "revoked" | "expired" | "unavailable"; type Invitation = { id: string; teamId: string; email: string; role: "admin" | "member" | "reviewer" | "observer"; inviterName: string; createdAt: string; issuedAt: string; expiresAt: string; status: InvitationStatus; }; type InvitationPreview = { teamId: string; teamName: string; inviterName: string; email: string; role: "admin" | "member" | "reviewer" | "observer"; expiresAt: string; status: InvitationStatus; }; ``` Owners manage invitations for every role; Admins manage Member, Reviewer, and Observer invitations, not Admin ones (ADR-058). Members, Reviewers, and Observers receive 403 on management; inaccessible teams and cross-team invitation IDs return 404. Email is trimmed/lowercased and limited to 254 characters. Existing members and duplicate unresolved invitations receive 409; resend an expired one. Creating an invitation adds no membership. The secret is 32 random bytes, returned as 64 hex characters only when issued; the database stores only its SHA-256 hash. Links expire after seven days. Resend replaces the secret and issuer and renews expiry, immediately invalidating the previous link. Accepted or revoked invitations cannot be resent (409); create a new invitation when needed. Acceptance requires both a verified account with the matching email and the inviter's current permission. An Admin invitation requires its inviter to still be the Owner. Lost permission yields `unavailable`; an authorized manager can resend. Expired, revoked, and permission-invalid acceptance returns 410. Wrong/unverified accounts return 403. All writes lock the same team row as membership/ownership changes. Membership, token consumption, and completion commit together. Simultaneous acceptances in different teams share an idempotent completion UPSERT. Repeated acceptance by the same still-present member succeeds; a consumed link cannot rejoin someone who left or was removed (409). Existing memberships retain their role. The web offers an Invite people dialog from Members, email delivery through the existing sender, and immediate Copy link. Email failure leaves the issued invitation usable and offers copying/resending. The secret is not recoverable from the list; resend issues a fresh link. Management uses a separate table and named revoke confirmation. The acceptance screen is a focused full page. Exact 64-hex preview URLs (and their legacy `/expired` redirect) are public; all other invitation paths retain the deny-by-default gate. Sign-in/signup/verification preserve the invitation destination. A preview alone never completes onboarding or unlocks project creation. Preview responses disable caching, and the page sets `no-referrer`/no indexing. API hosting request-start/finish logs are filtered below Warning because those framework messages include raw token URLs. Production proxy logs must also avoid recording invitation secrets. Project management writes share the team transaction lock with role/removal/transfer changes and construct their response before commit, so concurrent revocation cannot commit a write and then fail its membership read.