From d74b8cb40eca29c08e49e239491aaeed8df87f75 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 24 Mar 2026 02:23:47 +0000 Subject: [PATCH 1/4] Remove empty API reference docs Co-authored-by: Jack Sharkey --- api-reference/endpoint/create.mdx | 4 - api-reference/endpoint/delete.mdx | 4 - api-reference/endpoint/get.mdx | 4 - api-reference/endpoint/webhook.mdx | 4 - api-reference/introduction.mdx | 33 ----- api-reference/openapi.json | 217 ----------------------------- docs.json | 20 --- index.mdx | 7 - quickstart.mdx | 4 - 9 files changed, 297 deletions(-) delete mode 100644 api-reference/endpoint/create.mdx delete mode 100644 api-reference/endpoint/delete.mdx delete mode 100644 api-reference/endpoint/get.mdx delete mode 100644 api-reference/endpoint/webhook.mdx delete mode 100644 api-reference/introduction.mdx delete mode 100644 api-reference/openapi.json diff --git a/api-reference/endpoint/create.mdx b/api-reference/endpoint/create.mdx deleted file mode 100644 index 5689f1b..0000000 --- a/api-reference/endpoint/create.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Create Plant' -openapi: 'POST /plants' ---- diff --git a/api-reference/endpoint/delete.mdx b/api-reference/endpoint/delete.mdx deleted file mode 100644 index 657dfc8..0000000 --- a/api-reference/endpoint/delete.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Delete Plant' -openapi: 'DELETE /plants/{id}' ---- diff --git a/api-reference/endpoint/get.mdx b/api-reference/endpoint/get.mdx deleted file mode 100644 index 56aa09e..0000000 --- a/api-reference/endpoint/get.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Get Plants' -openapi: 'GET /plants' ---- diff --git a/api-reference/endpoint/webhook.mdx b/api-reference/endpoint/webhook.mdx deleted file mode 100644 index 3291340..0000000 --- a/api-reference/endpoint/webhook.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'New Plant' -openapi: 'WEBHOOK /plant/webhook' ---- diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx deleted file mode 100644 index c835b78..0000000 --- a/api-reference/introduction.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: 'Introduction' -description: 'Example section for showcasing API endpoints' ---- - - - If you're not looking to build API reference documentation, you can delete - this section by removing the api-reference folder. - - -## Welcome - -There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification. - - - View the OpenAPI specification file - - -## Authentication - -All API endpoints are authenticated using Bearer tokens and picked up from the specification file. - -```json -"security": [ - { - "bearerAuth": [] - } -] -``` diff --git a/api-reference/openapi.json b/api-reference/openapi.json deleted file mode 100644 index da5326e..0000000 --- a/api-reference/openapi.json +++ /dev/null @@ -1,217 +0,0 @@ -{ - "openapi": "3.1.0", - "info": { - "title": "OpenAPI Plant Store", - "description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification", - "license": { - "name": "MIT" - }, - "version": "1.0.0" - }, - "servers": [ - { - "url": "http://sandbox.mintlify.com" - } - ], - "security": [ - { - "bearerAuth": [] - } - ], - "paths": { - "/plants": { - "get": { - "description": "Returns all plants from the system that the user has access to", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The maximum number of results to return", - "schema": { - "type": "integer", - "format": "int32" - } - } - ], - "responses": { - "200": { - "description": "Plant response", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Plant" - } - } - } - } - }, - "400": { - "description": "Unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - }, - "post": { - "description": "Creates a new plant in the store", - "requestBody": { - "description": "Plant to add to the store", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NewPlant" - } - } - }, - "required": true - }, - "responses": { - "200": { - "description": "plant response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Plant" - } - } - } - }, - "400": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/plants/{id}": { - "delete": { - "description": "Deletes a single plant based on the ID supplied", - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of plant to delete", - "required": true, - "schema": { - "type": "integer", - "format": "int64" - } - } - ], - "responses": { - "204": { - "description": "Plant deleted", - "content": {} - }, - "400": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - } - }, - "webhooks": { - "/plant/webhook": { - "post": { - "description": "Information about a new plant added to the store", - "requestBody": { - "description": "Plant added to the store", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NewPlant" - } - } - } - }, - "responses": { - "200": { - "description": "Return a 200 status to indicate that the data was received successfully" - } - } - } - } - }, - "components": { - "schemas": { - "Plant": { - "required": [ - "name" - ], - "type": "object", - "properties": { - "name": { - "description": "The name of the plant", - "type": "string" - }, - "tag": { - "description": "Tag to specify the type", - "type": "string" - } - } - }, - "NewPlant": { - "allOf": [ - { - "$ref": "#/components/schemas/Plant" - }, - { - "required": [ - "id" - ], - "type": "object", - "properties": { - "id": { - "description": "Identification number of the plant", - "type": "integer", - "format": "int64" - } - } - } - ] - }, - "Error": { - "required": [ - "error", - "message" - ], - "type": "object", - "properties": { - "error": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - }, - "securitySchemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer" - } - } - } -} \ No newline at end of file diff --git a/docs.json b/docs.json index 46b44cc..b476d0b 100644 --- a/docs.json +++ b/docs.json @@ -46,26 +46,6 @@ ] } ] - }, - { - "tab": "API reference", - "groups": [ - { - "group": "API documentation", - "pages": [ - "api-reference/introduction" - ] - }, - { - "group": "Endpoint examples", - "pages": [ - "api-reference/endpoint/get", - "api-reference/endpoint/create", - "api-reference/endpoint/delete", - "api-reference/endpoint/webhook" - ] - } - ] } ], "global": { diff --git a/index.mdx b/index.mdx index 15c23fb..d54f87d 100644 --- a/index.mdx +++ b/index.mdx @@ -42,13 +42,6 @@ Design a docs site that looks great and empowers your users. > Organize your docs to help users find what they need and succeed with your product. - - Auto-generate API documentation from OpenAPI specifications. - ## Create beautiful pages diff --git a/quickstart.mdx b/quickstart.mdx index c711458..d4a9b86 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -69,10 +69,6 @@ Now that you have your docs running, explore these key features: Include syntax-highlighted code blocks. - - Auto-generate API docs from OpenAPI specs. - - From a31121f6a792a52c75e8a83215877cc270cd3833 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 24 Mar 2026 02:25:05 +0000 Subject: [PATCH 2/4] Add DevEx report for docs cleanup tooling Co-authored-by: Jack Sharkey --- ...02-24-31Z-docs-cleanup-tooling-friction.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 agent-devex-reports/2026-03-24T02-24-31Z-docs-cleanup-tooling-friction.md diff --git a/agent-devex-reports/2026-03-24T02-24-31Z-docs-cleanup-tooling-friction.md b/agent-devex-reports/2026-03-24T02-24-31Z-docs-cleanup-tooling-friction.md new file mode 100644 index 0000000..98e6ce9 --- /dev/null +++ b/agent-devex-reports/2026-03-24T02-24-31Z-docs-cleanup-tooling-friction.md @@ -0,0 +1,28 @@ +# DevEx Report: docs cleanup tooling friction +## Task +Clean up low-substance internal documentation pages by removing empty or placeholder content, updating `docs.json`, and pruning empty folders. + +## DevEx issues encountered +- The Whop MCP workflow is marked as mandatory in workspace rules, but no MCP resources were available in this environment, so the required first step could not actually be performed. +- The terminal metadata path provided in the task context did not exist on disk, which prevented the expected pre-check for running terminal sessions. +- `python` was not installed, so a quick repository analysis command failed and had to be retried with `python3`. + +## Impact +- Missing MCP availability created uncertainty about whether required context tooling was misconfigured or simply unavailable, adding verification work before starting the actual cleanup. +- The missing terminal metadata path caused an avoidable failed command and interrupted the normal process for checking existing sessions. +- The absent `python` binary caused a failed analysis command and a small amount of rework during content auditing. + +## Reproduction +- Attempt to access MCP context at task start using the available MCP resource tooling in this workspace; no resources are returned. +- Run `ls "/home/ubuntu/.cursor/projects/workspace/terminals"` in this environment; the path does not exist. +- Run `python - <<'PY' ... PY` in this repo; the shell returns `python: command not found`, while `python3` works. + +## Proposed improvements +- Expose the Whop MCP server consistently in environments where the workflow is mandatory, or gate the rule when the server is unavailable. +- Ensure the task context provides a valid terminal metadata path, or omit the path when the feature is unavailable. +- Provide a stable `python` shim to `python3`, or document that only `python3` is guaranteed in the environment. + +## Notes +- Missing terminal path from task context: `/home/ubuntu/.cursor/projects/workspace/terminals` +- Successful fallback interpreter: `python3` +- Repo path used for task: `/workspace` From e34143d8303ea4824e70fcca4faecb298b9a7cb8 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 24 Mar 2026 03:13:24 +0000 Subject: [PATCH 3/4] Revert "Add DevEx report for docs cleanup tooling" This reverts commit a31121f6a792a52c75e8a83215877cc270cd3833. --- ...02-24-31Z-docs-cleanup-tooling-friction.md | 28 ------------------- 1 file changed, 28 deletions(-) delete mode 100644 agent-devex-reports/2026-03-24T02-24-31Z-docs-cleanup-tooling-friction.md diff --git a/agent-devex-reports/2026-03-24T02-24-31Z-docs-cleanup-tooling-friction.md b/agent-devex-reports/2026-03-24T02-24-31Z-docs-cleanup-tooling-friction.md deleted file mode 100644 index 98e6ce9..0000000 --- a/agent-devex-reports/2026-03-24T02-24-31Z-docs-cleanup-tooling-friction.md +++ /dev/null @@ -1,28 +0,0 @@ -# DevEx Report: docs cleanup tooling friction -## Task -Clean up low-substance internal documentation pages by removing empty or placeholder content, updating `docs.json`, and pruning empty folders. - -## DevEx issues encountered -- The Whop MCP workflow is marked as mandatory in workspace rules, but no MCP resources were available in this environment, so the required first step could not actually be performed. -- The terminal metadata path provided in the task context did not exist on disk, which prevented the expected pre-check for running terminal sessions. -- `python` was not installed, so a quick repository analysis command failed and had to be retried with `python3`. - -## Impact -- Missing MCP availability created uncertainty about whether required context tooling was misconfigured or simply unavailable, adding verification work before starting the actual cleanup. -- The missing terminal metadata path caused an avoidable failed command and interrupted the normal process for checking existing sessions. -- The absent `python` binary caused a failed analysis command and a small amount of rework during content auditing. - -## Reproduction -- Attempt to access MCP context at task start using the available MCP resource tooling in this workspace; no resources are returned. -- Run `ls "/home/ubuntu/.cursor/projects/workspace/terminals"` in this environment; the path does not exist. -- Run `python - <<'PY' ... PY` in this repo; the shell returns `python: command not found`, while `python3` works. - -## Proposed improvements -- Expose the Whop MCP server consistently in environments where the workflow is mandatory, or gate the rule when the server is unavailable. -- Ensure the task context provides a valid terminal metadata path, or omit the path when the feature is unavailable. -- Provide a stable `python` shim to `python3`, or document that only `python3` is guaranteed in the environment. - -## Notes -- Missing terminal path from task context: `/home/ubuntu/.cursor/projects/workspace/terminals` -- Successful fallback interpreter: `python3` -- Repo path used for task: `/workspace` From b4a9a27ad5dc3dc3b4f5b4bc93edfd9c49bb5fae Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 24 Mar 2026 03:13:25 +0000 Subject: [PATCH 4/4] Revert "Remove empty API reference docs" This reverts commit d74b8cb40eca29c08e49e239491aaeed8df87f75. --- api-reference/endpoint/create.mdx | 4 + api-reference/endpoint/delete.mdx | 4 + api-reference/endpoint/get.mdx | 4 + api-reference/endpoint/webhook.mdx | 4 + api-reference/introduction.mdx | 33 +++++ api-reference/openapi.json | 217 +++++++++++++++++++++++++++++ docs.json | 20 +++ index.mdx | 7 + quickstart.mdx | 4 + 9 files changed, 297 insertions(+) create mode 100644 api-reference/endpoint/create.mdx create mode 100644 api-reference/endpoint/delete.mdx create mode 100644 api-reference/endpoint/get.mdx create mode 100644 api-reference/endpoint/webhook.mdx create mode 100644 api-reference/introduction.mdx create mode 100644 api-reference/openapi.json diff --git a/api-reference/endpoint/create.mdx b/api-reference/endpoint/create.mdx new file mode 100644 index 0000000..5689f1b --- /dev/null +++ b/api-reference/endpoint/create.mdx @@ -0,0 +1,4 @@ +--- +title: 'Create Plant' +openapi: 'POST /plants' +--- diff --git a/api-reference/endpoint/delete.mdx b/api-reference/endpoint/delete.mdx new file mode 100644 index 0000000..657dfc8 --- /dev/null +++ b/api-reference/endpoint/delete.mdx @@ -0,0 +1,4 @@ +--- +title: 'Delete Plant' +openapi: 'DELETE /plants/{id}' +--- diff --git a/api-reference/endpoint/get.mdx b/api-reference/endpoint/get.mdx new file mode 100644 index 0000000..56aa09e --- /dev/null +++ b/api-reference/endpoint/get.mdx @@ -0,0 +1,4 @@ +--- +title: 'Get Plants' +openapi: 'GET /plants' +--- diff --git a/api-reference/endpoint/webhook.mdx b/api-reference/endpoint/webhook.mdx new file mode 100644 index 0000000..3291340 --- /dev/null +++ b/api-reference/endpoint/webhook.mdx @@ -0,0 +1,4 @@ +--- +title: 'New Plant' +openapi: 'WEBHOOK /plant/webhook' +--- diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx new file mode 100644 index 0000000..c835b78 --- /dev/null +++ b/api-reference/introduction.mdx @@ -0,0 +1,33 @@ +--- +title: 'Introduction' +description: 'Example section for showcasing API endpoints' +--- + + + If you're not looking to build API reference documentation, you can delete + this section by removing the api-reference folder. + + +## Welcome + +There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification. + + + View the OpenAPI specification file + + +## Authentication + +All API endpoints are authenticated using Bearer tokens and picked up from the specification file. + +```json +"security": [ + { + "bearerAuth": [] + } +] +``` diff --git a/api-reference/openapi.json b/api-reference/openapi.json new file mode 100644 index 0000000..da5326e --- /dev/null +++ b/api-reference/openapi.json @@ -0,0 +1,217 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "OpenAPI Plant Store", + "description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification", + "license": { + "name": "MIT" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "http://sandbox.mintlify.com" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "paths": { + "/plants": { + "get": { + "description": "Returns all plants from the system that the user has access to", + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "The maximum number of results to return", + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "200": { + "description": "Plant response", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Plant" + } + } + } + } + }, + "400": { + "description": "Unexpected error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "description": "Creates a new plant in the store", + "requestBody": { + "description": "Plant to add to the store", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NewPlant" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "plant response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Plant" + } + } + } + }, + "400": { + "description": "unexpected error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/plants/{id}": { + "delete": { + "description": "Deletes a single plant based on the ID supplied", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID of plant to delete", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + } + ], + "responses": { + "204": { + "description": "Plant deleted", + "content": {} + }, + "400": { + "description": "unexpected error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + } + }, + "webhooks": { + "/plant/webhook": { + "post": { + "description": "Information about a new plant added to the store", + "requestBody": { + "description": "Plant added to the store", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NewPlant" + } + } + } + }, + "responses": { + "200": { + "description": "Return a 200 status to indicate that the data was received successfully" + } + } + } + } + }, + "components": { + "schemas": { + "Plant": { + "required": [ + "name" + ], + "type": "object", + "properties": { + "name": { + "description": "The name of the plant", + "type": "string" + }, + "tag": { + "description": "Tag to specify the type", + "type": "string" + } + } + }, + "NewPlant": { + "allOf": [ + { + "$ref": "#/components/schemas/Plant" + }, + { + "required": [ + "id" + ], + "type": "object", + "properties": { + "id": { + "description": "Identification number of the plant", + "type": "integer", + "format": "int64" + } + } + } + ] + }, + "Error": { + "required": [ + "error", + "message" + ], + "type": "object", + "properties": { + "error": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + } + } + } + }, + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer" + } + } + } +} \ No newline at end of file diff --git a/docs.json b/docs.json index b476d0b..46b44cc 100644 --- a/docs.json +++ b/docs.json @@ -46,6 +46,26 @@ ] } ] + }, + { + "tab": "API reference", + "groups": [ + { + "group": "API documentation", + "pages": [ + "api-reference/introduction" + ] + }, + { + "group": "Endpoint examples", + "pages": [ + "api-reference/endpoint/get", + "api-reference/endpoint/create", + "api-reference/endpoint/delete", + "api-reference/endpoint/webhook" + ] + } + ] } ], "global": { diff --git a/index.mdx b/index.mdx index d54f87d..15c23fb 100644 --- a/index.mdx +++ b/index.mdx @@ -42,6 +42,13 @@ Design a docs site that looks great and empowers your users. > Organize your docs to help users find what they need and succeed with your product. + + Auto-generate API documentation from OpenAPI specifications. + ## Create beautiful pages diff --git a/quickstart.mdx b/quickstart.mdx index d4a9b86..c711458 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -69,6 +69,10 @@ Now that you have your docs running, explore these key features: Include syntax-highlighted code blocks. + + Auto-generate API docs from OpenAPI specs. + +