The rehearsal pattern rolls back by raising, so the command always exits
1 and writes to stderr on both the pass and the fail path. The previous
wording ("once the rehearsal output looks correct") read as if success
were normal output, which invites treating the expected non-zero exit as
a failure and retrying.
Add a callout plus a table mapping the two stderr messages to their
meaning, note the --json shape, and key the apply step off the
"rehearsal ok:" message instead of "output looks correct".
db query rejects BEGIN/COMMIT/ROLLBACK/SAVEPOINT with 'Transaction control
statements are not allowed.' but the query reference never mentioned it,
leaving no supported path for a guarded dry-run/restore rehearsal.
Add a Restrictions section to references/database/query.md that documents
the rejection (mirroring the migrations.md wording) and a single-statement
DO $$ ... $$ rehearsal example that mutates, validates, and ends with
RAISE EXCEPTION so PostgreSQL rolls the statement back.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Move --language under Optional flags with an explicit bold note that
it is required when --component sdk (it was listed under Required,
contradicting its own conditional qualifier).
- Write '--component skills' in full in the debug skill so the flag
binding is unambiguous.
- Generalize the insforge skill's example to show the type/component
enums instead of a fixed 'bug/sdk' classification agents would copy
verbatim for every situation.
- Narrow the redaction claim to the actual pattern coverage (public
IPv4, home-directory usernames — not all IPs/usernames) in both
skills that state it.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Companion to InsForge/CLI#206, which adds `insforge feedback` for
reporting InsForge-side hurdles (bug | feature-request | friction,
classified by toolkit component). Three skills now route agents to it:
- insforge-cli: core-rule reflex ("hit an InsForge-side hurdle → file
feedback → continue with a workaround"), routing-table row, and a
Feedback section with the situation→type mapping and full flag
reference.
- insforge (app/SDK): Important Notes bullet — SDK/backend/docs
misbehaving during app work → file with --component sdk --language,
never for the user's own app code.
- insforge-debug: "When the Root Cause Is InsForge Itself" section —
file while diagnostic evidence (failing command, log output,
workaround) is in hand; never block the user's task on the report.
Merge order: publish the CLI release first, then merge this — skills
install from this repo's default branch at runtime, so merging first
would document a command agents don't have yet.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Live ChatGPT session scaffolded an app with placeholder credentials
instead of logging in and creating a project first. Make the order
explicit: login -> create/link -> build with real values.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GcszudKMZBSm5RMP14h7fu
Live ChatGPT-app testing revealed two gaps:
- Harnesses that only return output on process exit (and kill at ~45s)
never show a single blocking `login --device` run's link. Teach the
two-step pattern: timeout-bounded first run to capture the link,
relay, rerun to resume the same pending code and complete.
- Workspaces with a network-domain allowlist need api.insforge.dev
added; teach agents to relay that instruction.
Also addresses review comments: --json on the SKILL.md inline command,
'hangs forever' -> waits until callback timeout, language tag on the
output fence.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GcszudKMZBSm5RMP14h7fu
Replaces the paste-back (--no-browser/--callback-url) guidance per
Tony's call — device flow only: agent runs `login --device`, relays
the pre-filled link + code, user clicks Authorize, CLI polls to
completion; rerun resumes the same pending code after sandbox timeouts.
Retrieval-tested: an agent given only this doc chose the right command,
relayed the link, handled the killed-process resume, and knew no
paste-back is needed.
Companion to InsForge/CLI#199 + insforge-cloud-backend#733; requires
the CLI release that ships --device.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GcszudKMZBSm5RMP14h7fu
Companion to InsForge/CLI#198. In sandboxes like the ChatGPT app the
browser cannot reach the CLI's loopback callback, so browser login hangs;
the new two-step flow prints the auth URL, the user pastes back the
redirect URL, and the CLI redeems it.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GcszudKMZBSm5RMP14h7fu
Codex's bundled skill-creator spec (references/openai_yaml.md) requires
default_prompt to reference the skill explicitly as $skill-name. Also
document the interface field set and constraints in CONTRIBUTING.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QT8v1kqCZYreDZwy6wfzJH
Addresses John-bot re-review on #117: interface.short_description is
constrained to 25-64 chars by the Codex skill-interface spec; all four
were 94-134 chars. Also adds the recommended per-skill default_prompt,
mirroring defaultPrompt in .codex-plugin/plugin.json.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QT8v1kqCZYreDZwy6wfzJH
OpenAI's plugin submission portal rejects SKILL.md files with a metadata
frontmatter block ('metadata does not configure the skill interface').
Drop the informational metadata blocks and add per-skill
agents/openai.yaml with the supported interface fields.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QT8v1kqCZYreDZwy6wfzJH
Address PR review feedback on the token-refresh examples:
- Clerk and Better Auth hooks now drop the previous user's token and set
isReady=false when the signed-in user changes (A -> B) before the async
token fetch, so no request goes out authenticated as the old user while
the new token is in flight.
- clerk.md: add an SDK version note (two-arg setAccessToken / AuthChangeEvent
require >= 1.4.4; 1.3.x drops the second arg; < 1.3.0 uses the legacy
fallback), matching better-auth.md.
- clerk.md: align the summary bullet with the two-arg setAccessToken form.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Per review: remove the standalone ⚠️ warning block; the $INSFORGE_USER_API_KEY
var form already mirrors the existing $EMAIL/$PASSWORD CI convention, which
carries no per-command security note. Keeps the login doc consistent in tone.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Review (jwfing + greptile): the recommended headless/agent/CI invocation
put the raw uak_ inline, which leaks a full-access credential into shell
history, ps/proc, and CI logs. Show it sourced from a secret-store shell
variable ("$INSFORGE_USER_API_KEY") instead, with an explicit caution.
Note: this is a user-set shell variable, not a CLI-read env var — the CLI's
login reads only the --user-api-key flag (verified), so we don't claim
native env support.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The CLI now supports `login --user-api-key uak_...` — direct bearer auth with
no browser and no token exchange (the recommended non-interactive path for
agents/CI). Update the login reference (options, methods, credential storage,
examples) and the Connection Setup guidance to cover it.
Also correct the credential-storage note: a user-API-key session stores
`user_api_key`, not `access_token`/`refresh_token`, and isn't refreshed.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Examples now destructure { data, error } and use concrete columns (not
select('*')), matching the file's own Important Notes conventions.
- Add a write-path (.insert) example; use env-var placeholders like Setup.
- State public is the default explicitly; note custom schemas are auto-exposed
on v2.2.3+ backends but require explicit GRANTs (exposure != access).
- Add that InsForge-internal schemas (auth/storage/system/payments/...) are
never exposed and must not be targeted; accurate PGRST106 message.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds a "Selecting a Schema" section covering client.database.schema('x'),
the createClient db:{schema} default, and the access model (schema is
routable but grants + RLS still gate access; old backends return PGRST106).
Pairs with the SDK .schema() support and v2.2.3 backend custom-schema exposure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Teach agents the memory workflow: run `memory list` at the start of
non-trivial tasks (Core Rules reflex), recall relevant titles before
designing or debugging, and record decisions/gotchas with
`memory remember` at the moment they happen.
- Core Rules bullet making recall a start-of-task reflex
- Command Routing row + terse `## Memory` section
- New references/memory.md: commands, workflow, kinds taxonomy,
store/don't-store guidance, idempotency/scope/empty-recall notes
- Frontmatter description mentions agent memory; version 1.6.0 -> 1.7.0
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Resolves valid findings from the PR reviewers (jwfing, Cubic, CodeRabbit):
- marketplace.json: remove `version` from the plugin entry. Per the
official docs, setting `version` in both plugin.json and the marketplace
entry is an anti-pattern — plugin.json always wins silently, so a stale
marketplace version can mask the real one. plugin.json is now the single
source of truth.
- marketplace.json: drop duplicated author/homepage/license/keywords. With
`source: "./"` and strict mode (default), plugin.json is the authority for
plugin definition; duplicating these fields only adds drift risk. Trimmed
to name + source + catalog description.
- marketplace.json: remove top-level `metadata.version` — it's the catalog
version namespace, optional; omitting lets each git commit count as a new
marketplace version (simpler for a frequently-updated skills repo).
- README: the integrations intro implied every entry is a JWT/auth flow;
clarify that OKX x402 is a payment facilitator, not an auth provider.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The docs site is the most useful "learn more" target for someone
evaluating the plugin in the directory, vs the marketing homepage.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Prep for submission to the Claude community plugin directory:
- License: LICENSE is Apache 2.0 but all manifests declared MIT. Align
every declaration to Apache-2.0 (plugin.json, marketplace.json, the
four SKILL.md frontmatters, README, CONTRIBUTING, AGENTS).
- README integrations summary: add Better Auth and OKX x402 (both shipped
but previously undocumented).
- README structure tree: rewrite insforge-cli / insforge-debug /
insforge-integrations subtrees to match the real flat references/*.md
layout instead of the stale per-provider SKILL.md dirs.
- marketplace.json metadata version 1.0.0 -> 1.2.0 to match the plugin.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds .claude-plugin/marketplace.json so the repo can be added as a
Claude Code plugin marketplace via `/plugin marketplace add
InsForge/insforge-skills` and installed with `/plugin install insforge`.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Correct the `--json` description for `billing upgrade`/`manage`: it prints a
JSON object ({ checkoutUrl, sessionId } / { portalUrl }) and suppresses the
browser open — not a bare URL string.
- Add the headless/CI `--json` note to `billing manage` (it was only on upgrade).
- List the full plan enum (free | starter | pro | team | enterprise) to match
the CLI help.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds usage docs for the commands shipped in InsForge/CLI#176:
- billing: history, cycles, upgrade <plan> (Stripe checkout, opens browser),
manage (Stripe customer portal). Reframes the section from "read-only" since
the CLI now performs checkout, and drops the "go to the dashboard" note.
- projects transfer <targetOrgId> (requires explicit --project; guarded).
- Routing-table rows updated; skill version 1.7.0 -> 1.8.0.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Routing table: drop the non-existent "pause" from the project-lifecycle row
(only `restore` ships), and list all six backups operations instead of three.
- projects delete: stop advising `-y`; emphasize it's a guarded, human-in-the-
loop op and the target id must be confirmed.
- backups create: clarify `--name` is optional (1–64 chars when provided).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds usage instructions for the new CLI commands shipped in InsForge/CLI#175:
projects lifecycle (get/update/restore/update-version/upgrade-instance/delete),
billing status/credits, org usage, orgs + members management, project backups,
secrets rotate, and storage s3-keys.
- New routing-table rows and dedicated sections (Organizations and Members,
Billing and Usage, Backups).
- Notes the org-resolution order, the latest-only semantics of update-version,
the xl instance ceiling, and the show-once nature of rotated keys / S3 secrets.
- Bumps skill version 1.6.0 -> 1.7.0.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
CarmenDou