Document how the @self/v1 extend is what pulls the API

[jviotti]

Signed-off-by: Juan Cruz Viotti jv@jviotti.com

[augmentcode]

🤖 Augment PR Summary

Summary: Documents that the HTTP API and its describing JSON Schemas come from the built-in @self/v1 collection, and warns that this will need to be explicitly enabled via extends in a future release.
Changes: Adds a warning/note to the API and Getting Started docs and updates configuration examples to include @self/v1 to avoid future disruption.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 1 suggestion posted.

Comment augment review to trigger a new review at any time.

[augmentcode]

In docs/api.md:14, recommending "extends": [ "@self/v1" ] could be interpreted as replacing an existing extends list, which might lead readers to accidentally drop other required entries. Consider clarifying that @self/v1 should be added to the existing extends array (if present) rather than overwriting it.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

[cubic-dev-ai]

1 issue found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/api.md">

<violation number="1" location="docs/api.md:14">
P2: This recommendation can mislead users into replacing their entire `extends` array with only `@self/v1`. Tell readers to add `@self/v1` to the existing array instead of showing a single-entry replacement.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[github-actions]

Benchmark Index (community)

Details

Benchmark suite	Current: f0b8b40	Previous: 68468d4	Ratio
Add one schema (0 existing)	21 ms	22 ms	0.95
Add one schema (100 existing)	25 ms	24 ms	1.04
Add one schema (1000 existing)	79 ms	77 ms	1.03
Add one schema (10000 existing)	657 ms	654 ms	1.00
Update one schema (1 existing)	18 ms	17 ms	1.06
Update one schema (101 existing)	27 ms	25 ms	1.08
Update one schema (1001 existing)	79 ms	78 ms	1.01
Update one schema (10001 existing)	669 ms	666 ms	1.00
Cached rebuild (1 existing)	10 ms	10 ms	1
Cached rebuild (101 existing)	12 ms	13 ms	0.92
Cached rebuild (1001 existing)	34 ms	34 ms	1
Cached rebuild (10001 existing)	269 ms	263 ms	1.02
Index 100 schemas	147 ms	120 ms	1.23
Index 1000 schemas	1277 ms	974 ms	1.31
Index 10000 schemas	14484 ms	13387 ms	1.08

This comment was automatically generated by workflow using github-action-benchmark.

[github-actions]

Benchmark Index (enterprise)

Details

Benchmark suite	Current: f0b8b40	Previous: 68468d4	Ratio
Add one schema (0 existing)	22 ms	22 ms	1
Add one schema (100 existing)	29 ms	26 ms	1.12
Add one schema (1000 existing)	76 ms	86 ms	0.88
Add one schema (10000 existing)	634 ms	614 ms	1.03
Update one schema (1 existing)	20 ms	20 ms	1
Update one schema (101 existing)	28 ms	26 ms	1.08
Update one schema (1001 existing)	78 ms	84 ms	0.93
Update one schema (10001 existing)	632 ms	638 ms	0.99
Cached rebuild (1 existing)	12 ms	11 ms	1.09
Cached rebuild (101 existing)	14 ms	14 ms	1
Cached rebuild (1001 existing)	35 ms	37 ms	0.95
Cached rebuild (10001 existing)	268 ms	265 ms	1.01
Index 100 schemas	129 ms	116 ms	1.11
Index 1000 schemas	1019 ms	1060 ms	0.96
Index 10000 schemas	13714 ms	13280 ms	1.03

This comment was automatically generated by workflow using github-action-benchmark.