@gonovus-ai/spec-flow-cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,808 @@
-# Temporary Holding Version
+# SpecFlow CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The next CLI contract is **0.2.0**, coordinated with the official Skill's exact
+pin. Directory, Spec and Product Map results can return `capabilityId: null`;
+unassigned search results have `capabilityPath: []`. Consumers of 0.1.x must
+handle these absent placements before upgrading. Omit `--capability-id` on
+creation, and use `--capability-id none` on `spec update` to clear placement;
+omitting that update option preserves the current placement. Existing grouped
+requests and nested Capability paths retain their meaning. The HTTP service
+continues under `/v1` with regenerated OpenAPI inputs; clients must update their
+nullable response handling together. This source change does not publish either
+artifact or change already released Skill tags.
+
+`@gonovus-ai/spec-flow-cli` uses OAuth Device Authorization to create an independent
+seven-day Better Auth CLI Session. It supports the Node.js 24 runtime line;
+Node.js 22 and unverified future major versions are intentionally unsupported.
+
+```bash
+npm install --global @gonovus-ai/spec-flow-cli@0.2.0
+specflow auth login
+specflow auth status
+specflow auth logout
+```
+
+The published package's default service origin comes from the GitHub repository
+Actions variable `SPEC_FLOW_DEFAULT_API_URL`, embedded at build time. Both authentication
+and resource commands resolve `--server` first, then runtime `SPEC_FLOW_API_URL`, then
+that packaged default. Keep the same origin for login and subsequent commands.
+Credentials are isolated by origin; a different environment requires its own login.
+
+Changing the repository variable requires publishing a new CLI version; existing
+installations keep their packaged default. The release workflow rejects a missing,
+empty or invalid origin. Skill instructions do not need a deployment address.
+
+Local builds without `SPEC_FLOW_DEFAULT_API_URL` have no implicit service target;
+pass `--server` or set runtime `SPEC_FLOW_API_URL`. To build a local package with a
+default, provide `SPEC_FLOW_DEFAULT_API_URL` to the CLI build command. The packed
+installation smoke uses an isolated `.invalid` test origin when no build value is
+provided; it never substitutes a deployment URL into source.
+
+After login, resource commands reuse the stored CLI Session and emit structured JSON
+on stdout. Existing-Project commands always require an explicit `--project-id`:
+
+```bash
+SPEC_FLOW_API_URL=https://specflow.example specflow workspace list
+SPEC_FLOW_API_URL=https://specflow.example specflow workspace create --name "Core Platform"
+SPEC_FLOW_API_URL=https://specflow.example specflow project list
+SPEC_FLOW_API_URL=https://specflow.example specflow project list --workspace-id <workspace-id>
+SPEC_FLOW_API_URL=https://specflow.example specflow project list --status Archived
+SPEC_FLOW_API_URL=https://specflow.example specflow project list --status Trashed
+SPEC_FLOW_API_URL=https://specflow.example specflow project create --name "Payments" --project-id PAY --workspace-id <workspace-id>
+SPEC_FLOW_API_URL=https://specflow.example specflow project create --name "Payments" --project-id PAY --workspace-id <workspace-id> --spec-language zh-CN
+SPEC_FLOW_API_URL=https://specflow.example specflow project archive --project-id <project-id> --expected-version '"1"'
+SPEC_FLOW_API_URL=https://specflow.example specflow project restore --project-id <project-id> --expected-version '"2"'
+SPEC_FLOW_API_URL=https://specflow.example specflow project trash --project-id <project-id> --expected-version '"2"'
+SPEC_FLOW_API_URL=https://specflow.example specflow project directory --project-id <project-id>
+SPEC_FLOW_API_URL=https://specflow.example specflow spec read --project-id <project-id> --spec-id <spec-id>
+SPEC_FLOW_API_URL=https://specflow.example specflow spec current --project-id <project-id> --spec-id <spec-id>
+SPEC_FLOW_API_URL=https://specflow.example specflow spec revision --project-id <project-id> --spec-id <spec-id> --revision-id <revision-id>
+SPEC_FLOW_API_URL=https://specflow.example specflow spec changelog --project-id <project-id> --spec-id <spec-id>
+SPEC_FLOW_API_URL=https://specflow.example specflow spec edit --project-id <project-id> --spec-id <spec-id> --content "$(cat payments.md)"
+SPEC_FLOW_API_URL=https://specflow.example specflow spec assign-scenario-ids --project-id <project-id> --spec-id <spec-id>
+SPEC_FLOW_API_URL=https://specflow.example specflow spec publish --project-id <project-id> --spec-id <spec-id>
+SPEC_FLOW_API_URL=https://specflow.example specflow glossary edit --project-id <project-id> --entries '[{"id":"payment","canonicalTerm":"Payment","definition":"A completed transfer.","usageNote":null}]'
+SPEC_FLOW_API_URL=https://specflow.example specflow proposal create-spec --project-id <project-id> --spec-id <spec-id> --baseline-content "$(cat payments.md)" --proposed-content "$(cat payments.md)" --agent-revision <revision> --agent-model <model> --source-reference-ids '["source-id"]'
+SPEC_FLOW_API_URL=https://specflow.example specflow proposal list --project-id <project-id> --target-kind Spec --spec-id <spec-id> --status Open
+SPEC_FLOW_API_URL=https://specflow.example specflow proposal apply --project-id <project-id> --proposal-id <proposal-id> --change-ids '["hunk-1"]'
+SPEC_FLOW_API_URL=https://specflow.example specflow proposal discard --project-id <project-id> --proposal-id <proposal-id>
+SPEC_FLOW_API_URL=https://specflow.example specflow authoring-history --project-id <project-id>
+```
+
+Every official CLI service request sends the versioned `@gonovus-ai/spec-flow-cli/<version>`
+User-Agent. Diagnostics use stderr, and stable Skill Errors use documented reason and
+exit-status categories.
+
+## Optional Task resource links
+
+Use `work-item resource-link list --project-id PAY --work-item-id PAY-7` to read
+current authorized references. Add a stable Spec with `add --kind spec --spec-id
+PAY-8`; `--spec-project-id` selects another accessible Project in the same Workspace
+and otherwise defaults to the Task Project. Add a document or other locator with
+`add --kind document|other --title <name> --url <http-or-https-url>`. Every add requires
+`--idempotency-key <uuid>` and the owning Project/Task flags. Retain that key for an
+ambiguous retry of the same input.
+
+Unlink with `remove --link-id <uuid> --expected-version <opaque-version>
+--idempotency-key <uuid>` and the Project/Task flags. The target and Task remain
+independent. `spec work-items --project-id <Spec-project> --spec-id <id> [--limit <n>]
+[--cursor <opaque-cursor>]` reads paged authorized reverse Task references.
+These commands read current metadata without pinning a Revision, importing content,
+or changing Task completion or Spec publication. External locator names are
+user-authored Task data; opening a destination uses that destination's authorization.
+
+## Machine contract
+
+Resource-command success writes exactly one newline-terminated JSON object to stdout.
+stderr is newline-delimited JSON (NDJSON): zero or more diagnostics use
+`{ "diagnostic": { "level": "warning", "message": string } }`. These
+command/result pairs are the supported schemas:
+
+| Command                                                                                                 | Success object                                                                                                        |
+| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `workspace list`                                                                                        | `{ workspaces: WorkspaceSummary[] }`                                                                                  |
+| `workspace create`                                                                                      | `{ workspace: WorkspaceSummary }`                                                                                     |
+| `workspace member list --workspace-id <id>`                                                             | `{ members: WorkspaceMember[] }`                                                                                      |
+| `workspace member search --workspace-id <id> --query <q>`                                               | `{ candidates: WorkspaceDirectoryCandidate[] }`                                                                       |
+| `workspace member add --workspace-id <id> --user-id <userId> --role <role>`                             | `{ member: WorkspaceMember }`                                                                                         |
+| `workspace member set-role --workspace-id <id> --user-id <userId> --role <role> --expected-version <v>` | `{ member: WorkspaceMember }`                                                                                         |
+| `workspace member remove --workspace-id <id> --user-id <userId> --expected-version <v>`                 | `{ removed: { userId: string } }`                                                                                     |
+| `workspace role list --workspace-id <id>`                                                               | `{ roles: WorkspaceRole[] }`                                                                                          |
+| `workspace role create --workspace-id <id> --name <name> --statements <json>`                           | `{ role: WorkspaceRole }`                                                                                             |
+| `workspace role update --workspace-id <id> --name <name> --statements <json> --expected-version <v>`    | `{ role: WorkspaceRole }`                                                                                             |
+| `workspace role delete --workspace-id <id> --name <name> --expected-version <v>`                        | `{ deleted: { name: string } }`                                                                                       |
+| `project list [--status Active\|Archived\|Trashed] [--workspace-id <workspace-id>]`                     | `{ projects: ProjectSummary[] }`                                                                                      |
+| `project create`                                                                                        | `{ project: ProjectSummary }`                                                                                         |
+| `project archive`                                                                                       | `{ project: ProjectSummary }`                                                                                         |
+| `project restore`                                                                                       | `{ project: ProjectSummary }`                                                                                         |
+| `project trash`                                                                                         | `{ project: ProjectSummary }`                                                                                         |
+| `project context`                                                                                       | `{ project: ProjectContext, publishedGlossary: PublishedGlossary \| null }`                                           |
+| `project directory`                                                                                     | `{ capabilities: Capability[], permissions: Permissions, specs: SpecSummary[] }`                                      |
+| `spec search`                                                                                           | `{ nextCursor: string \| null, results: SearchResult[], totalCount: number }`                                         |
+| `work-item resource-link list`                                                                          | `{ links: WorkItemResourceLink[], canCreateLink: boolean, canReadSpecs: boolean }`                                    |
+| `work-item resource-link add`                                                                           | `{ linkId: string, link: WorkItemResourceLink \| null, replayed: boolean }`                                           |
+| `work-item resource-link remove`                                                                        | `{ deleted: true, replayed: boolean }`                                                                                |
+| `spec work-items`                                                                                       | `{ workItems: SpecWorkItemReference[], nextCursor: string \| null, canReadWorkItems: boolean }`                       |
+| `spec read`                                                                                             | `{ currentRevision: SpecRevision \| null, permissions: Permissions, spec: SpecDetails }`                              |
+| `spec current`                                                                                          | `{ revision: SpecRevision, spec: SpecSummary }`                                                                       |
+| `spec revision`                                                                                         | `{ revision: SpecRevision }`                                                                                          |
+| `spec changelog`                                                                                        | `{ entries: SpecChangelogEntry[] }`                                                                                   |
+| `spec create`                                                                                           | `{ spec: SpecDetails }`                                                                                               |
+| `spec update`                                                                                           | `{ spec: SpecDetails }`                                                                                               |
+| `spec draft`                                                                                            | `{ spec: SpecDetails }`                                                                                               |
+| `spec edit`                                                                                             | `{ draft: { draftSessionId: string, content: string, specId: string } }`                                              |
+| `spec assign-scenario-ids`                                                                              | `{ assignedScenarioIds: string[], draft: { draftSessionId: string, content: string, specId: string } }`               |
+| `spec publish`                                                                                          | `{ revision: SpecRevision, spec: SpecSummary }`                                                                       |
+| `spec state`                                                                                            | `{ spec: SpecSummary }`                                                                                               |
+| `spec rollback`                                                                                         | `{ revision: SpecRevision, spec: SpecSummary }`                                                                       |
+| `spec delete`                                                                                           | `{ deleted: { specId: string } }`                                                                                     |
+| `glossary read`                                                                                         | `{ currentRevision: GlossaryRevision \| null, draftSession: GlossaryDraftSession \| null, permissions: Permissions }` |
+| `glossary changelog`                                                                                    | `{ entries: GlossaryChangelogEntry[] }`                                                                               |
+| `glossary revision`                                                                                     | `{ revision: GlossaryRevision }`                                                                                      |
+| `glossary draft`                                                                                        | `{ glossary: GlossaryDetails }`                                                                                       |
+| `glossary edit`                                                                                         | `{ draft: { draftSessionId: string, entries: GlossaryEntry[] } }`                                                     |
+| `glossary publish`                                                                                      | `{ revision: GlossaryRevision }`                                                                                      |
+| `glossary rollback`                                                                                     | `{ revision: GlossaryRevision }`                                                                                      |
+| `proposal create-spec\|create-glossary`                                                                 | `{ proposal: DraftProposal }`                                                                                         |
+| `proposal list`                                                                                         | `{ proposals: DraftProposal[] }`                                                                                      |
+| `proposal apply`                                                                                        | `{ mergeOutcome: "Applied", proposal: DraftProposal }`                                                                |
+| `proposal discard`                                                                                      | `{ proposal: DraftProposal }`                                                                                         |
+| `authoring-history`                                                                                     | `{ operations: AuthoringOperation[] }`                                                                                |
+| `capability create`                                                                                     | `{ capability: Capability }`                                                                                          |
+| `capability update`                                                                                     | `{ capability: Capability }`                                                                                          |
+| `capability delete`                                                                                     | `{ deleted: { capabilityId: string } }`                                                                               |
+| `token issue`                                                                                           | `{ credential: string, token: ProjectReadToken }`                                                                     |
+| `token list`                                                                                            | `{ tokens: ProjectReadToken[] }`                                                                                      |
+| `token revoke`                                                                                          | `{ revoked: { tokenId: string } }`                                                                                    |
+| `review request`                                                                                        | `{ review: ManualReviewRecord }`                                                                                      |
+| `review read`                                                                                           | `{ review: ManualReviewRecord }`                                                                                      |
+| `finding list`                                                                                          | `{ findings: ReviewFinding[], nextCursor: string \| null, permissions: FindingPermissions }`                          |
+| `finding read`                                                                                          | `{ finding: ReviewFinding, permissions: FindingPermissions }`                                                         |
+| `finding create`                                                                                        | `{ finding: ReviewFinding, permissions: FindingPermissions }`                                                         |
+| `finding confirm\|dismiss\|resolve`                                                                     | `{ finding: ReviewFinding, permissions: FindingPermissions }`                                                         |
+
+The named JSON shapes are:
+
+```ts
+type WorkItemResourceLink = {
+  id: string;
+  version: string; // opaque ETag
+  createdAt: string;
+  target:
+    | {
+        kind: "spec";
+        projectId: string;
+        specId: string;
+        title: string;
+        state: "Draft" | "Ready" | "Unavailable";
+        unavailabilityReason: string | null;
+      }
+    | { kind: "document" | "other"; title: string; url: string };
+};
+type SpecWorkItemReference = {
+  linkId: string;
+  projectId: string;
+  workItemId: string;
+  title: string;
+  status: string;
+};
+type WorkspaceSummary = {
+  capabilities: {
+    canReadMembers: boolean;
+    canReadRoles: boolean;
+  };
+  id: string;
+  name: string;
+  role: string;
+};
+type WorkspaceMember = {
+  accessStatus: "Enabled" | "Disabled";
+  email: string | null;
+  image: string | null;
+  name: string;
+  role: string;
+  userId: string;
+  version: string; // opaque ETag
+};
+type WorkspaceDirectoryCandidate = {
+  eligible: boolean;
+  ineligibleReason: string | null;
+  issuer: string;
+  name: string;
+  subject: string;
+  userId: string | null;
+};
+type WorkspaceRole = {
+  name: string;
+  statements: Record<string, string[]>;
+  version: string; // opaque ETag
+};
+type ProjectSummary = {
+  effectiveCapabilities: {
+    canAdministerGitHubConnection: boolean;
+    canAdministerProject: boolean;
+    canEditProject: boolean;
+    canReadProject: boolean;
+  };
+  specLanguage: string;
+  id: string;
+  name: string;
+  role: string;
+  status: "Active" | "Archived" | "Trashed";
+  version: string; // opaque ETag
+  workspaceId: string;
+  workspaceName: string;
+};
+type ProjectContext = {
+  specLanguage: string;
+  id: string;
+  name: string;
+  status: "Active" | "Archived";
+  version: string; // opaque ETag
+};
+type GlossaryEntry = {
+  canonicalTerm: string;
+  definition: string;
+  id: string;
+  usageNote: string | null;
+};
+type PublishedGlossary = {
+  entries: GlossaryEntry[];
+  id: string;
+  publishedAt: string; // ISO 8601 date-time
+};
+type Capability = {
+  id: string;
+  name: string;
+  parentId: string | null;
+  version: string; // opaque ETag, for example: "\"1\""
+};
+type Permissions = { canEdit: boolean };
+type FindingPermissions = { canWrite: boolean };
+type SourceReference = {
+  externalRevision?: string;
+  id: string;
+  section?: string;
+  title: string;
+  url: string;
+};
+type SpecSummary = {
+  capabilityId: string;
+  featureName: string;
+  id: string;
+  sourceReferences: SourceReference[];
+  state: "Draft" | "Ready" | "Unavailable";
+  unavailabilityReason: string | null;
+  version: string; // opaque ETag
+};
+type SpecDetails = SpecSummary & {
+  draftSession: {
+    documentName: string;
+    id: string;
+    rootName: "spec-outline";
+  } | null;
+};
+type SpecRevision = {
+  content: string;
+  id: string;
+  publishedAt: string; // ISO 8601 date-time
+};
+type CapabilityPathEntry = { id: string; name: string };
+type SearchResult = {
+  capabilityPath: CapabilityPathEntry[];
+  spec: SpecSummary;
+};
+type SourceReferenceInput = Omit<SourceReference, "id">;
+type SpecChangelogEntry = {
+  acceptedAt: string; // ISO 8601 date-time
+  action:
+    | "Published"
+    | "RolledBack"
+    | "StateChanged"
+    | "MetadataChanged"
+    | "FindingCreated"
+    | "FindingConfirmed"
+    | "FindingDismissed"
+    | "FindingResolved"
+    | "FindingStale";
+  actorSessionId: string;
+  actorUserId: string;
+  changes: {
+    content: { from: string | null; to: string } | null;
+    finding: {
+      findingId: string;
+      status: "Confirmed" | "Dismissed" | "Proposed" | "Resolved" | "Stale";
+    } | null;
+    metadata: {
+      capabilityId?: { from: string; to: string };
+      sourceReferences?: {
+        from: SourceReferenceInput[];
+        to: SourceReferenceInput[];
+      };
+    } | null;
+    state: {
+      from: "Draft" | "Ready" | "Unavailable";
+      fromUnavailabilityReason: string | null;
+      to: "Draft" | "Ready" | "Unavailable";
+      toUnavailabilityReason: string | null;
+    } | null;
+  };
+  id: string;
+  previousRevisionId: string | null;
+  revisionId: string | null;
+};
+type GlossaryRevision = {
+  entries: GlossaryEntry[];
+  id: string;
+  publishedAt: string; // ISO 8601 date-time
+};
+type GlossaryDraftSession = {
+  documentName: string;
+  entriesName: "entries";
+  id: string;
+};
+type GlossaryDetails = {
+  currentRevision: GlossaryRevision | null;
+  draftSession: GlossaryDraftSession;
+};
+type GlossaryChangelogEntry = {
+  acceptedAt: string; // ISO 8601 date-time
+  action: "Published" | "RolledBack";
+  actorSessionId: string;
+  actorUserId: string;
+  changes: {
+    added: GlossaryEntry[];
+    removed: GlossaryEntry[];
+    updated: { from: GlossaryEntry; to: GlossaryEntry }[];
+  };
+  id: string;
+  previousRevisionId: string | null;
+  revisionId: string;
+};
+type ProjectReadToken = {
+  createdAt: string; // ISO 8601 date-time
+  expiresAt: string | null; // ISO 8601 date-time
+  id: string;
+  issuer: { id: string; name: string };
+  lastUsedAt: string | null; // ISO 8601 date-time
+  name: string;
+  revokedAt: string | null; // ISO 8601 date-time
+};
+type FindingType =
+  | "Contradiction"
+  | "Conflict"
+  | "Duplicate"
+  | "Ambiguity"
+  | "Terminology"
+  | "Unverifiable";
+type ManualReviewRecord = {
+  agentRevision: string;
+  completedAt: string | null; // ISO 8601 date-time
+  createdAt: string; // ISO 8601 date-time
+  draft: { contentHash: string; draftSessionId: string; specId: string };
+  enabledFindingTypes: FindingType[];
+  failureCategory:
+    | "InvalidOutput"
+    | "ProjectInactive"
+    | "TerminalExecutionFailure"
+    | "Timeout"
+    | null;
+  findingIds: string[];
+  glossaryRevisionId: string | null;
+  id: string;
+  knownFindingIds: string[];
+  mastraExecutionVersion: string;
+  model: string | null;
+  projectId: string;
+  requestedBy: { sessionId: string; userId: string };
+  reviewContractVersion: string;
+  startedAt: string | null; // ISO 8601 date-time
+  status:
+    | "Queued"
+    | "Running"
+    | "ProposedFindings"
+    | "Superseded"
+    | "Cancelled"
+    | "Failed";
+  trigger: "ManualDraft";
+  updatedAt: string; // ISO 8601 date-time
+};
+type FindingReference = {
+  kind: "Feature" | "Rule" | "Background" | "Scenario" | "Examples" | "Step";
+  text: string;
+};
+type FindingTarget = {
+  binding:
+    | { kind: "Revision"; revisionId: string }
+    | {
+        contentHash: string;
+        draftSessionId: string;
+        kind: "WorkingDraftSnapshot";
+      };
+  references: FindingReference[];
+  specId: string;
+};
+type FindingEvidence =
+  | { incompatibleClaims: [string, string]; kind: "Contradiction" }
+  | { incompatibleRequirements: [string, string]; kind: "Conflict" }
+  | { duplicatedBehavior: string; kind: "Duplicate" }
+  | {
+      interpretations: [
+        { behavior: string; meaning: string },
+        { behavior: string; meaning: string },
+      ];
+      kind: "Ambiguity";
+    }
+  | {
+      glossaryEntryIds: string[];
+      issue: "MissingDefinition" | "GlossaryConflict" | "MultipleMeanings";
+      kind: "Terminology";
+      term: string;
+    }
+  | { kind: "Unverifiable"; missingCriterion: string };
+type ReviewFinding = {
+  affectedScenarios: string[];
+  author: { sessionId: string; userId: string };
+  conclusion: string;
+  createdAt: string; // ISO 8601 date-time
+  evidence: FindingEvidence;
+  explanation: string;
+  glossaryReferences: {
+    entry: GlossaryEntry;
+    entryId: string;
+    revisionId: string;
+  }[];
+  id: string;
+  projectId: string;
+  reviewRecordId: string | null;
+  status: "Proposed" | "Confirmed" | "Dismissed" | "Resolved" | "Stale";
+  targets: FindingTarget[];
+  type: FindingType;
+  updatedAt: string; // ISO 8601 date-time
+  version: string; // opaque ETag
+};
+```
+
+A failed resource command writes nothing to stdout. After any diagnostic lines, the
+final stderr line is exactly `{ "error": { "message": string, "reason":
+SkillErrorReason, "retryAfter"?: string, "retryable": boolean,
+"diagnostics"?: SkillErrorDiagnostic[] } }` where
+`type SkillErrorDiagnostic = { column?: number; line?: number; message: string;
+reason: string }`. `diagnostics` is present whenever the server reports
+positioned source problems: Spec Publish and Rollback rejections from the Spec Content
+Publish Gate carry one entry per `feature-count`, `language-mismatch`,
+`parse-error`, `scenario-required`, or `scenario-id-*` reason,
+`spec assign-scenario-ids` carries the same shape when the Working Draft source is
+invalid, and other Invalid Operation rejections may carry it too. `SkillErrorReason` is `Authentication Failed`,
+`Project Not Accessible`, `Permission Denied`, `Resource Not Found`,
+`Resource Changed`, `Invalid Operation`, or `Temporary Failure`. Exit status `2`
+covers authentication, validation, inaccessible/not-found resources, conflicts, and
+invalid operations; `3` is permission denial; `4` is a `Temporary Failure`, whose
+`retryable` field determines whether automatic retry is safe. Exit status `0` is
+success. Exit status `1` is reserved for startup/runtime failure before a
+resource-command contract can run.
+
+HTTP `429` is a retryable `Temporary Failure`. When the server supplies
+`Retry-After`, the CLI copies its exact value to `retryAfter` and does not retry the
+request automatically. Generated `--help` is a separate controlled success path:
+top-level help includes authentication and every resource group, nested help includes
+the selected group's operations and options, and all help writes to stdout, exits
+zero, and does not resolve credentials or call the service.
+
+`ProjectSummary.effectiveCapabilities` incorporates lifecycle status. Archived
+Projects always report `canEditProject: false`, including for Admins and Editors; an
+Archived Admin still reports `canAdministerProject: true` for Restore and access
+reduction. A Trashed Project reports `canReadProject: false` even for its Admin:
+it appears only in the explicit `--status Trashed` list, and every read or write
+path rejects it; its only accepted mutation is `project restore`, which lands it
+on Archived, so reaching Active again takes a second explicit restore.
+
+Workspace membership is the only source of Project access. `ProjectSummary.role`
+is the caller's Role in the owning Workspace, and `workspace create` grants the
+creator the `Owner` Workspace Role. `project create` requires the owning
+Workspace's ID and at least the `Editor` Role inside it.
+
+`workspace member` and `workspace role` administer that source. `member search`
+queries the bound identity directory and reports each candidate's eligibility;
+`member add` provisions the selected User — including before first login — and
+`member set-role`/`member remove` require the Membership's opaque `version` as
+`--expected-version`. `role` commands manage the Workspace's statement sets:
+`--statements` takes a JSON object mapping resources to action arrays, a Role
+never grants statements the caller does not hold, `Owner` is immutable, and a
+Role still assigned to a member cannot be deleted. Role updates and deletes
+require the Role's `version` as `--expected-version`.
+
+`project list` stays stateless: pass `--workspace-id <workspace-id>` — from
+`workspace list` or `project create` output — to select one Workspace and list
+only its Projects, combinable with `--status`. The CLI keeps no implicit
+current Workspace. An unknown or inaccessible Workspace returns an empty list
+rather than revealing that it exists, and a CLI Session approved for a Project
+subset only ever returns Projects inside that scope, even when the filter names
+a Workspace that contains no scoped Project.
+
+Every non-idempotent create, Draft-session, Publish, Rollback,
+token issuance, Finding disposition, Manual Review request, and Project lifecycle
+command performs at most one fetch-transport retry. It clones the request and reuses
+the same `Idempotency-Key`; an HTTP response, including a response whose body cannot
+be decoded, is never dispatched again. Archive, Restore, and Trash require the opaque
+Project
+version returned by discovery or context. If neither transport attempt yields a usable
+response, the final `Temporary Failure` has `retryable: false` and directs the caller
+to inspect the resource or Changelog before deciding whether another logical mutation
+is appropriate.
+
+Token issuance returns the plaintext credential only for the first committed
+response. If a same-key retry confirms the token with `credential: null`, the CLI
+exits nonzero, prints no success payload, and directs the caller to list or revoke the
+token before deliberately issuing another.
+
+Source Reference URLs accept only HTTP or HTTPS and must not contain URL userinfo
+(`username` or `password`). Keep external credentials in the Agent's own authorized
+source-reading tool; never embed them in SpecFlow metadata.
+
+The repository-owned official Skill is `skills/specflow/SKILL.md`. It pins this exact
+CLI release, requires explicit User confirmation immediately before Spec or Glossary
+Publish and Rollback, and does not send proof of that confirmation to the CLI or API.
+
+The CLI stores its Session credential in macOS Keychain, Windows Credential
+Manager, or Linux Secret Service. It does not print or persist the credential in
+environment variables. If the system store is unavailable on a POSIX platform,
+local-file storage is used only after `--allow-file-fallback` is explicitly
+selected; the CLI warns and enforces directory mode `0700` and file mode `0600`.
+
+## Work Item creation labels
+
+`specflow work-item create --project-id PAY --title "Retry alert" --label <definitionId>`
+sets existing Workspace labels in the same transaction as creation. Repeat `--label`
+for multiple labels; duplicate IDs are ignored. The response includes
+`workItem.labels`. Missing, foreign-Workspace, copy, or deleting labels reject the
+entire creation with `INVALID_WORK_ITEM_LABEL`.
+
+## Work Item JSON exchange
+
+```bash
+specflow work-item export --project-id PAY --status done > tasks.json
+specflow work-item import --project-id OPS --file tasks.json --idempotency-key release-tasks-1
+```
+
+Export supports the same selection flags as `work-item list` and returns a JSON
+`{ project: { name, slug, description, exportedAt }, tasks: [...] }` document on
+stdout. Each task contains `title`, `description`, `status`, `priority`,
+`startDate`, `dueDate`, `userId`, and `labels: [{ name, color }]`. Dates are ISO
+strings or null. Only readable tasks from the explicit Project are included.
+An export over 1000 tasks or 1 MiB fails; narrow the selection instead of expecting
+a truncated document.
+
+Import accepts a JSON file with a `tasks` array, at most 1000 tasks and 1 MiB.
+File Project metadata is descriptive; `--project-id` always selects the target.
+The server applies ordinary creation and assignment authorization, membership,
+workflow, default Custom Field, and identity rules. Unknown statuses become
+`planned`; unknown priorities become `no-priority`; absent or empty priority
+becomes `low`. Labels are exported but not imported, matching pinned Kaneo;
+nonempty imported labels produce an explicit warning.
+
+Import stdout contains `importedAt`, target `project`, and `results` with
+`total`, `successful`, `failed`, and indexed `tasks`. Each row has `success` and
+`warnings`; successful rows include `workItemId` and opaque `version`, while
+failed rows include an error code. If any row fails, the CLI retains this complete
+receipt on stdout, emits a nonretryable `Invalid Operation` on stderr, and exits
+`2`. Correct and import only failed rows with a new key. Successful rows and
+business refusals commit together; an unexpected database error rolls back the
+whole batch.
+
+Retry the same file with the same `--idempotency-key` after an interrupted request.
+Within the existing 24-hour replay window it returns the original receipt without
+duplicating tasks. A changed task payload with that key conflicts. Read Tokens may
+export their single Project; they cannot import. No CSV or legacy migration format
+is provided.
+
+### Task relations
+
+Relations link two tasks in the same Workspace, including across Projects.
+`subtask` means source parent → target child; `blocks` means source blocker →
+blocked target; `related` is symmetric. Reading either endpoint returns both task
+identities and their current Projects. Self-links and duplicate pairs of the same
+relation type in either direction are rejected; longer cycles are allowed, as in
+the pinned Kaneo contract. These links are separate from Spec/document links.
+
+```bash
+specflow work-item relation list --project-id PAY --work-item-id PAY-7
+specflow work-item relation create --project-id PAY --work-item-id PAY-7 \
+  --target-project-id OPS --target-work-item-id OPS-2 --type blocks \
+  --idempotency-key relation-command-1
+specflow work-item relation delete --project-id OPS --work-item-id OPS-2 \
+  --peer-project-id PAY --relation-id <relation-id> --expected-version '"1"' \
+  --idempotency-key remove-relation-command-1
+```
+
+Keep the same command key and inputs after an interrupted response. Receipts
+contain only the relation identifier; a create replay returns `relation: null`
+when the relation has been deleted or its current endpoints are outside the
+original authority. It never restores a deleted link. After a task transfer,
+reread to obtain the endpoint's new task identity and Project before removing its
+relation. Both endpoints require current task update permission for writes;
+Archived endpoints are read-only. Lists omit inaccessible peers and their counts.
+Project Read Tokens can read only relations wholly inside their single Project
+and cannot create or delete relations.
+
+### Task comments and activity
+
+Read comments oldest first, or read the mixed discussion/activity feed newest
+first. Both commands return an opaque `nextCursor`; pass it back with `--cursor`.
+Pages accept `--limit` from 1 through 100.
+
+```bash
+specflow work-item comment list --project-id PAY --work-item-id PAY-7 --limit 20
+specflow work-item discussion --project-id PAY --work-item-id PAY-7 --limit 20
+specflow work-item comment create --project-id PAY --work-item-id PAY-7 \
+  --content '**Review** the rollout' --idempotency-key <uuid>
+specflow work-item comment update --project-id PAY --work-item-id PAY-7 \
+  --comment-id <comment-uuid> --content 'Updated review' \
+  --expected-version '"1"' --idempotency-key <uuid>
+specflow work-item comment delete --project-id PAY --work-item-id PAY-7 \
+  --comment-id <comment-uuid> --expected-version '"2"' --idempotency-key <uuid>
+```
+
+Comment mutations require a CLI Session, current task update permission, and a
+UUID command key. Only the comment's author may edit or delete it, including
+when another Member is an Admin. Reuse the same command key and inputs after a
+lost response; receipts retain only the comment identifier and resolve its
+current content. A replay after deletion returns `comment: null`.
+
+Take the opaque comment `version` from the read result. An edit or deletion
+against an older version reports `Resource Changed`; reread before deciding
+whether to resubmit. Project Read Tokens may read comments and activity under
+`WorkItemRead`, and cannot mutate comments. Activities are produced by the
+server's actual task operations; there is no activity creation command.
+
+### Task time recording
+
+List entries oldest first with an opaque `nextCursor`, or retrieve one entry:
+
+```bash
+specflow work-item time-entry list --project-id PAY --work-item-id PAY-7 --limit 20
+specflow work-item time-entry get --project-id PAY --work-item-id PAY-7 --entry-id <uuid>
+specflow work-item time-entry create --project-id PAY --work-item-id PAY-7 \
+  --start-time '2026-07-01T10:00:00+08:00' --end-time '2026-07-01T11:00:00+08:00' \
+  --description 'Reviewed rollout' --idempotency-key <uuid>
+specflow work-item time-entry update --project-id PAY --work-item-id PAY-7 \
+  --entry-id <uuid> --start-time '2026-07-01T10:00:00+08:00' \
+  --end-time '2026-07-01T11:30:00+08:00' --expected-version '"1"' --idempotency-key <uuid>
+```
+
+Timestamps require an ISO 8601 offset. Omit `--end-time` on creation to record an
+unfinished entry; on update, omission preserves the existing end time. Omitted
+descriptions are preserved on update. The server computes whole duration seconds;
+unfinished entries have no duration and are excluded from `closedDurationSeconds`.
+The list returns that exact cumulative value as a decimal string plus `runningCount`.
+
+Writes require a CLI Session, current task update permission and a UUID command
+key. Only the author may update an entry, including when another Member is an
+Admin. Reuse the same key and inputs after an interrupted response. Updates require
+the read result's opaque `version`; a conflict requires a deliberate reread.
+Project Read Tokens can list and retrieve entries but cannot write. Archived
+Projects are read-only. There is no time-entry deletion command.
+
+### Personal notifications
+
+Use the existing User Session; a Project Read Token cannot access this inbox.
+
+```bash
+specflow notification list
+specflow notification read --notification-id <uuid> --idempotency-key <uuid>
+specflow notification read-all --idempotency-key <uuid>
+specflow notification clear --idempotency-key <uuid>
+specflow notification preferences get
+specflow notification preferences update --expected-version <version> --preferences '{"taskCommentEnabled":false}' --idempotency-key <uuid>
+specflow notification create --type info --title "Review ready" --message "Evidence attached" --idempotency-key <uuid>
+```
+
+Task or Workspace creation targets use paired `--related-entity-id` and
+`--related-entity-type task|workspace` options; Task identifiers are current public
+IDs such as `PAY-7`. Optional `--event-data` accepts a bounded JSON object. Manual
+creation is for the current User only and returns a null notification when the
+category is muted or the target is inaccessible.
+
+The feed returns the latest 50 currently accessible entries and their unread
+count. A read command returns the fresh target after a transfer. Reuse identical
+inputs and the same UUID key after an ambiguous write outcome, particularly for
+read-all and clear, so a retry cannot alter later arrivals. A CLI Session restricted
+to Projects can read only admitted targets; read-all, clear, and preferences require
+an unrestricted Session. Preference reads return an opaque version; saves require `--expected-version`. A
+stale save returns Resource Changed and requires a deliberate reread and reapply.
+Preferences accept partial assignment/comment/status/due
+booleans and `dueDateReminderMinutes` from 5 to 43200. No command schedules reminders
+or configures external delivery channels.
+
+### Public task sharing
+
+```bash
+specflow project sharing read --project-id PAY
+specflow project sharing set --project-id PAY --public true \
+  --expected-version '"1"' --idempotency-key <uuid>
+specflow project sharing set --project-id PAY --public false \
+  --expected-version '"2"' --idempotency-key <uuid>
+```
+
+Use the sharing read's opaque version, which is independent of the Project's
+lifecycle version. Changes require a CLI Session with current `project:share`
+permission on an Active Project. Reuse the same UUID key, boolean and expected
+version after a lost response; a replay returns its original command result without
+changing current sharing. Read the settings again to obtain the current state. A stale fresh command requires a
+reread and an explicit decision. Project Read Tokens cannot manage sharing.
+
+Public sharing exposes only Task/workflow fields and finalized assets currently
+referenced by Task descriptions. It creates no Workspace membership and grants
+no Spec, Glossary, resource association, comment or private attachment access.
+Archive and Trash close sharing; Restore does not reopen it. The anonymous Web
+entry is `/public/projects/<PROJECT>`.
+
+## User API Keys in the current checkout
+
+Use an authenticated CLI Session to manage the current User’s explicitly scoped
+keys. Creating a key saves its one-time secret directly to the origin-scoped system
+credential store; stdout contains metadata and `credentialStored`, never the secret.
+The warned owner-only file fallback remains opt-in with `--allow-file-fallback`.
+These commands describe the repository implementation; a published npm release
+must be verified separately.
+
+```bash
+specflow --server https://specflow.example api-key create --name "Task automation" --project-ids PAY --scopes '{"workItem":["read","create"]}' --expires-at never --idempotency-key <uuid>
+specflow --server https://specflow.example api-key list --limit 50
+specflow --server https://specflow.example api-key list --cursor <nextCursor>
+specflow --server https://specflow.example --api-key-id <key-id> work-item list --project-id PAY
+specflow --server https://specflow.example api-key revoke --key-id <key-id> --expected-version '"1"' --idempotency-key <uuid>
+```
+
+An expiry can instead be an explicit UTC ISO timestamp. Creation requires explicit
+Project IDs and resource-to-actions scope statements. Spec/Glossary `publish` is a
+separate grant; unknown or ungranted scopes fail closed. Every business request
+checks current User eligibility, membership, Role, explicit key scope and lifecycle.
+Global account/Workspace and credential-management routes require a User Session.
+
+Keep the same creation command ID and intent when recovering an uncertain response.
+A replay cannot redisclose a lost secret; revoke that key before deliberately issuing
+a replacement. Saving failure triggers a versioned compensating revoke; an uncertain
+revoke reports the key ID for operator reconciliation. Revocation removes only the
+selected local key slot after the server confirms success. Session credentials stay
+independent.
+
+`SPEC_FLOW_API_KEY` accepts an explicitly provided key for CI. Do not place raw
+secrets in command arguments or use multiple credential selectors. An absent selected
+key never falls back to the Session. API Keys and Project Read Tokens cannot manage
+credentials.
+
+## Explicit GitHub import in the current checkout
+
+```bash
+specflow github connection status --project-id PAY
+specflow github import status --project-id PAY
+specflow github import run --project-id PAY --expected-version '"1"' --idempotency-key <uuid>
+specflow github import run --project-id PAY --expected-version '"1"' --idempotency-key <new-uuid> --run-id <saved-run-id>
+```
+
+Use the connected repository's observed version. Starting and reading import progress
+require a real User Session with current GitHub connection management permission on
+an Active Project. Each page separately checks the connection's current delegated
+API Key and the Task/label operations it needs. Passing `--api-key-id` cannot grant
+connection management.
+
+The command processes bounded batches until completion, retrying rate limits up to
+five times with the same command identity. Stdout contains the final run identity and
+new/updated/skipped counts. A failed batch leaves committed progress intact; retry a
+lost initial response with the same UUID and identical options. Once a run ID is known,
+resume it explicitly. A completed explicit run returns its saved counts; starting
+without a run ID after completion begins a new import.
+
+Import reads open Issues, copies ordinary labels and non-bot historical comments, and
+associates matching Pull Requests. Historical comments remain read-only. Explicit
+import refreshes existing linked Tasks without applying webhook workflow rules; PR
+association does not move a Task. The Project settings Web surface offers the same
+start/resume capability. Closing it stops future batches; an in-flight batch may still
+commit before the pause takes effect.
+
+Specs may be created without `--capability-id`. They appear in Unassigned and retain
+the same editing and publication contract. To move a Spec to Unassigned, use
+`specflow spec update --project-id <id> --spec-id <id> --capability-id none
+--expected-version <version>`. Capability deletion rejects child Capabilities;
+deleting a leaf moves its Specs to Unassigned and records their placement changes.