DEV-2032: document context.settings and the three app-settings tiers

[Arpanexe]

What

DEV-2032. Documents context.settings for V3 app actions, and replaces the two-tier app-settings model with the three tiers the API now enforces.

Companion PRs: Fliplet/fliplet-api#8639, plus same-named branches in fliplet-service-browser and fliplet-studio.

Why this one matters more than a normal docs change

Studio's AI Builder fetches docs/API/core/app-actions-v3.md at runtime and is told that loaded docs are binding. A wrong sentence here does not only mislead a reader - it steers the code the AI generates for customers.

That page previously stated: "The context parameter is an object with a single property: payload. The context object does not contain any other properties." That directly contradicts the feature.

Changes

docs/API/core/app-actions-v3.md

• The Context object section now documents both payload and settings.
• New context.settings section: server-environment only, every top-level _-prefixed key of the master app, read fresh on every run, {} for client and any, the 100 KB limit with the exact error string, and the defensive read.
• One complete example: reads the credential, returns early when not configured, sends the key in an Authorization header, and returns fixed error codes so nothing leaks.
• Both credential sources are described: a Fliplet AI Builder secure panel field, saved as _aiartifact_<settingKey> (a private key, readable by Studio editors over the API), and a __ protected key written through the REST API.
• The headless-browser cross-origin limit, and the leak rule - never return, log, throw, or put a setting in a URL or query string. A provider that only accepts its key in the URL cannot be called under that rule.

docs/API/v3/app-settings.md

• Three-tier table replacing the two-row one, and a Protected settings section covering what the API now does: every HTTP read omits __ for editors, admins and API tokens; editors may write and delete but never read back; task tokens get 403; version snapshots no longer store them and a restore keeps current values.
• Corrects the false claim that app actions read the full app.settings from the model.
• Corrects the save endpoint. The page's only save example used PUT /v1/apps/:id with a nested settings object. That endpoint does not write settings - its handler assigns an allow-list that does not include them - so the call returns 200 and stores nothing, and a server action then reports the credential as not configured with no error anywhere. The section now documents POST /v1/apps/:id/settings with the keys flat in the body, on the master app id, with the shallow-merge semantics, plus a warning about the old example and a new Removing settings section for DELETE.
• Documents the settingKey sanitizer: characters outside a-zA-Z0-9_.- become _, and a key containing - or . needs bracket access.

Generated projections (llms-full.txt, llms.txt, agent-skills/index.json, agent-skills/fliplet-js-api/SKILL.md) regenerated with the repo's own generator. No generated file was hand-edited.

Testing

npm run test:unit: 163 passing, 0 failing.

Every behavioural claim was verified against the shipping source in the companion repos rather than against a brief - libs/lambda.js, libs/filterPrivateSettings.js, models/app.js, libs/v3/app-version-service.js, the settings and admin routes, core.js, and Studio's useArtifactDestinationWriters.js. A 26-row table of every protected-key sentence was checked line by line, twice.

Note for anyone validating locally: npm run check:docs exits 0 with no output on Windows and validates nothing. The entry guard at docs/bin/build-agent-indexes.mjs:1169 compares a file:// URL against a backslash argv path, so main() never runs. CI on Linux is unaffected. The real local equivalent, which was run and exits 0 across 203 docs with no frontmatter, capability, catalog or cross-link errors:

MSYS_NO_PATHCONV=1 node --input-type=module -e "await import('file://' + process.argv[1])" <repo>/docs/bin/build-agent-indexes.mjs --strict

Two pre-existing drifts were deliberately kept out of this diff: the generatedAt timestamp in llms-v3-libraries.json, and two stale hunks in an unrelated transcription example in llms-full.txt (a doc was changed without regenerating). The second is worth a separate fix.

Follow-up to raise

docs/API/v3/routing.md:43 carries the same wrong claim - that the route manifest is updated "via the App Settings API (PUT /v1/apps/:id with settings.v3)". It is outside this change, but after this merges the two pages contradict each other inside the same llms-full.txt, so an AI writing route-manifest code would still follow the wrong one and silently store nothing.

Deploy order

These docs ship last: fliplet-api in all three regions, then the fliplet-service-browser runner image, then fliplet-studio, then this. Merging to master publishes developers.fliplet.com, which is what the AI Builder fetches at runtime. Shipping early would promise context.settings the runner does not yet deliver, and promise __ protection the API does not yet enforce - an app owner could store a live secret in a __ key that is still readable over HTTP.

🤖 Generated with Claude Code

[zeryabkhan91]

LGTM