docs: correct four statements the Azure rebuild made false - #38
Open
mastermanas805 wants to merge 3 commits into
Open
docs: correct four statements the Azure rebuild made false#38mastermanas805 wants to merge 3 commits into
mastermanas805 wants to merge 3 commits into
Conversation
… testing patterns
…agent recovery patterns
All four were found by agents dogfooding the published docs against the live platform, and each one cost a real run time. 1. STORAGE BACKEND. llms.txt described DigitalOcean Spaces (nyc3) and a connection_url of https://s3.instanode.dev/... Object storage is Cloudflare R2 now, and s3.instanode.dev still resolves to the retired DO load balancer, so anything built from that host is dead. Also documented the presign contract properly: `operation` is REQUIRED and must be GET/PUT/HEAD — a caller guessing `method` gets 400 invalid_operation. Removed the claim that "anonymous-tier objects are auto-deleted at 24h by a bucket lifecycle rule". There is deliberately NO bucket-wide rule: the tenant prefix is a bare resource-token UUID with no tier marker, so a bucket rule cannot distinguish an anonymous object from a paying customer's — and a previous whole-bucket rule silently deleted every backup within 24h. Expiry is enforced by the TTL reaper deleting under the tenant prefix. 2. STACK MANIFEST SYNTAX (docs/stacks.md). The published command used `-F "manifest=@instant.yaml"`, which cannot work: the handler reads manifest from the multipart VALUES, so an @-upload lands in the file part and returns 400 missing_manifest. Corrected to `<` with a note explaining why the per-service tarball fields still use `@`. 3. CLAIM RETURNS A USABLE SESSION. `POST /claim`'s 201 carries `session_token`, usable immediately as a Bearer token with no email round-trip — but that appeared ONLY in the raw OpenAPI schema. Both agent-facing docs described only the magic-link flow, which cannot complete today (no mail provider), so per the docs an unattended agent could never obtain a session. Named the exact field, since session_jwt / jwt / api_token are all wrong guesses. 4. REDIS KEY PREFIX. /cache/new returns `key_prefix` and the tenant ACL is scoped to it, so the natural first attempt — a bare `SET mykey` — fails with the native `NOPERM No permissions to access a key`. That is a raw Redis error, not a platform envelope, so it carries no agent_action to recover from. Now stated explicitly. NOT changed here, deliberately: the claim section still says a session "owns every resource attached to your network fingerprint". That is accurate today and is precisely the P0 being fixed — claiming sweeps every unclaimed resource sharing a /24+ASN bucket, so two strangers behind one NAT means whoever claims first inherits the other's live database. Rewriting it before the fix ships would make the docs wrong in the other direction; it lands with that PR so behaviour and documentation change together. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Found by agents dogfooding the published docs against the live platform. Each one cost a real
run time, and three of them are copy-paste-fatal for an agent following instructions literally.
1. Storage backend — wrong vendor, dead hostname, and a lifecycle rule that must not exist
llms.txtdescribed DigitalOcean Spaces (nyc3) withconnection_urlofhttps://s3.instanode.dev/instant-shared/<prefix>/. Object storage is Cloudflare R2 now, ands3.instanode.devstill resolves to the retired DO load balancer — anything constructed from thathost is dead on arrival.
Also documented the presign contract properly:
operationis required and must beGET/PUT/HEAD. A caller guessingmethodgets400 invalid_operation.Removed the claim that anonymous objects are auto-deleted by a bucket lifecycle rule. There is
deliberately no bucket-wide rule. The tenant prefix is a bare resource-token UUID with no tier
marker, so a bucket rule cannot tell an anonymous object from a paying customer's — and the
previous whole-bucket rule silently deleted every backup within 24h. Expiry is enforced by the TTL
reaper deleting under the tenant prefix.
2. The stack deploy command cannot work as published
docs/stacks.mdshowed-F "manifest=@instant.yaml". The handler readsmanifestfrom themultipart values, so an
@upload lands in the file part and returns400 missing_manifest.Corrected to
<, with a note on why the per-service tarball fields still use@.3. Claim returns a usable session — documented nowhere a reader would look
POST /claim's 201 carriessession_token, usable immediately as a Bearer token with no emailround-trip. That appeared only in the raw OpenAPI schema. Both agent-facing docs described only the
magic-link flow — which cannot complete today, because no mail provider is configured.
So per the published docs, an unattended agent could never obtain a session. It always could. Named
the exact field, since
session_jwt/jwt/api_tokenare all plausible wrong guesses.4. Redis keys must carry
key_prefix/cache/newreturnskey_prefixand the tenant's ACL is scoped to it, so the natural firstattempt — a bare
SET mykey— fails withNOPERM No permissions to access a key. That is a nativeRedis error, not a platform envelope, so there is no
agent_actionto recover from. Now explicit.Deliberately not changed
The claim section still reads "owns every resource attached to your network fingerprint."
That is accurate today and is exactly the P0 under repair: claiming sweeps every unclaimed
resource sharing a
/24 + ASNbucket, so two strangers behind one NAT means whoever claims firstinherits the other's live database. Rewriting it now would make the docs wrong in the other
direction. It changes with that fix, so behaviour and documentation land together.
Follow-up
instanode-web/public/llms.txtneeds the matching fallback edit — the build syncs from this repo,but the committed fallback should not diverge in the meantime.
🤖 Generated with Claude Code