Add a dedicated `## Availability` section to references/posthog.md and
expand the SKILL.md callout to a three-line block (feature + 404
failure mode + supported frameworks), matching the structure used for
payments. Tells agents what to do when the rollout hasn't reached the
project, and warns against working around the gap by pulling a phc_
key from a separate PostHog account.
Address review feedback: replace bare `insforge ...` with
`npx @insforge/cli ...` per the skill's "no global install" rule.
Title also normalized to `# npx @insforge/cli posthog setup` to match
other reference files (login.md, db-query.md, payments.md, etc.).
Drop the Related link pointing to insforge-integrations/posthog.md —
that file doesn't exist on main.
Adds a new "Analytics Integration" command section to the InsForge CLI
skill, with a dedicated reference covering the templated SDK install
flow: framework auto-detection, per-framework templates (Next.js App/
Pages Router, Vite + React, SvelteKit, Astro), env var writes, and
the layout.tsx hand-off note.
Bumps insforge-cli skill to 1.4.0.
Templates moved BA's tables to a dedicated `better_auth` schema
(insforge-templates#28). The doc was still teaching the old
public+REVOKE model; sync it.
Removed:
- Entire "Lock down PostgREST exposure (REQUIRED)" section (15 lines).
- "DATABASE_URL must keep superuser-grade privileges" callout — no
more REVOKE means no risk of a tightened DATABASE_URL silently
breaking sign-up.
- Organization plugin REVOKE block (5-line SQL + verify curl text).
- Plugin REVOKE template table — every plugin's tables inherit
`search_path=better_auth` automatically.
- Two Common Mistakes rows: "Skipping the REVOKE block" and
"Connecting BA as anon/authenticated after REVOKE" — both no
longer applicable.
Replaced with:
- Three-line schema-layout intro at the top of the guide showing
auth.* / better_auth.* / public.* ownership.
- "Schema setup + first migrate" subsection with `CREATE SCHEMA`
one-liner + a callout explaining why this is sufficient (PostgREST
exposes only `public` by default; dashboard reaches `better_auth`
through the admin route's postgres superuser pool).
- New `lib/auth.ts` example with `pool.on('connect')` setting
`search_path TO better_auth, public` — the canonical pg method
per BA's own docs since pg.Pool doesn't take a schema option.
- New Common Mistakes rows: forgetting `CREATE SCHEMA` before
migrate; FK'ing without schema qualification.
Updated:
- Manual-integration numbered workflow: drop the REVOKE step,
insert the CREATE SCHEMA step.
- FK example in the database-setup section: `REFERENCES public."user"(id)`
→ `REFERENCES better_auth."user"(id)`.
- "FK to BA users" section: prescribed FK is now `better_auth.user(id)`
(not `public.user(id)`).
- Plugin section's "rule of thumb": `\dt better_auth.*` (not `public.*`).
- All REVOKE-template SQL in plugin sections — gone.
Net change: 96 lines edited (48 insertions, 48 deletions). Word count
4260 → 4482 (+5%) because the explanatory schema-layout + new Common
Mistakes rows are slightly longer than the dropped sections; acceptable
for the clarity gain.
Verified end-to-end against current insforge main (v2.1.0) via
insforge-templates#28's branch — see that PR for the test matrix.
Ran the writing-skills TDD methodology against the BA integration guide:
dispatched a baseline subagent to do the integration with no doc access
(RED), then a second subagent reading the doc (GREEN). Compared their
outputs to identify what the doc teaches well vs where it has gaps.
The doc PASSED retrieval testing — the GREEN agent produced correct
bridge route, REVOKE matrix, and requesting_user_id() helper just by
reading the relevant sections. But three real issues surfaced:
1. Hono bridge example contradicted the Next bridge on PII. The Next
route's comment says "Don't add email or other PII"; the Hono one
inlined `email: session.user.email` 400 lines later. GREEN agent
flagged this as an internal contradiction. Removed the email claim,
added a back-reference to the Next route's no-PII comment, and
added the same `Cache-Control: no-store` header for parity.
2. The "DATABASE_URL must keep superuser-grade privileges" warning was
buried in the Common Mistakes table near the bottom. Promoted it
into a callout immediately under the REVOKE block, where the foot-
gun actually fires (a user who tightens DATABASE_URL to the
`authenticated` role after the REVOKE silently breaks BA sign-up).
3. The doc taught `requireEnv()` as the canonical pattern at lines
60-66 but used `process.env.X!` 12 times after on the SERVER side
— internal inconsistency a junior copy-paster would inherit.
Standardized server-side reads on `requireEnv`. Kept `!` for
`NEXT_PUBLIC_*` (those are bundler-inlined; a module-load check
would just fire in the browser anyway) and added a one-line
comment near the requireEnv definition explaining the asymmetry.
Also tightened `skills/insforge-integrations/SKILL.md` description:
dropped the workflow-summary tail ("Covers provider-specific dashboard
setup, client/server code…") since per writing-skills CSO guidance, a
description that summarizes the body trains Claude to read the
description and skip the actual content. The description now states
only when to use the skill.
The Vite/React skeleton was demonstrating the same Vite-proxy +
Origin-rewrite pattern that's already documented in prose with full
code blocks (the "Vite / React-only setups" section, ~109 lines
including a complete vite.config.ts and Hono bridge route).
Same drift logic that retired examples/better-auth-nextjs: no
CLI/CI keeps the example accurate, every @insforge/sdk or BA bump
risks a stale snippet. The doc IS the canonical reference.
If a real "clone-and-run" Vite story becomes worth the maintenance,
ship it through the CLI: a `vite` base template + the existing
better-auth overlay, same model as nextjs.
PR #44 is now 2 files: the SKILL.md edit and the integration guide.
The Next skeleton was duplicating what `insforge create --auth
better-auth` (CLI #98) and the templates repo's auth-providers/
better-auth/ overlay produce. We just had drift between the two
copies — the project_admin REVOKE fix had to land twice — so the
duplication is real maintenance cost.
Drop the Next skeleton entirely; point the doc at the CLI command
instead. Vite/React skeleton stays — the CLI doesn't scaffold React
yet, so it's still the canonical reference for that pattern.
Reduces this PR from 33 files to 13.
The dashboard's record browser switched from /database/records (PostgREST
passthrough, runs as the project_admin Postgres role) to
/database/admin/tables/.../records (backend AdminRecordService → postgres
superuser pool). Studio inspection is now role-independent, so the
"REVOKE from project_admin only if you want full lockdown" caveat was
misleading — there's no trade-off, just REVOKE from it.
Updated the core REVOKE block, the Organization plugin block, and the
plugin REVOKE-template table.
Replaces the description with the canonical InsForge positioning:
"The backend platform for AI-native developers. A Postgres-based
backend with auth, storage, compute, hosting, and AI gateway. Built
for coding agents."
Updates keywords to match the surface area called out in the tagline
(postgres, auth, storage, compute, hosting, ai-gateway) and swaps
agent-native for ai-native / coding-agents to mirror the marketing copy.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reframes the plugin description so the InsForge value prop — agent-native
BaaS for agent-native builders — is the first thing a marketplace browser
sees, before the feature list. Adds agent-native and ai-agents keywords
to improve discoverability for builders searching the directory.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds .claude-plugin/plugin.json so this repo can be submitted to the
official Claude Code plugin marketplace
(anthropics/claude-plugins-official) via the in-app submission form at
claude.ai/settings/plugins/submit.
Also aligns the license field across the three SKILL.md files that
declared Apache-2.0 to MIT, matching the LICENSE file at the repo root
and avoiding inconsistency a marketplace reviewer would flag.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Clarify what end users see on Google's sign-in screen with shared keys
(insforge.dev) vs. custom credentials (insforge.app) and what the project
owner needs to do in each case to rebrand.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Backend defaults dropped to maxBranchedParentsPerOrg=3 and
maxBranchesPerParent=2 (theoretical cap 6 branches/org instead of 15).
Update the user-facing copy in branch.md to match.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Collapse five thin per-subcommand branch references (create, list, switch,
delete, when-to-use) into a single branch.md covering the decision guide
and lifecycle commands. Trim duplicated post-merge and reset-vs-delete
content from branch-merge.md and branch-reset.md, and update SKILL.md
links accordingly.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Critical correction. The published @insforge/sdk@1.2.6 does NOT
expose client.setAccessToken on the public client class — only on
TokenManager. Both example skeletons were calling client.setAccessToken
directly, which would throw "is not a function" at runtime. The CLI
scaffold was already correct (feature-detect helper); the standalone
example skeletons were not.
Verified by importing the published 1.2.6 SDK directly:
client.setAccessToken → undefined
client.getHttpClient().setAuthToken → function
client.realtime.tokenManager.setAccessToken → function
Changes:
- Both skeleton lib/insforge.ts files now use the same setBridgeToken
helper the CLI scaffold uses (feature-detects so it stays correct
when public method ships in 1.3.0)
- Skill doc Pattern A code block adopts the helper; the explanatory
note is rewritten to match reality (1.3.0 ships public method,
1.2.x needs dual-update)
- Sign-out section, Realtime section, and Common Mistakes table
entry all reference the helper instead of the non-existent
public method
- React skeleton README updated
Verified post-fix end-to-end on ba-sdk-test: Vite SPA signup → bridge
JWT → RLS-scoped INSERT all green with the corrected helper.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@insforge/sdk@1.3.0 doesn't exist on npm — the latest published
version is 1.2.6, which already includes the public setAccessToken
API the skeletons depend on. Both example skeletons' package.json
were failing npm install on the stale ^1.3.0 pin.
Also flips every "SDK ≥ 1.3.0" reference in the skill doc and
example READMEs to 1.2.6 so the version threshold matches reality.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Recommended Workflow section now leads with the four-line CLI flow
(link → install → setup → dev) and frames the rest of the doc as a
reference layer: what got scaffolded, why, and how to extend it.
Manual workflow stays as a one-paragraph callout for users who can't
or won't use the CLI, with each numbered step still anchored to its
own section below.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
If a user lands on this guide without BA already configured, give them
two paths: the InsForge CLI flag (one-shot) for users in our flow, or
better-auth/skills (the canonical BA scaffolder) for users coming from
outside. This skill covers the InsForge integration layer, not generic
Better Auth setup, so we shouldn't reinvent the BA scaffolder.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Tracks the parallel CLI rename: the underlying OSS endpoint surfaces
Fly machine lifecycle events (start/stop/exit/restart), not container
stdout/stderr. The new command name is honest about that.
`compute logs` will return as a separate command for actual container
stdout/stderr streaming when that feature lands.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Add `CREATE EXTENSION IF NOT EXISTS pgcrypto` before gen_random_uuid()
so the SQL block runs on a fresh DB. Idempotent on existing stacks.
- Validate the bridged token before piping it into setAccessToken so a
malformed bridge response throws cleanly instead of silently clearing
auth state.
- Narrow the React effect dep from session.data?.user to
session.data?.user?.id — avoids resetting the refresh interval if the
auth library returns a new user object instance with the same id.
- Pattern B: pass explicit { algorithm: 'HS256', expiresIn: '1h' } to
jwt.sign and drop the manual exp claim. Aligns with the bridge route
and the service-token mailer.
CodeRabbit also flagged HTML escaping in the email-template snippet.
Skipping that — production code should use react-email/mjml; for an
example demonstrating client.emails.send, a 7-line escape helper is
more noise than the snippet's worth.
Re-ran the 12-check Next.js e2e: signup → bridge → RLS isolation → REVOKE
→ sign-out, all green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
CarmenDou