docs(insta): manifest pgVersion, storage buckets and strict service keys

[CarmenDou]

What

insta/cli-reference.md teaches agents the new template manifest fields: pgVersion on a postgres service, a storage bucket with public, the five storage keys reachable through env.platform, and that a bucket takes no region. The rules table gains a storage row, which carries the CLI version floor, and a row saying a misspelt service key is now refused by name. The validation paragraph says what the CLI no longer checks locally. The template info and --region wording follow the CLI change.

Spec: docs/superpowers/specs/2026-10-05-template-service-definition-v1-design.md in the insta-cloud superproject (section 5, skills). Merge after the CLI release that carries the change, and after the platform change (InsForge/instacloud-platform#625) is live in production.

How

• The sample manifest gains pgVersion, a private files bucket with public: true shown only as a comment (so a copied sample never makes a world-readable bucket), and env.platform lines for its keys, AWS_REGION included.
• The storage keys were read from CANONICAL_KEYS.storage in the platform's src/provisioning/secretNames.ts at 8bdadd38, not copied from another doc.
• The storage rule tells the agent to say so to the person it deploys for, because a public bucket is readable by anyone, and says the deploy is gated by service.setAccess. The quoted refusals are the platform's own sentences.
• Four rules became six.

Verify

• python3 .github/check-markdown.py passes, so every code fence pairs and every table row matches its header.
• No @CLI_VERSION@ token is left in the file, and the floor equals the released CLI version.

🤖 Generated with Claude Code

---

Summary by cubic

Documents new template manifest fields in insta/cli-reference.md: pgVersion on a postgres service, a storage bucket with optional public, the five storage keys reachable through env.platform, and that a bucket takes no region. Also records that misspelt service keys are now refused by name, that the CLI no longer validates non-web/worker service types locally, and that storage and template info need CLI ≥ 0.1.19.

• The sample manifest keeps the bucket private (public: true shown only as a comment) and binds all five storage keys via env.platform, AWS_REGION included.
• The storage rule says to tell the person you deploy for that a public bucket is readable by anyone, and that deploying one is gated by service.setAccess.
• Merge once CLI 0.1.19 and InsForge/instacloud-platform#625 are live.

^{Written for commit 5f6a1e3. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="insta/cli-reference.md">

<violation number="1" location="insta/cli-reference.md:571">
P3: These examples drop the braces required by the documented `${{services...}}` syntax, so they are not valid manifest references. Spell both refused examples as `${{services.<name>.url}}` and `${{services.<name>.host}}`.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

P3: These examples drop the braces required by the documented ${{services...}} syntax, so they are not valid manifest references. Spell both refused examples as ${{services.<name>.url}} and ${{services.<name>.host}}.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At insta/cli-reference.md, line 571:

<comment>These examples drop the braces required by the documented `${{services...}}` syntax, so they are not valid manifest references. Spell both refused examples as `${{services.<name>.url}}` and `${{services.<name>.host}}`.</comment>

<file context>
@@ -554,10 +563,15 @@ services:
+in this same manifest and the credential key it mints. A postgres service mints `DATABASE_URL`. A
+storage service mints `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`,
+`BUCKET_NAME` and `AWS_REGION`. The platform resolves the reference while writing variables, before
+the app starts. A database and a bucket have no address, so `${services.<name>.url}` and `.host`
+are refused for them. A public bucket's address is not a reference either: the app builds it from
+`BUCKET_NAME` plus the platform's public storage host, which no `env.platform` key carries, see
</file context>

Suggested change

	the app starts. A database and a bucket have no address, so `${services.<name>.url}` and `.host`
	the app starts. A database and a bucket have no address, so `${{services.<name>.url}}` and `${{services.<name>.host}}`

[jwfing]

Summary

The manifest guidance is broadly consistent with the stated intent, but the unreplaced CLI-version token blocks publication.

Requirements context

I assessed the change against the PR description, the repository’s existing Templates and storage guidance, and the related CLI PR #351. The referenced superproject design document is not present in this checkout, and platform PR #625 was not publicly accessible; CLI PR #351 confirms that the compatibility floor must come from the release cut after that currently open CLI change merges.

Findings

Critical

• Replace the unresolved release placeholders before merging. Both compatibility notices render the literal @CLI_VERSION@, so readers cannot determine which CLI accepts storage services or displays the new service details. This also directly contradicts the PR’s verification statement that no such token remains. Wait for the dependent CLI release, then substitute its actual version in both locations. (insta/cli-reference.md:85-85, insta/cli-reference.md:606-606)

Suggestion

(none)

Information

• Software engineering: This is documentation-only, so no behavioral unit tests are expected. The head commit’s repository sanity check passed, including Markdown fence/table validation, and git diff --check is clean. (insta/cli-reference.md:535-616)
• Functionality: Apart from the version floor, the sample and surrounding rules cover pgVersion, private-by-default storage, all five platform keys, region behavior, strict service fields, and changed validation ownership. (insta/cli-reference.md:535-616)
• Security: No executable security surface changes. The guidance explicitly warns that public buckets permit anonymous reads and identifies the service.setAccess gate. (insta/cli-reference.md:542-542, insta/cli-reference.md:606-606)
• Performance: No performance-relevant changes; this PR modifies static documentation only. (insta/cli-reference.md:85-616)

Verdict

Request changes — one Critical finding must be resolved by replacing both placeholders with the released CLI version.

[jwfing]

LGTM - approved.

[jwfing]

Summary

The PR accurately documents the new template service definition, with one minor reference-syntax typo.

Requirements context

I assessed the change against the PR title and description, existing template/storage guidance, and repository conventions. The referenced superproject design document is not present in this checkout and was not publicly accessible, so its requirements could not be independently inspected.

Findings

Critical

(none)

Suggestion

• insta/cli-reference.md:566-572 — The paragraph first defines references as ${{services.<service>.<KEY>}}, but the negative URL example uses ${services.<name>.url} with only one pair of braces. Write ${{services.<name>.url}} (and preferably ${{services.<name>.host}}) so the example demonstrates rejection of a syntactically valid reference for semantic reasons, rather than rejection caused by malformed syntax.

Information

• Software engineering/functionality: The focused documentation change covers pgVersion, a private-by-default storage example, all five canonical storage keys, the CLI/platform validation boundary, strict service keys, region behavior, and the CLI 0.1.19 floor (insta/cli-reference.md:85-86, insta/cli-reference.md:502-616). No runtime test coverage is applicable. git diff --check passed, no @CLI_VERSION@ token remains, and an equivalent execution of the repository's fence/table validation logic passed; the exact Python script could not run because Python is unavailable in the review image (.github/check-markdown.py:1-93).
• Security: The copied manifest remains private by default, and the documentation explicitly warns that public buckets are anonymously readable and governed by service.setAccess; no secrets are embedded or exposed (insta/cli-reference.md:540-556, insta/cli-reference.md:606-606).
• Performance: This PR changes documentation only and introduces no runtime code, queries, loops, allocations, or I/O behavior (insta/cli-reference.md:85-86, insta/cli-reference.md:492-616).

Verdict

Approved under the stated verdict rule: zero Critical findings. The syntax correction is recommended but non-blocking.