nubase_cli 0.1.0 → 0.1.2

package/dist/src/nubase-client.js

@@ -7,6 +7,45 @@ export class NubaseClient {
     capabilities() {
         return this.request('/agent/v1/capabilities');
     }
+    // --- One-shot backend snapshot -----------------------------------------
+    // Aggregates the read-only state an agent needs to start work into a single
+    // round-trip: capabilities, schema, buckets, auth users, and gateway keys.
+    // Each section degrades to { error } so an unauthorized or unsupported area
+    // never blocks the rest of the snapshot.
+    async overview(args = {}) {
+        const schema = typeof args.schema === 'string' && args.schema ? args.schema : 'public';
+        const [capabilities, database, storage, auth, aiGateway] = await Promise.all([
+            safeSection(() => this.capabilities()),
+            safeSection(() => this.dbExportSchema({ schema })),
+            safeSection(() => this.storageListBuckets({ limit: 100 })),
+            safeSection(() => this.authListUsers({ perPage: 1 })),
+            safeSection(() => this.gatewayListKeys()),
+        ]);
+        return {
+            nubaseUrl: this.config.nubaseUrl,
+            project: {
+                keyConfigured: Boolean(this.config.projectKey),
+                userScoped: Boolean(this.config.userJwt),
+                agentId: this.config.agentId,
+            },
+            permissions: {
+                sqlExecute: this.config.allowSqlExecute,
+                dangerousSql: this.config.allowDangerousSql,
+                adminWrite: this.config.allowAdminWrite,
+            },
+            capabilities,
+            database: { schema, ...database },
+            storage,
+            auth,
+            aiGateway,
+            nextSteps: [
+                'Call memory_context({ task }) before planning to recall prior decisions.',
+                'Inspect database above (or db_export_schema) before any schema change; sql_dry_run before sql_execute.',
+                'Use /rest/v1, /auth/v1, /storage/v1 in generated app code; service-role keys stay server-side.',
+                'Write durable decisions with memory_write when the task is done.',
+            ],
+        };
+    }
     instructions() {
         return this.request('/agent/v1/instructions');
     }
@@ -42,6 +81,93 @@ export class NubaseClient {
         const query = typeof args.query === 'string' && args.query ? args.query : 'select=*';
         return this.request(`/rest/v1/${encodeURIComponent(table)}?${query}`);
     }
+    // --- Storage (Supabase-style /storage/v1) -------------------------------
+    storageListBuckets(args) {
+        const query = buildQuery({ search: args.search, limit: args.limit, offset: args.offset });
+        return this.request(`/storage/v1/bucket${query}`);
+    }
+    storageCreateBucket(args) {
+        const name = requiredString(args.name, 'name');
+        return this.guardedWrite('create bucket', () => this.request('/storage/v1/bucket', {
+            method: 'POST',
+            body: {
+                name,
+                public: args.public === true,
+                file_size_limit: typeof args.fileSizeLimit === 'number' ? args.fileSizeLimit : undefined,
+            },
+        }));
+    }
+    storageDeleteBucket(args) {
+        const bucketId = requiredString(args.bucketId, 'bucketId');
+        return this.guardedWrite('delete bucket', () => this.request(`/storage/v1/bucket/${encodeURIComponent(bucketId)}`, { method: 'DELETE' }));
+    }
+    // --- Auth admin (Supabase-style /auth/v1/admin) -------------------------
+    authListUsers(args) {
+        const query = buildQuery({ page: args.page, per_page: args.perPage, keyword: args.keyword });
+        return this.request(`/auth/v1/admin/users${query}`);
+    }
+    authCreateUser(args) {
+        const email = requiredString(args.email, 'email');
+        return this.guardedWrite('create user', () => this.request('/auth/v1/admin/users', {
+            method: 'POST',
+            body: {
+                email,
+                password: typeof args.password === 'string' ? args.password : undefined,
+                phone: typeof args.phone === 'string' ? args.phone : undefined,
+                role: typeof args.role === 'string' ? args.role : undefined,
+            },
+        }));
+    }
+    authDeleteUser(args) {
+        const userId = requiredString(args.userId, 'userId');
+        const query = buildQuery({ should_soft_delete: args.softDelete === true ? 'true' : undefined });
+        return this.guardedWrite('delete user', () => this.request(`/auth/v1/admin/users/${encodeURIComponent(userId)}${query}`, { method: 'DELETE' }));
+    }
+    // --- Database schema introspection --------------------------------------
+    dbExportSchema(args) {
+        return this.request('/auth/v1/admin/schema/export-ddl', {
+            method: 'POST',
+            body: {
+                schemaName: typeof args.schema === 'string' && args.schema ? args.schema : 'public',
+                tableNames: typeof args.tables === 'string' ? args.tables : undefined,
+                includeDropStatements: args.includeDrop === true,
+            },
+        });
+    }
+    // --- AI Gateway control plane (/ai-gateway/admin/v1) --------------------
+    gatewayListKeys() {
+        return this.request('/ai-gateway/admin/v1/keys');
+    }
+    gatewayIssueKey(args) {
+        return this.guardedWrite('issue gateway key', () => this.request('/ai-gateway/admin/v1/keys', {
+            method: 'POST',
+            body: {
+                name: typeof args.name === 'string' && args.name ? args.name : 'Untitled key',
+                description: typeof args.description === 'string' ? args.description : undefined,
+                expiresAt: typeof args.expiresAt === 'string' ? args.expiresAt : undefined,
+            },
+        }));
+    }
+    gatewayRevokeKey(args) {
+        const id = requiredString(args.id, 'id');
+        return this.guardedWrite('revoke gateway key', () => this.request(`/ai-gateway/admin/v1/keys/${encodeURIComponent(id)}`, { method: 'DELETE' }));
+    }
+    gatewayUsage(args) {
+        const query = buildQuery({ start_date: args.startDate, end_date: args.endDate });
+        return this.request(`/ai-gateway/admin/v1/usage/overview${query}`);
+    }
+    async guardedWrite(action, run) {
+        if (!this.config.allowAdminWrite) {
+            return {
+                success: false,
+                code: 'PERMISSION_GATE_OFF',
+                error: `Cannot ${action}: this is supported but admin writes are gated off by default. This is a permission switch, not a missing feature — it will work once enabled.`,
+                remedy: 'Set NUBASE_ALLOW_ADMIN_WRITE=true in the MCP bridge env, then retry.',
+                userAction: `Ask the user to enable admin writes (NUBASE_ALLOW_ADMIN_WRITE=true) so you can ${action}.`,
+            };
+        }
+        return run();
+    }
     sqlDryRun(args) {
         const sql = requiredString(args.sql, 'sql');
         const risk = classifySql(sql);
@@ -58,14 +184,20 @@ export class NubaseClient {
         if (!this.config.allowSqlExecute) {
             return {
                 success: false,
-                error: 'SQL execution is disabled. Set NUBASE_ALLOW_SQL_EXECUTE=true to enable it.',
+                code: 'PERMISSION_GATE_OFF',
+                error: 'SQL execution is supported but gated off by default. This is a permission switch, not a missing feature.',
+                remedy: 'Set NUBASE_ALLOW_SQL_EXECUTE=true in the MCP bridge env, then retry.',
+                userAction: 'Ask the user to enable SQL execution (NUBASE_ALLOW_SQL_EXECUTE=true) before retrying.',
                 dryRun,
             };
         }
         if (dryRun.risk === 'DANGEROUS' && !this.config.allowDangerousSql) {
             return {
                 success: false,
-                error: 'Dangerous SQL is blocked. Set NUBASE_ALLOW_DANGEROUS_SQL=true to allow it.',
+                code: 'DANGEROUS_SQL_BLOCKED',
+                error: 'This statement is classified DANGEROUS (e.g. drop/truncate/bulk delete) and is blocked by default.',
+                remedy: 'Set NUBASE_ALLOW_DANGEROUS_SQL=true to allow it, and confirm the operation with the user first.',
+                userAction: 'Confirm the destructive intent with the user, then ask them to set NUBASE_ALLOW_DANGEROUS_SQL=true.',
                 dryRun,
             };
         }
@@ -73,7 +205,60 @@ export class NubaseClient {
             method: 'POST',
             body: { query: sql },
         });
-        return { risk: dryRun.risk, ...result };
+        const out = { risk: dryRun.risk, ...result };
+        // Audit trail: record schema-changing executions so they can be reviewed
+        // and replayed later. Best-effort — a failure here never fails the execute.
+        const isSchemaChange = dryRun.risk === 'SCHEMA_WRITE' || dryRun.risk === 'DANGEROUS';
+        const succeeded = !result || result.success !== false;
+        if (this.config.recordMigrations !== false && isSchemaChange && succeeded) {
+            try {
+                await this.recordMigration({ sql, risk: dryRun.risk, statementCount: dryRun.statementCount });
+                out.migrationRecorded = true;
+            }
+            catch (err) {
+                out.migrationRecorded = false;
+                out.migrationError = err instanceof Error ? err.message : String(err);
+            }
+        }
+        return out;
+    }
+    // Append-only audit table in a dedicated `nubase` schema (kept out of public
+    // so it does not clutter the user's app schema). Ensured idempotently.
+    async recordMigration(entry) {
+        const query = `create schema if not exists nubase;
+create table if not exists nubase.migrations (
+  id bigint generated always as identity primary key,
+  applied_at timestamptz not null default now(),
+  risk text not null,
+  statement_count integer not null default 1,
+  sql text not null,
+  agent_id text,
+  run_id text,
+  user_id text
+);
+insert into nubase.migrations (risk, statement_count, sql, agent_id, run_id, user_id)
+values (${sqlLiteral(entry.risk)}, ${entry.statementCount}, ${sqlLiteral(entry.sql)}, ${sqlLiteralOrNull(this.config.agentId)}, ${sqlLiteralOrNull(this.config.runId)}, ${sqlLiteralOrNull(this.config.userId)});`;
+        return this.request('/auth/v1/admin/sql/execute', { method: 'POST', body: { query } });
+    }
+    // Read the audit trail. Hardcoded SELECT against our own table, so it does not
+    // require NUBASE_ALLOW_SQL_EXECUTE (reading the log is always safe).
+    async listMigrations(args = {}) {
+        const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(Math.floor(args.limit), 200) : 50;
+        try {
+            return await this.request('/auth/v1/admin/sql/execute', {
+                method: 'POST',
+                body: {
+                    query: `select id, applied_at, risk, statement_count, sql, agent_id, run_id, user_id from nubase.migrations order by applied_at desc limit ${limit};`,
+                },
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (/does not exist|nubase\.migrations/i.test(message)) {
+                return { migrations: [], note: 'No migrations recorded yet (nubase.migrations not present).' };
+            }
+            throw err;
+        }
     }
     async request(path, options = {}) {
         if (!this.config.projectKey) {
@@ -99,6 +284,14 @@ export class NubaseClient {
         return data;
     }
 }
+async function safeSection(run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
 function parseResponse(text) {
     if (!text)
         return null;
@@ -109,9 +302,26 @@ function parseResponse(text) {
         return text;
     }
 }
+function buildQuery(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        search.set(key, String(value));
+    }
+    const query = search.toString();
+    return query ? `?${query}` : '';
+}
 function requiredString(value, name) {
     if (typeof value !== 'string' || !value.trim()) {
         throw new Error(`${name} is required`);
     }
     return value;
 }
+// Postgres string literal with single quotes doubled — safe for arbitrary text.
+function sqlLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function sqlLiteralOrNull(value) {
+    return value === undefined || value === null ? 'NULL' : sqlLiteral(String(value));
+}

package/dist/src/tools.js

@@ -3,7 +3,7 @@ import { fetchDocs } from './docs.js';
 export const TOOLS = [
     {
         name: 'fetch_docs',
-        description: 'Fetch bundled Nubase agent docs. Topics: overview, setup, memory, database, auth, storage, ai_gateway, supabase_compatibility, security, or all.',
+        description: 'Fetch bundled Nubase agent docs. Topics: overview, quickstart, setup, memory, database, auth, storage, ai_gateway, security, or all.',
         inputSchema: objectSchema({
             topic: { type: 'string' },
         }),
@@ -18,6 +18,13 @@ export const TOOLS = [
         description: 'Return agent instructions for using Nubase safely.',
         inputSchema: objectSchema({}),
     },
+    {
+        name: 'nubase_overview',
+        description: 'One-shot snapshot of the whole backend in a single call: capabilities, database schema, storage buckets, auth users, AI Gateway keys, current permissions, and suggested next steps. Call this first when starting a Nubase task. Read-only; each section degrades gracefully if unauthorized.',
+        inputSchema: objectSchema({
+            schema: { type: 'string' },
+        }),
+    },
     {
         name: 'memory_context',
         description: 'Return compact relevant memory context for a task. Scope defaults can come from NUBASE_USER_ID, NUBASE_AGENT_ID, and NUBASE_RUN_ID.',
@@ -69,6 +76,99 @@ export const TOOLS = [
         description: 'Execute SQL through Nubase admin API. Disabled unless NUBASE_ALLOW_SQL_EXECUTE=true.',
         inputSchema: objectSchema({ sql: { type: 'string' } }, ['sql']),
     },
+    {
+        name: 'db_export_schema',
+        description: 'Export table DDL for a Postgres schema (default public) to inspect the database structure. Read-only.',
+        inputSchema: objectSchema({
+            schema: { type: 'string' },
+            tables: { type: 'string' },
+            includeDrop: { type: 'boolean' },
+        }),
+    },
+    {
+        name: 'db_list_migrations',
+        description: 'List the audit trail of schema-changing SQL applied through sql_execute (most recent first), with timestamp, risk, and the SQL text. Read-only; returns an empty list if nothing has been recorded yet.',
+        inputSchema: objectSchema({
+            limit: { type: 'number' },
+        }),
+    },
+    {
+        name: 'storage_list_buckets',
+        description: 'List Nubase storage buckets. Read-only.',
+        inputSchema: objectSchema({
+            search: { type: 'string' },
+            limit: { type: 'number' },
+            offset: { type: 'number' },
+        }),
+    },
+    {
+        name: 'storage_create_bucket',
+        description: 'Create a storage bucket. Write op; disabled unless NUBASE_ALLOW_ADMIN_WRITE=true.',
+        inputSchema: objectSchema({
+            name: { type: 'string' },
+            public: { type: 'boolean' },
+            fileSizeLimit: { type: 'number' },
+        }, ['name']),
+    },
+    {
+        name: 'storage_delete_bucket',
+        description: 'Delete a storage bucket. Write op; disabled unless NUBASE_ALLOW_ADMIN_WRITE=true.',
+        inputSchema: objectSchema({ bucketId: { type: 'string' } }, ['bucketId']),
+    },
+    {
+        name: 'auth_list_users',
+        description: 'List auth users with optional keyword search. Read-only.',
+        inputSchema: objectSchema({
+            page: { type: 'number' },
+            perPage: { type: 'number' },
+            keyword: { type: 'string' },
+        }),
+    },
+    {
+        name: 'auth_create_user',
+        description: 'Create an auth user. Write op; disabled unless NUBASE_ALLOW_ADMIN_WRITE=true.',
+        inputSchema: objectSchema({
+            email: { type: 'string' },
+            password: { type: 'string' },
+            phone: { type: 'string' },
+            role: { type: 'string' },
+        }, ['email']),
+    },
+    {
+        name: 'auth_delete_user',
+        description: 'Delete an auth user by id. Write op; disabled unless NUBASE_ALLOW_ADMIN_WRITE=true.',
+        inputSchema: objectSchema({
+            userId: { type: 'string' },
+            softDelete: { type: 'boolean' },
+        }, ['userId']),
+    },
+    {
+        name: 'gateway_list_keys',
+        description: 'List AI Gateway self-routing keys (nbk_) for this project. Read-only.',
+        inputSchema: objectSchema({}),
+    },
+    {
+        name: 'gateway_issue_key',
+        description: 'Issue a new AI Gateway key (full key returned once). Write op; disabled unless NUBASE_ALLOW_ADMIN_WRITE=true.',
+        inputSchema: objectSchema({
+            name: { type: 'string' },
+            description: { type: 'string' },
+            expiresAt: { type: 'string' },
+        }),
+    },
+    {
+        name: 'gateway_revoke_key',
+        description: 'Revoke an AI Gateway key by id. Write op; disabled unless NUBASE_ALLOW_ADMIN_WRITE=true.',
+        inputSchema: objectSchema({ id: { type: 'string' } }, ['id']),
+    },
+    {
+        name: 'gateway_usage',
+        description: 'AI Gateway usage overview (tokens, requests, cost) for a date range. Read-only.',
+        inputSchema: objectSchema({
+            startDate: { type: 'string' },
+            endDate: { type: 'string' },
+        }),
+    },
 ];
 export async function callTool(name, args, config, client) {
     switch (name) {
@@ -78,6 +178,8 @@ export async function callTool(name, args, config, client) {
             return client.capabilities();
         case 'nubase_instructions':
             return client.instructions();
+        case 'nubase_overview':
+            return client.overview(args);
         case 'memory_context':
             return client.memoryContext(withScope(config, args));
         case 'memory_search':
@@ -90,6 +192,30 @@ export async function callTool(name, args, config, client) {
             return client.sqlDryRun(args);
         case 'sql_execute':
             return client.sqlExecute(args);
+        case 'db_export_schema':
+            return client.dbExportSchema(args);
+        case 'db_list_migrations':
+            return client.listMigrations(args);
+        case 'storage_list_buckets':
+            return client.storageListBuckets(args);
+        case 'storage_create_bucket':
+            return client.storageCreateBucket(args);
+        case 'storage_delete_bucket':
+            return client.storageDeleteBucket(args);
+        case 'auth_list_users':
+            return client.authListUsers(args);
+        case 'auth_create_user':
+            return client.authCreateUser(args);
+        case 'auth_delete_user':
+            return client.authDeleteUser(args);
+        case 'gateway_list_keys':
+            return client.gatewayListKeys();
+        case 'gateway_issue_key':
+            return client.gatewayIssueKey(args);
+        case 'gateway_revoke_key':
+            return client.gatewayRevokeKey(args);
+        case 'gateway_usage':
+            return client.gatewayUsage(args);
         default:
             throw new Error(`Unknown tool: ${name}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nubase_cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "bin": {

package/skills/nubase/SKILL.md

@@ -20,9 +20,9 @@ It provides:
 
 When starting a Nubase task:
 
-1. Call `fetch_docs({ "topic": "overview" })` if the MCP tool is available.
+1. Call `nubase_overview()` first. One call returns the whole backend state — capabilities, database schema, storage buckets, auth users, AI Gateway keys, the permission gates that are on/off, and suggested next steps. Use it instead of separately calling `db_export_schema` + `storage_list_buckets` + `auth_list_users` + `gateway_list_keys`.
 2. Call `memory_context({ "task": "<current task>" })`.
-3. Identify which capability owns the work and read the matching reference:
+3. Read `fetch_docs({ "topic": "overview" })` or a focused reference if you need detail. Identify which capability owns the work and read the matching reference:
    - `references/memory.md`
    - `references/database.md`
    - `references/auth-storage.md`
@@ -35,6 +35,9 @@ When starting a Nubase task:
 
 Expected tools from `nubase_cli`:
 
+Core:
+
+- `nubase_overview` (start here — one-shot backend snapshot)
 - `fetch_docs`
 - `nubase_capabilities`
 - `nubase_instructions`
@@ -45,6 +48,10 @@ Expected tools from `nubase_cli`:
 - `sql_dry_run`
 - `sql_execute`
 
+Backend ops (read): `db_export_schema`, `db_list_migrations`, `storage_list_buckets`, `auth_list_users`, `gateway_list_keys`, `gateway_usage`.
+
+Backend ops (write, gated by `NUBASE_ALLOW_ADMIN_WRITE=true`): `storage_create_bucket`, `storage_delete_bucket`, `auth_create_user`, `auth_delete_user`, `gateway_issue_key`, `gateway_revoke_key`. When the gate is off, these return `{ success: false, error }` without touching the backend. See `references/auth-storage.md` and `references/ai-gateway.md`.
+
 If a tool is unavailable, continue with REST/API guidance and tell the user what automation was unavailable.
 
 ## Setup
@@ -84,16 +91,7 @@ This installs one Nubase skill directory containing:
 
 ## Compatibility Language
 
-Say "Supabase-style" or "Supabase-compatible subset" unless exact SDK behavior is tested.
-
-Nubase targets common app-building compatibility for:
-
-- `/auth/v1`
-- `/rest/v1`
-- `/storage/v1`
-- `apikey` plus optional `Authorization: Bearer <jwt>`
-
-Do not claim complete Supabase Cloud replacement. Realtime, Edge Functions, and some SDK-specific edge cases may be absent.
+`/auth/v1`, `/rest/v1`, and `/storage/v1` are Supabase-style compatible subsets (use `apikey` plus optional `Authorization: Bearer <jwt>`). Say "Supabase-style", not a complete Supabase Cloud replacement, unless exact SDK behavior is tested — Realtime, Edge Functions, and some SDK edge cases may be absent.
 
 ## Core Safety Rules
 

package/skills/nubase/references/ai-gateway.md

@@ -2,7 +2,23 @@
 
 Use this reference when configuring Nubase AI Gateway, model routing, OpenAI-compatible base URLs, Anthropic-compatible base URLs, gateway keys, usage logs, pricing, provider abstraction, or agent model configuration.
 
-AI Gateway is separate from MCP tools.
+Model-call routing (the `/v1` surface below) is separate from MCP tools, but the gateway control plane is exposed as MCP tools.
+
+## Control-Plane Tools
+
+Manage the project's gateway keys and usage without leaving the agent. These require the project key to carry `service_role`.
+
+Read (always available):
+
+- `gateway_list_keys()` — list this project's `nbk_` self-routing keys (no plaintext/secret returned)
+- `gateway_usage({ startDate?, endDate? })` — tokens, requests, and cost overview for a date range
+
+Write (gated by `NUBASE_ALLOW_ADMIN_WRITE=true`; otherwise returns `{ success: false, error }` without calling the backend):
+
+- `gateway_issue_key({ name?, description?, expiresAt? })` — the full key is returned exactly once; treat it as a secret
+- `gateway_revoke_key({ id })`
+
+When `gateway_issue_key` returns a full key, never write it to Memory, generated code, or docs.
 
 Use AI Gateway for:
 

package/skills/nubase/references/auth-storage.md

@@ -2,6 +2,26 @@
 
 Use this reference when implementing Nubase Auth, users, sessions, JWTs, Supabase-style `/auth/v1`, object storage, buckets, signed URLs, `/storage/v1`, uploads, downloads, or file metadata.
 
+## Admin Ops Tools
+
+These tools run against admin endpoints and require the project key to carry `service_role`.
+
+Read (always available):
+
+- `auth_list_users({ page?, perPage?, keyword? })`
+- `storage_list_buckets({ search?, limit?, offset? })`
+
+Write (gated by `NUBASE_ALLOW_ADMIN_WRITE=true`; otherwise they return `{ success: false, error }` without calling the backend):
+
+- `auth_create_user({ email, password?, phone?, role? })`
+- `auth_delete_user({ userId, softDelete? })`
+- `storage_create_bucket({ name, public?, fileSizeLimit? })`
+- `storage_delete_bucket({ bucketId })`
+
+Prefer the read tools for inspection. Before any write tool, confirm the user asked for it; bucket and user deletion are destructive and need explicit confirmation.
+
+> Nubase has no serverless/edge-function runtime, so there are no function-deploy tools.
+
 ## Auth
 
 Auth base path:
@@ -20,6 +40,39 @@ Use Auth for:
 
 Generated frontend apps should use anon/authenticated keys plus user JWTs. Service-role keys must stay server-side or inside trusted local agent tooling.
 
+### Worked Example: signup → login → current user
+
+```http
+POST /auth/v1/signup
+apikey: <anon key>
+Content-Type: application/json
+
+{ "email": "ada@example.com", "password": "s3cret-pass" }
+```
+
+```http
+POST /auth/v1/token?grant_type=password
+apikey: <anon key>
+Content-Type: application/json
+
+{ "email": "ada@example.com", "password": "s3cret-pass" }
+```
+
+Response carries the JWT the app stores and replays on every user-scoped request:
+
+```json
+{ "access_token": "<JWT>", "token_type": "bearer", "expires_in": 3600,
+  "refresh_token": "<refresh>", "user": { "id": "f3a...07", "email": "ada@example.com" } }
+```
+
+```http
+GET /auth/v1/user
+apikey: <anon key>
+Authorization: Bearer <JWT>
+```
+
+Refresh with `POST /auth/v1/token?grant_type=refresh_token` and body `{ "refresh_token": "<refresh>" }`.
+
 When implementing auth:
 
 1. Keep API base configurable.
@@ -44,6 +97,42 @@ Use Storage for:
 - signed URLs
 - resumable uploads when supported by the app flow
 
+### Worked Example: private upload via signed URL
+
+```text
+storage_create_bucket({ "name": "avatars", "public": false })   # gated by NUBASE_ALLOW_ADMIN_WRITE
+```
+
+Ask the backend for a one-time signed upload URL, then PUT the bytes to it:
+
+```http
+POST /storage/v1/object/upload/sign/avatars/f3a...07/photo.png
+apikey: <anon or authenticated key>
+Authorization: Bearer <user JWT>
+```
+
+```json
+{ "signedUrl": "/storage/v1/object/upload/sign/avatars/...?token=<token>" }
+```
+
+```http
+PUT <signedUrl>
+Content-Type: image/png
+
+<binary file bytes>
+```
+
+Serve it back later with a short-lived signed download URL, and record the path in an app table:
+
+```http
+POST /storage/v1/object/sign/avatars/f3a...07/photo.png    Body: { "expiresIn": 3600 }
+```
+
+```text
+# then persist the reference
+POST /rest/v1/profiles   Body: { "avatar_path": "avatars/f3a...07/photo.png" }
+```
+
 When generating file flows:
 
 1. Validate file size and MIME type.
@@ -52,6 +141,4 @@ When generating file flows:
 4. Avoid service_role in browser uploads.
 5. Store file references in app tables through `/rest/v1` when needed.
 
-## Supabase Compatibility
-
-Say Supabase-style Auth/Storage or Supabase-compatible subset. Do not assume every Supabase SDK behavior exists unless the project has compatibility tests for it.
+> `/auth/v1` and `/storage/v1` are Supabase-style subsets; don't assume every Supabase SDK behavior exists without a compatibility test.