Skip to content

docs: add read-only access skill for SDK users#1139

Open
pyramation wants to merge 2 commits into
mainfrom
devin/1778571017-read-only-docs
Open

docs: add read-only access skill for SDK users#1139
pyramation wants to merge 2 commits into
mainfrom
devin/1778571017-read-only-docs

Conversation

@pyramation
Copy link
Copy Markdown
Contributor

@pyramation pyramation commented May 12, 2026

Summary

Adds a new .agents/skills/read-only-access/SKILL.md documenting both read-only access mechanisms for SDK consumers:

  1. Read-Only Memberships (isReadOnly on entity-scoped memberships) — per-entity, per-member restriction via restrictive RLS policies
  2. Read-Only API Keys (accessLevel: 'read_only') — transaction-level enforcement that blocks all writes

Includes SDK/CLI examples, GraphQL mutations, behavior tables, scope details, and a comparison of when to use each mechanism.

This documents features implemented in constructive-db PR #814 (read-only memberships module) and the existing graphile.ts enforcement for read-only API keys.

Updates since last revision

  • Removed internal references (SPRT, AuthzNotReadOnly, pgSettings) per "no private things" requirement — docs now describe behavior without exposing implementation
  • Fixed misleading "invite a member as read-only" example — now correctly documents that the invite flow does not support isReadOnly at invite time; members must be updated after joining
  • Added updateOrgMembership GraphQL example as the primary workflow
  • Clarified that direct org-membership create is admin/owner only and bypasses the invite flow

Review & Testing Checklist for Human

  • Verify the updateOrgMembership GraphQL mutation shape (input: { id, patch: { isReadOnly } }) matches the actual generated schema — PostGraphile update mutations sometimes use nodeId or different patch patterns
  • Verify createApiKey GraphQL mutation field names and return fields (apiKey, accessLevel) match the actual schema
  • Confirm CLI parameter casing: is it --isReadOnly or --is-read-only? Generated reference shows --isReadOnly but verify against actual CLI behavior

Notes

  • The generated CLI reference (references/create-api-key.md) already exposes --input.accessLevel <String> but with no explanation — this skill provides the missing conceptual documentation.
  • The node-type-registry build errors visible in CI are pre-existing on main (missing @babel/types dependency) and unrelated to this docs-only change.
  • This is a docs-only change (single markdown file) — no functional code modified.

Link to Devin session: https://app.devin.ai/sessions/5b846ad23d754cbe903fa86b27c109b4
Requested by: @pyramation

@devin-ai-integration
Copy link
Copy Markdown
Contributor

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant