docs(openapi): add fork endpoints, forkId params, and spec-currency enforcement

[khaliqgant]

Summary

• OpenAPI spec gaps fixed: three fork endpoints (POST /forks, DELETE /forks/{forkId}, POST /forks/{forkId}/commit) were fully implemented in internal/httpapi/server.go but entirely absent from the spec
• forkId query param documented on all six fork-aware filesystem endpoints: fs/tree, fs/file (GET/PUT/DELETE), fs/bulk, fs/export, fs/query
• depth default corrected: spec said 2, server uses 10 (with max 100, not 10)
• New schemas: ForkHandle, ForkCommitResponse, ForkCommitConflictResponse, Gone (410) response, ForkId component parameter
• Spec-currency enforcement: new .claude/rules/openapi-spec.md and AGENTS.md section instruct agents to keep the spec in sync whenever server.go or the openapi/ directory is touched

Changes

File	What changed
openapi/relayfile-v1.openapi.yaml	Fork paths, forkId params, schema additions, depth fix
.claude/rules/openapi-spec.md	New Claude rule scoped to openapi/** and internal/httpapi/**
AGENTS.md	OpenAPI spec maintenance guidance for all agents

Test plan

• Verify scripts/check-contract-surface.sh passes on this branch
• Confirm the three fork endpoints are reachable and match the documented request/response shapes against internal/httpapi/server.go
• Confirm forkId param flows correctly through fs/tree, fs/file, fs/bulk, fs/export, fs/query
• Confirm depth default of 10 matches parseBoundedInt(r.URL.Query().Get("depth"), 10, 1, 100) in server.go

https://claude.ai/code/session_019EWJdxPwPwifR9ZUWaB1B6

---

Generated by Claude Code

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces fork support to the RelayFile API by adding OpenAPI spec definitions for three new fork endpoints (create, discard, commit) and extending existing filesystem endpoints with an optional forkId parameter. It also establishes contract maintenance rules and documentation to keep the OpenAPI spec synchronized with HTTP server implementation.

Changes

Fork API Specification and Contract Maintenance

Layer / File(s)	Summary
Contract Maintenance Rules .claude/rules/openapi-spec.md, AGENTS.md	Establishes governance for OpenAPI spec synchronization with internal/httpapi/server.go and mandates verification via scripts/check-contract-surface.sh.
Fork Component Definitions openapi/relayfile-v1.openapi.yaml	Defines reusable ForkId query parameter, Gone error response, and Forks operation tag for fork lifecycle endpoints.
Fork Lifecycle Endpoints openapi/relayfile-v1.openapi.yaml	Adds POST /v1/workspaces/{workspaceId}/forks (create), DELETE /v1/workspaces/{workspaceId}/forks/{forkId} (discard), and POST /v1/workspaces/{workspaceId}/forks/{forkId}/commit (commit) with request/response schemas and error handling.
Fork Integration with Filesystem Endpoints openapi/relayfile-v1.openapi.yaml	Adds optional forkId query parameter to tree, bulk write, export, file read/write/delete, and query endpoints to enable fork-scoped operations.

Sequence Diagram(s)

The conditions for generating sequence diagrams are not met for this PR. The changes are primarily OpenAPI specification and documentation updates defining new API contracts, not implementing new control flow or multi-component interactions at the code level.

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Forks and branches, a rabbit's delight,
Isolated workspaces, keeping all right.
Commit when ready, or discard with care,
OpenAPI contracts—a specification so fair! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and specifically describes the main changes: adding fork endpoints, forkId parameters, and spec-currency enforcement mechanisms to the OpenAPI documentation.
Description check	✅ Passed	The description is well-related to the changeset, providing a clear summary of OpenAPI spec gaps fixed, new schemas added, and spec-currency enforcement introduced.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/assess-project-readiness-ROyiF

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 76a90f2fa3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Remove unsupported forkId from export spec

When a caller supplies forkId to GET /fs/export, the server does not read that query parameter; handleExport always calls s.store.ExportWorkspace(workspaceID) and filters the main workspace. Documenting this parameter here will lead clients to believe staged fork writes are included, but exports taken before commit silently return the parent workspace instead.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Mark createFork body and proposalId as required

The server cannot create a fork without a JSON body containing a non-empty proposalId: handleCreateFork always calls decodeJSONBody, and Store.CreateFork returns ErrInvalidInput when proposalID is empty. With requestBody.required: false and no schema required list, generated clients may omit the body or proposalId and get a 400 from an operation the spec advertises as valid.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Document same-proposal replay as 200

The documented 409 for reusing the same proposalId does not match the implementation: Store.CreateFork returns the existing fork handle with nil error when the same workspace/proposal pair already exists, and only raises ErrForkProposalConflict when that proposal is associated with a different workspace. Clients following this response map will handle idempotent retries incorrectly because same-workspace replay returns 200, not 409.

Useful? React with 👍 / 👎.