Changelog

An application you can read, that CI keeps honest

examples/ held six guides: the commands that build the same Job Portal in six architectures. Guides are useful and they have one weakness, which is that a guide cannot be wrong in a way anyone notices. It describes commands, and when a command's behaviour changes the guide goes quietly out of date while still reading as authoritative.

examples/library is an application instead. Authors, books, and the loans that connect a book to whoever has it. Generated by Grit, checked in, and built, vetted and tested by this repository's CI on every push.

One file in it was written by hand: apps/api/internal/policies/loan.go, which says that a loan that has been returned is history and cannot be edited or deleted. Neither of the other two authorization layers can express that. The permission catalogue decides whether somebody may touch loans at all, and a librarian holding every permission still should not be able to quietly change the dates on a closed loan. --owned-by decides whether a row belongs to the caller, and the borrower does own it. The rule is about the state of the record, which is what a policy is for. The test beside it makes the requests and checks the answers, because that claim is either true of the running code or it is marketing.

What it checks that nothing else did

The Live workflow already proves that today's templates produce a working application. This proves something different: that an application generated at an earlier version still builds and passes its own tests against today's libraries. That is the question every existing user has, and a fresh scaffold cannot ask it, because it is never old.

One checked-in application and not six. Six copies would be six to keep green against a framework that releases most days, and the day they fell behind they would teach the wrong thing while looking authoritative. The guides stay correct a different way: the commands in them are checked against the real command tree on every push, and a renamed flag fails the docs build.

Traces, when you point them somewhere

Grit already answered "what is my server doing" better than most: Pulse profiles every request, the activity log records who did what, and every response carries an X-Request-ID that ties a log line to a request. All of that stops at the edge of the process.

A trace does not. When this API calls a payments service, which calls a ledger, a trace is the one artifact that shows the whole thing as a single timeline with the slow span highlighted. You cannot reconstruct that from three sets of logs with three different request ids, which is what everybody tries first.

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

That is the whole configuration, and it is OpenTelemetry's variable rather than one Grit invented. OTEL_SERVICE_NAME and OTEL_TRACES_SAMPLER_ARG work too. Anyone who has run a collector before already knows them; anyone who has not can paste a line from a vendor's quickstart and have it work.

Off until the endpoint is set, because a tracer with nowhere to send spans is a background goroutine and a growing buffer that pays for nothing. Everything is sampled in development and a tenth in production, because a developer looking for one request wants that request and not a tenth of it, and a trace per request at a thousand a second is a bill rather than a tool.

One id, not two

When a request is sampled, the request id becomes the trace id. A log line and a span that share an id are one search away from each other; two ids that do not match are two searches and a guess. X-Request-ID still goes out, so nothing that reads it breaks, and X-Trace-Id goes out beside it.

Four modules, not ten: the OTLP/HTTP exporter rather than both transports, and a hand-written Gin middleware rather than otelgin, because the span has to be named after the route pattern (/api/v1/widgets/:id, not one span per id) and carry this project's request id. Only a 5xx marks a span as an error: a 404 or a 422 is the API working, and a trace list where everything is red is one nobody reads.

Rules about one row

A Grit project could already answer two authorization questions. The route's middleware answers may this user touch widgets at all, from the permission catalogue. --owned-by scoping answers is this their row, from the owner column.

Neither can say anything conditional on the record itself. A post may be edited while it is a draft and not after it is published. An order may be approved by anyone except the person who raised it. Those were hand-written if statements at the top of a handler, which is where they stop being findable and start being forgotten in the second handler that needs them.

internal/policies is where they go now. A rule gets the actor and the row, and returns authz.Allow() or authz.Deny("..."). Three abilities are checked around every row the API loads: widgets.read before returning one, widgets.update before an update or a patch, and widgets.delete before a delete, so a rule can refuse a delete without refusing an edit.

The reason is the feature

A permission check can only say no, so a user who cannot do something is told that they cannot, and files a ticket. A denial here carries words, and they come back as the 403 body: this post was published on Tuesday, and published posts are edited through a revision. That is 403 and not the 404 ownership uses, deliberately: the caller is already allowed to see this row, so hiding it says nothing and withholds the reason, which is the thing the rule exists to give.

An ability with no rule allows

Deliberately, and it is the opposite of what a security layer usually wants. A gate is a narrowing: the route's permission has already said yes, and a rule decides whether this record is an exception. Failing closed would mean that delivering this to an existing project refused every write in it, which is not a safe default, it is an outage. So a rule is a restriction you add, never a permission you forget to grant.

grit upgrade adds the check to resources generated before this release, both halves in one pass: a project with forty resources would otherwise have to regenerate all forty to use one rule. The repaired service is byte-identical to a freshly generated one, comments included.

A runbook for the part of an upgrade that needs judgment

grit upgrade rewrites the project and will not touch a file you have edited since Grit wrote it. That protection is also the limit: what the new version would have changed in that file goes unapplied, and it was reported as one line of terminal output that scrolls away.

There is no mechanical answer to that, because the reason the file was skipped is that applying the change needs judgment about code you wrote. But a change that needs judgment is one a coding agent can carry out when it is told what the change is, where to look and how to check the result.

grit upgrade --plan writes UPGRADE-PLAN.md at your project root: which version you came from, every file left alone, the diff of what the new version does to it, and a command whose success means it worked. Paste the whole file into a coding agent, or work through it yourself.

Every entry is detect, change, verify. The third one is the point: an instruction with no verification step is one an agent will report as done whether or not it is. The command fits the file, because "the whole project builds" is slow enough that nobody runs it between edits, and a check nobody runs is not a check. A Go file gets gofmt and go build from its own module directory, a .tsx gets tsc --noEmit in its app, a compose file gets docker compose config.

The diff is what Grit would have written against what you have, and it is not a patch to apply blindly: your edits are in there for a reason, and the job is to carry the new behaviour into them rather than to replace one with the other. The file says so.

A generated resource now comes with its tests

grit generate resource wrote twelve files and no test. The only thing standing between a generator change and a broken resource was somebody scaffolding a project by hand and looking at it.

It writes a factory and four tests now. Not tests of the CRUD mechanics, which are the same code for every resource and already covered: tests of the wiring, which is what varies. That the route refuses an anonymous caller, because a resource injected into the wrong group is reachable by anyone and nothing else would notice. That a signed-in user without the permission gets a 403, which is the difference between a permission that is declared and one that is checked. That a created row survives the round trip through the model, the service, the handler and the serialiser. And that an unknown id is a 404 and not a 500, which is the most common shape of generated-handler bug.

The factory at internal/factory/<resource>.go is the one place that knows what a valid row looks like, so adding a required field is one edit rather than one per test. A belongs_to is deliberately left empty: the factory cannot know which parent you mean, and inserting one would make every test that touches the resource write rows in another table too. The doc comment says so and shows the override.

Run the same suite against Postgres

internal/testkit is the shared setup: a database, a config, a request client and the assertions. By default the database is SQLite in memory, which is fast and needs nothing installed, and is not what you deploy to. Postgres stores timestamps to microseconds and SQLite to nanoseconds, so a hash chain over a timestamp verifies locally and fails in production. JSONB, ILIKE and numeric precision all differ too.

docker compose up -d postgres
GRIT_TEST_DATABASE_URL=postgres://grit:grit@localhost:5432/grit go test ./...

Every call gets its own schema, created and dropped around the test, so they stay isolated and can run in parallel. Worth doing before a release even if you do not do it every day.

A failing assertion prints the body. "expected 200, got 422" sends you to add a print statement and run it again; the same line followed by the validation error is the answer.

What each route asks of a caller

grit routes was reading 108 of the 171 routes a fresh project registers, and it was calling /api/v1/auth/me public. Three separate faults, all of the same shape: each one produced a plausible answer rather than no answer.

A route with its guard written in front of it, which is how every permission is attached, matched nothing at all, so the 55 lines that name a permission were dropped. Authentication was detected by looking for .Use(middleware.Auth and the generated file writes .Use(middleware.APIKeyOrAuth(db, middleware.Auth(...))), so no group was ever recognised as protected and every authenticated route was reported public. And a path built from a constant came out as /api/"+APIVersion+"/health.

The parser does less guessing now: the group graph is built first and resolved afterwards, each group's middleware chain is accumulated rather than tracked as one running variable, and arguments are split with a paren-aware scanner instead of a pattern that assumed their shape. It reads the per-resource route files too, which is most of what a real project serves. 182 routes in a fresh project, against 108.

So grit routes has an ACCESS column, and so does /system/routes. v3.356.0 shipped that screen with a paragraph explaining why it could not have one: Gin's route table carries a route's last handler and nothing about the middleware in front of it. That was true about Gin and wrong about the problem. The answer is written in routes.go, so grit reads it there and generates internal/access/registry.go, which the screen and the MCP route tool both read.

There are four states, not two. A route the table does not cover reads unknown, never public: the reference, the profiler and the database browser register 125 routes this project's route files never saw, and calling those public would be the one wrong answer worth avoiding, because somebody reads this column as a security statement.

The table is rewritten by grit new, grit generate resource, grit remove and grit upgrade. Add a route by hand and grit doctor says so, which is the one case no command catches.

The route table, in the browser

grit routes has printed it in a terminal for a long time and remains the fuller answer, because the CLI parses routes.go and can report the middleware group and the permission each route wants. What nothing provided was a searchable version for somebody already in the admin, looking for the URL of an endpoint they are about to call.

/system/routes lists every registered route grouped by what it is about, filtered as you type, with a copy-as-curl on each row. The API's own endpoints come first and the mounted dashboards last: the reference, the profiler and the database browser are 130 of the 298 routes in a fresh project and they are somebody else's.

There is deliberately no access column. Gin's route table carries a route's last handler and nothing about the middleware in front of it, so the authorization level is not readable at runtime at all. A level guessed from the path would be wrong for /api/v1/auth/me and all six passkey endpoints, which sit under /auth/ and every one of them needs a signed-in user, and somebody would read that as a security statement. The page says so and points at the command that does know.

/llms-full.txt now orders its route listing the same way, since it was sorting the same 130 mounted routes to the top of the file.

The saga runs screen

v3.354.0 shipped the engine and no way to look at it. A run that goes stuck is one whose compensation failed past its attempts, so there is a charge, a reservation or a booking still standing that was supposed to be taken back, and the only way to find one was SQL against saga_runs. That means nobody finds one until a customer complains.

/system/sagas lists every run with its status, filtered by chips that carry the counts, and a banner at the top when anything is stuck. Opening a run shows its steps in order with the error that stopped each one, and a stuck run gets a Retry button: it resumes compensating from the step it stopped on, because the thing that could not be undone is still not undone.

Retry refuses a run that is not stuck, and says why. A running one needs no help and a finished one has nothing left to do, so retrying either would re-run work that already happened.

The status chips carry what each word means on hover, because compensated reads as a failure and is the opposite: a step failed and everything before it was undone, so the world is back where it started. See Sagas.

grit generate workflow: steps that finish or are undone

A transaction is the right tool when every write is in one database. It is no help when the steps are in four places: charge a card, reserve stock, book a courier, send the receipt. The card does not roll back when the courier refuses, and the process holding all of it in its head is exactly the thing that crashes, usually between the charge and the reservation.

Every step now gets a Do and an Undo. They run in order, and when one fails for good the completed ones are undone newest first. Where the run got to is a row in saga_runs, not a stack frame, so a process that dies resumes rather than losing the thread, and every replica runs a runner because a run is claimed before it is touched.

grit generate workflow Checkout --steps "charge,reserve_stock,book_courier,send_receipt"

Each generated step returns an error until you write it. A stub that returned nil would be a saga reporting success and doing nothing, and the first you would hear of it is a customer saying the parcel never came.

The parts that are easy to get wrong are the ones the engine takes a position on. r.IdempotencyKey() is stable across retries, because a crash between the charge and the record of it is not preventable and a provider that deduplicates on that key is what stops the second charge. What a step writes with r.Set survives even when that step then fails, because a charge id obtained just before a timeout is exactly what the refund needs. And a compensation that cannot complete leaves the run stuck rather than compensated: something happened that could not be taken back, and a status that reads as resolved would be a lie.

A step you cannot undo declares Undo: nil, which is legitimate and makes the ordering the design: anything after it that fails leaves it done. See Sagas. This is a different thing from workflows, which turn a status column into a state machine; most projects want both.

The upgrade machinery is on the site

The strongest thing this project does had no page. A scaffolder gives you code once and then watches it rot; this one keeps fixing the project it generated, and the only place that appeared was in changelog entries, which is to say nowhere a visitor looks.

Upgrading a project is the detail: the manifest that records a hash per generated file, the three answers it gives (unchanged, modified, untracked) and the three behaviours they lead to, the 53 repairs that rewrite the files you share with Grit by matching the exact text it wrote, and what travels on every upgrade rather than only at scaffold time.

Documentation only. Nothing in the framework changed.

The page also says the part that is easiest to miss: a warning from grit upgrade is the interesting half. Grit found code it did not write, so it did not touch it, and told you what the fix would have been and why.

The MCP server has ten tools and two modes

It had three, all of them read-only, and no way to say so structurally. It now has nine that answer questions and one that writes, and the default server does not contain the one that writes: grit mcp serve builds a map without it, so no token, no scope, no misconfigured client and no instruction hidden in a README can reach it. --mode write builds the one that has it.

The alternative, which is what most servers do, is to register everything and check a flag inside each handler. That works until somebody adds a tool and forgets the check, and the failure is silent and total: the tool simply works for everyone. Letting the mode decide what gets built removes the class of mistake.

The new tools are the ones an agent actually needs. grit_file_ownership reports which generated files are still exactly as Grit wrote them and which you have edited, which nothing else can answer and which decides both whether an upgrade will keep updating a file and where it will report a conflict. grit_list_permissions gives the real permission keys, so a guard is not written against one that matches nothing and fails silently. grit_list_resources finds what the generator made, by the marker it leaves rather than by guessing from filenames. grit_doctor returns the audit as data. grit_env_keys names the variables and whether .env sets them, and never returns a value from either file. grit_cli_reference reads the commands out of the running binary, so an agent proposes a flag that exists in the version you have.

grit_generate_resource is the write-mode tool, and it checks its arguments before anything runs: a name that is not a name, a field type this version does not have, or a shell metacharacter is an error the agent can read rather than a half-generated resource to clean up. See MCP Server.

llms.txt, for the framework and for the API you build with it

An agent pointed at Grit had to crawl 171 pages of rendered HTML or guess. gritframework.dev/llms.txt is the index instead: what Grit is, the one thing to understand about it, and every documentation page with its description, grouped by subject. gritframework.dev/llms-full.txt adds the working guide and the complete CLI reference, as one file.

Neither is written twice. The page list is the metadata the pages already use for their titles, the CLI reference is the catalogue /docs/cli renders, and the working guide is the file grit init writes into a project, so none of it can drift from the docs.

A scaffolded API serves its own pair. /llms.txt is the orientation an OpenAPI document does not carry: how versioning works, which header holds the token, what a response and an error look like, and the parameters every list endpoint takes. /llms-full.txt adds every route the router holds, grouped by what it is about, which is the one thing the spec cannot answer, because the spec documents the routes somebody wrote an override for and this is the router's own table.

Both are mounted behind the same condition as the API reference, since they describe the same surface: off in production unless API_DOCS_PUBLIC=true. The text lives in internal/llms and is yours to edit. See llms.txt.

/api/health answers in four states, and reports storage

Every component reported one boolean, and that boolean covered two opposite situations: Redis is down, and this deployment has no Redis. Nothing reading the response could tell them apart, so the admin page guessed, and guessed differently per component: Redis read ok === false ? down : ok ? ok : unknown, email read configured ? ok : unknown, and storage was not on the page at all.

Components now answer ok, degraded, off or unknown. Off is a dependency this deployment never asked for and unknown is a probe that could not find out, so neither lowers the overall status. Only degraded does, and that rule lives in one function rather than in a condition that named Redis and therefore quietly excluded the mailer and the object store.

Storage is reported, which is the gap that prompted this: an upload answering 503 came with a System Health page that had nothing to say, because no object store was configured in that environment at all.

A missing cache is the one probe that asks which environment it is in. REDIS_URL= turned it off on purpose, and that is off. Anything else means the API dialled Redis at boot, was refused, and carried on with caching, jobs and cron disabled: on a laptop that is still off, with a detail saying so, and in production it is degraded, because there it is an incident.

Anything else reports itself through health.Register(name, probe), from a plugin or from your own main.go, and appears beside the framework's own components under the same rule. A probe that panics is reported as unknown rather than taking the endpoint down with it. See Health checks.

The ok field is still sent, and is exactly state === "ok", so load balancers, uptime probes and the desktop heartbeat are unaffected. grit upgrade rewrites the handler of a project that still has the one Grit wrote, and reports a handler you have edited rather than overwriting it.

A profile picture is cropped before it is uploaded

A profile picture is square and the pictures people have are not. Picking a file uploaded it as it came, and the browser did the cropping on display, where object-cover takes the middle: a photo of two people became a photo of somebody's shoulder, and the only fix was to go and edit the file.

Both places that change a picture, the account screen and the profile page, now open a cropper first. The whole picture stays visible with a round selection over it, which moves and resizes, and what is uploaded is a square cut from exactly that selection, scaled to 512 pixels. A PNG stays a PNG, because flattening transparency to JPEG turns it black.

Arrow keys move the selection and plus and minus resize it, so the cropper works without a pointer. A cropper that only works by dragging is one a keyboard user cannot use at all, and the alternative there is no picture.

No cropping library: the whole thing is a scale and an offset applied twice, once to the preview and once to the canvas, and those two agreeing is the only hard part. Verified against a running admin, which is how the one real bug was found: Tailwind preflight's img { max-width: 100% } was shrinking the picture below the size everything else was measured in.

The audit tables have a read side

Three handlers read them: the request log, the semantic activity feed, and the OCSF export a SIEM collector polls. Each built its own query, and the whitelists that decide which columns a client may sort or filter by were written three times. They are services.ActivityService now. Writing to those tables stays with the LogX functions: somebody logging an action should not have to build a service for it.

The severity chips above the activity dashboard dropped the error from their count, so a database that was down drew the same zeros as a quiet day. It is reported now. The window is still chosen by the endpoint, because 24 hours is that endpoint's promise; what the service owns is that the cutoff is bound as a value rather than written as NOW() - INTERVAL, which is Postgres-only syntax and used to return zeros on every SQLite project.

The export's cursor is in one place too: since is a wall-clock floor for a collector's first poll, after is the exact position for every poll after that, and an after that no longer exists falls through to since rather than erroring, so a collector that lost its place still makes progress instead of wedging.

All three handlers travel on upgrade now. Twenty of the framework's handlers have had their queries moved; twelve files still hold 26 sites between them, three of which only hand the connection to a service rather than building a query.

The auth handlers stop reading the users table themselves

Four handlers, ten queries: the provider callback, the password reset, the verification resend and the recovery contacts. Each one was a read or a write of a single account, and each one is now a call to a service.

Reads during a sign-in go through AuthService, which is where Login already gets them, so an unknown address is answered the same way whichever endpoint was asked. Writes to an account go through UserService, which owns them. The recovery handler builds its own, because it holds no AuthService and a lookup should not work or panic depending on how the handler was wired.

A provider sign-in for an address nobody has registered now inserts through services.CreateUser, so two callbacks for one new address in the same instant are settled by the unique index rather than by which read finished first. That is the third endpoint to pick this up: registration and the SSO provisioning path were the others.

All four travel on upgrade now, and recovery.go came out of a Go string literal into internal/scaffold/templates/, verified byte-for-byte. The repair that hardens an older OAuth handler still writes what that handler can compile, so its test runs against a fixture of the file it actually meets rather than against the current template.

One lockout, not one per factor

A wrong password and a wrong two-factor code are counted against the same account, and each had its own copy of the three writes that do it: count, read the count back, lock past the threshold. Written months apart, with the same trap in both, which is that the count a request arrived with is already stale and the decision has to be made from what the database holds.

They are AuthService.CountLoginFailure and AuthService.LockAccount now, beside the ClearLoginFailures that was already there, and both handlers call them. The threshold and the window stay with each caller, because one reads this project's configuration and the other reads the two-factor constants. The admin unlock went to UserService: it is an action on a user rather than part of signing in.

The offline sync protocol has a row store

services.SyncService takes the destination the handler built rather than a model, because a project syncs whatever it registered and the type is the registry's. The reflection stays in the handler with the protocol; what moved is the part that is a decision about data: that a pull is keyset-paginated on (updated_at, id) so rows sharing a timestamp are not lost at a page boundary, that it reads soft-deleted rows because those are the tombstones a client needs, and that a save from a phone touches neither associations nor created_at.

Both handlers travel on upgrade now, so an existing project gets the single lockout rather than keeping its own copy of it.

A public form stops losing submissions when two arrive at once

Every submission to a shared form bumped a counter by writing share.SubmissionCount + 1 from the row the request had read. Two visitors submitting in the same moment both wrote the same number, so the count lost one of them. A public form is exactly where that happens: nobody is taking turns. The increment is in SQL now.

Uploads list through paginate, and their stats report failures

The files list clamped the page and did the offset arithmetic itself, which is why it answered none of the search, sort or ?counts= parameters the rest of the API does. It goes through paginate like every other list, with the same response envelope it already returned.

Two of the three queries behind the storage stats discarded their errors, so a database that was down drew a page of zeros: indistinguishable from an empty bucket. All three report now.

Three more services

FormShareService, UploadService and WebhookEventService. The webhook one carries the claim that decides which of two redeliveries of one event may run its handler, and that claim has tests for the first time: one for a failed event taken over once, one for a pending event left alone until the process holding it must be gone.

Uploads keep their scoping in the handler, because who may see everybody's files reads the request; the handler says whose, and the service scopes every query by it.

All three handlers now travel on upgrade. Public form sharing was written once at scaffold time, so the lost-submission fix would have reached new projects only. 1,378 more lines came out of Go string literals into internal/scaffold/templates/, verified byte-for-byte.

The access-review list was 4n queries, and dropped every error

Drawing the recertification campaigns ran four counts per campaign, so a year of monthly reviews was forty-nine queries for one page. Each of those counts discarded its error, which meant a count that failed drew a campaign as having no items at all. In an access review that reads as nothing left to certify, which is the one wrong answer that matters.

It is two queries now, whatever the number of campaigns, and a failure is reported. The total is the sum of every decision rather than a fourth count, so a decision a later release adds is included instead of silently missing from the total.

The list also ordered by created_at alone, and two campaigns opened in the same second came back in whichever order the database felt like, which an operator sees as a list that reorders itself between refreshes. It breaks the tie on the id, which Grit issues in time order.

Feature flags have a service, and exposures count people

The flag rows and their exposure counts are services.FeatureFlagService. The engine in internal/flags still decides what a flag answers for a given user and when its cache is stale, which is the one thing a service cannot know. The exposure query counts distinct users, as it did before, and now has a test that spends forty checks by one person to prove it.

Both handlers moved into the framework-owned set, so an upgrade delivers them and the 4n list stops being something only new projects escape. Four more files came out of Go string literals into internal/scaffold/templates/.

SSO and SAML run no queries of their own

The connection and identity tables are now services.SSOService, and both sign-in flows read accounts through UserService. The handlers keep what they are for: which domains a customer's identity provider may vouch for, what a refused sign-in says, which fields an admin request may set.

The group-role mapping is the part worth reading. Its transaction was a second copy of the one behind the admin's role picker, written months apart, and both had to agree about the legacy users.role column, because that column is what the JWT carries: a token that disagrees with the grants is worse than either being wrong. One implementation now, in RoleService.ReplaceUserRoles, which the SSO mapping calls.

A just-in-time provisioned account goes through services.CreateUser, so two assertions for one new address in the same instant are decided by the unique index rather than by which read finished first.

The connection store has its own tests for the first time: one domain claimed twice, a disabled connection still answering a callback, a SAML assertion arriving for a connection switched to OIDC, and the subject match a returning sign-in depends on. The SSO service also moved out of a Go string literal into internal/scaffold/templates/, verified byte-for-byte.

Two-factor has a service, and the races live in one place

internal/handlers/totp.go was 870 lines and thirty-five queries, the largest handler Grit ships. They are now services.TwoFactorService: the config a user enrols, the pending token a half-finished sign-in carries, and the devices allowed to skip the prompt.

Three of those methods are the reason this one mattered most. A TOTP code is valid for its whole time step, a backup code sits in a list, and a pending token is a row anybody holding it can present: each has to be spent by one request and not by a second one arriving in the same instant. That is a compare-and-set, and whether this request won is a question only the write can answer, which makes it the service's and not a handler's. The guarantees were already there; they were spread across three handler methods, and nothing tested them. They have tests now, each one playing the second request.

The lockout decision reads the failure count the database holds rather than the one the request arrived with, which is what several wrong codes in flight at once needed all along. The "trusted devices" count on the status endpoint had its error dropped, so a database that was down read as a user with no trusted devices; it is reported now. User lookups go through AuthService, which this handler already held.

An upgrade delivers the handler and the service together, as it already delivered this handler: one without the other would not compile. 852 lines also came out of a Go string literal into internal/scaffold/templates/, verified byte-for-byte against the previous release.

The roles API has a service

Seventeen queries out of internal/handlers/role.go and into services.RoleService. The handler still decides who may ask: only an ADMIN changes a built-in role, a role hands out no more than its author holds, an unknown permission key is a 400. What a role is, how its holders are counted and which writes have to land together is the service's, and a job or a console command reaches the same rules.

Two things the move turned up. The holder count behind the roles list had its error dropped, so a failed count drew every role as held by nobody; it is reported now. And assigning roles counted the ids, then fetched the rows, where one read answers both.

"Role is assigned to N user(s)" now counts users

A role reaches a user two ways: the user_roles join table, and the legacy users.role string the admin's user form writes. The delete guard counted rows, so somebody holding a role both ways counted twice, and the number in that message is what an operator is told to go and reassign before they can delete the role. It counts people now, and a deleted account is not one of them, so a role held only by deleted users can be removed.

role.go travels on upgrade, and is a file again

The handler and its test were written once, when the project was scaffolded, so a fix to either reached new projects and no existing one. They are framework-owned now, which means an upgrade delivers them, manifest-guarded as always: a role.go you have edited is reported as a conflict and kept.

Both also moved out of Go string literals into internal/scaffold/templates/, 591 lines of Go that a parser can now see. Verified byte-for-byte: the same project name scaffolded with both binaries produced identical files.

The extractor that moves a batch of templates now refuses to overwrite a template that exists. Re-running it over a moved batch used to be a no-op, and stopped being one the moment templates carried repair markers: it wrote the stripped output back and deleted every marker in the file.

The user endpoints have a service

internal/handlers/user.go ran fourteen queries of its own: the row behind an id, the row behind a session, the address check, the two writes an update makes, the soft deletes, and the paging config for the list. Every generated resource was moved onto its service in v3.224, so the handler a developer is most likely to copy from was the one breaking the rule.

They are now services.UserService: List, GetByID, Update, Delete, EmailTakenByAnother and SyncRoleAssignment. The handler reads the request, calls one of them and writes the answer. A job that deactivates accounts and a console command that fixes a role now go through the same rules as the HTTP route, which is the point: a rule written in a handler applies to the handler.

The role assignment and the user row still share one transaction, and that claim now has a test: it forces the second write to fail and checks the promotion did not survive. Nothing tested it before, and it is the kind of thing that only shows up as a user who kept the permissions of a role they were never given.

handlers/user.go travels on upgrade

It used to be written once, when the project was scaffolded. A fix to it reached new projects and no existing one, which is why the hand-rolled users list that read none of the admin's filters had to be repaired into place with text substitutions, three separate times.

It is now one of the framework-owned files, so an upgrade delivers it. That delivery is manifest-guarded: a user.go you have edited is reported as a conflict and kept exactly as it is, and the repairs are still there for it. Verified both ways, on a copy of a real project: pristine takes the new handler and its service, edited keeps its edit and still builds.

handlers/user_role_sync_test.go is removed on upgrade, because its two cases moved to services/user_test.go beside the code they are about. Only when your handler no longer declares what it calls, and only when you have not edited the test yourself: either way you are told.

Sign-in runs no queries of its own

internal/handlers/auth.go read five things from the database by itself: the account behind an address, the account behind a refresh token, an enabled second factor, the row that records a half-finished sign-in, and the reset of the lockout counters. Every generated resource was moved onto its service in v3.224, and grit doctor reports a handler that queries, so the first file a developer opens was breaking the rule the generator enforces.

They are now five AuthService methods, and each one is a decision about data rather than about HTTP: which columns of a two-factor row are safe to load (the id and the method, never the secret, because a secret that cannot be decrypted would otherwise read as this account has no second factor), what an unknown address answers, when a failure count is cleared. The handler calls them and formats the answer.

An existing project gets the methods before the sign-in repair runs, which is the part that had to be built rather than noticed: grit upgrade rewrites an older Login to what the template says today, and what it says today calls h.AuthService.UserByEmail. Writing that into a project whose service has no such method is an upgrade that reports success and leaves a project that does not compile.

What an existing project gets: the five service methods, and, if its sign-in predates v3.286.0, a Login that calls them. An auth handler that already holds the current sign-in keeps its own queries, because internal/handlers/auth.go is a file developers edit and the upgrade changes it only where it still reads as Grit wrote it. It compiles and behaves the same either way.

The repair blocks are taken from the templates, not copied out of them

A repair needs the text the generator writes today, and it used to keep its own transcription: 229 lines of the auth handler in one constant, spliced with a second copy from another file. Editing the template without editing both copies left an upgraded project holding code the generator no longer writes, and nothing caught it, because the two halves are joined by a Go + that no search for the text can follow. That is how this release found two of them already out of step.

The templates now mark the parts a repair needs, the repair takes a slice of the one source, and the markers are stripped on the way out so no generated project sees them. Four blocks, no second copy. Proven by changing a string in the template alone and watching the repair tests follow it without being touched.

The templates are LF on every machine

v3.338.0 moved the handler templates out of Go string literals and into files. Files are subject to a thing string literals were not: git converts text on checkout, and this repository had no .gitattributes to stop it. A clone on Windows got all 29 templates with CRLF, the CLI embedded CRLF, and the repair constants that mirror those templates stopped matching them.

Confirmed by cloning the released tag: 29 of 29. It was invisible because the checks run on Linux, where no conversion happens, so all six workflows were green on a release that behaved differently on the machine it was written on. The same shape as v3.333, where the compose repairs had never once run on a Windows checkout.

.gitattributes now pins internal/scaffold/templates/** to eol=lf, and a test reads every embedded template back and fails on a CRLF, because an attributes file is easy to lose in a merge and the failure it prevents cannot be seen from Linux.

If you cloned at v3.338.0 on Windows, git pull then git add --renormalize . restores the templates; nothing in a generated project needs changing.

Templates as files, starting with the handlers

Nothing in this release changes a generated project. Every one of the 633 files a --triple --next scaffold produces is byte-for-byte what v3.337.1 produced. This is about the framework being maintainable by somebody other than its author.

internal/scaffold is 174,000 lines, and most of it is Go, TypeScript, CSS and YAML living inside Go string literals, with one file at 10,437 lines. An editor cannot highlight any of it, a parser cannot see it, and finding the template that produces a given file means grepping. A product review scored the maintainability of the framework itself 4 out of 10 for exactly this, and it is the reason a colour utility that compiled to nothing and a hook after an early return both shipped.

The 29 handler templates now live under internal/scaffold/templates/api/handlers/ as ordinary files, embedded with go:embed. api_files.go drops from 10,437 lines to 8,521. A test parses every Go template with go/parser, so a missing brace is now a unit-test failure naming the line (api/handlers/auth.go:524:47) in under a second, rather than a scaffold-and-build in CI.

What this does not do is type-check them. These templates import packages that exist only in a generated project, so the compiler cannot see them from here, and that stays the live suite's job. Syntax and findability are what moved, and syntax is where the bugs came from.

Two things that were tried and deliberately not shipped

Running gofmt over the templates looked like an obvious win and is wrong twice. The scaffolder already formats Go on the way out, so a generated project is formatted whatever the template looks like. And formatting a template means substituting a stand-in for {{MODULE}} first, which sorts to a different place in the import block than a real module path does: four handlers came out with their imports reordered. A tidy-up of the source was quietly changing what every project receives. The reasoning is recorded in the test file so the next person does not spend the afternoon rediscovering it.

The other is a note about verification. Comparing two scaffolded projects to prove nothing changed only works if they have the same name: the module path is part of the import block, and v3361b sorts after "time" while pilot3 sorts before it. Comparing differently named projects shows four false differences and hides real ones.

v3.337.0 was tagged with an empty commit: a git add that failed silently staged nothing, so that release carries no changes. Everything below is in this one. Nothing was wrong with v3.337.0 beyond its being identical to v3.336.1.

The docs now have to follow the rules the framework states

Every command the documentation shows has been checked against the real command tree for a long time: a renamed flag fails the build. The Go code on the same pages was checked against nothing, and it had drifted badly.

A product review found four things on the homepage that the agent skill tells an agent never to do: a handler running its own query, a float64 price, a swallowed bind error, and a hand-built error envelope with no code in it. The homepage is the page an agent reads before the skill, so it was teaching the wrong pattern from the opening screen.

There is now a check for it, with four narrow rules taken from what Grit already says in its README, its skill and its stability page. It found 49 violations across the site, not four, and all 49 are fixed: 29 money columns moved off float64, including an invoice Amount and a point-of-sale Price; five swallowed bind errors; nine handler queries.

The worst of them was not on the homepage. A lesson on building a public catalogue carried three samples labelled "(already generated)" that showed handlers building their own GORM queries. The generator stopped writing that shape at v3.224, around 110 releases ago, so the page was not teaching a bad habit: it was making a false claim about what the tool produces, and then telling the reader to add more of the same. It now shows what the generator writes, with the paginate.Config allowlist in the service where it lives, which is the half worth reading and was buried in a handler.

A page that needs to show what a rule forbids says so by name: docscheck:allow float-money with a reason on the same line. The Go language primer uses one, because float64 there is the subject being taught. A blanket skip-this-file switch would have been the easier design and would have stopped covering the pages that drifted most.

MySQL is supported, and the homepage said it was not

The connector has picked MySQL off the DSN prefix since v3.146, the live suite scaffolds an app and drives it over HTTP against MySQL 8 on every push, and the database section of the homepage carried a footnote saying there was no third dialector. Anyone evaluating Grit with MySQL in the building read that and left. It is now a provider card beside Postgres and SQLite.

Smaller things from the same review

• The themes heading said four and listed nine. A version badge in one graphic had been frozen at v3.23 since roughly release 23 of 450; it reads the same source as everything else now.
• The Wails desktop stack was a release train behind every other mode, on Gin 1.10 and GORM 1.25 while the rest was on 1.11 and 1.31. Raised.
• examples/ said "Example Projects" and held no code. It now says what it is, which is a set of build guides, and points at demo/ for an application you can actually clone and run.
• A compiled Python cache file had been committed to the docs folder.

The security scan is green again

A generated project's gosec run had eight findings, all of them from Grit's own recent work and none of them a real vulnerability: the template.CSS calls the email themes need (without them html/template writes ZgotmplZ and the mail arrives unstyled), the template.HTML that puts an already-escaped fragment into the layout shell, and the math/rand jitter that spreads cache expiry.

Each now carries a #nosec with the reasoning written out rather than a bare annotation, because an unexplained finding and a suppressed one look identical to the next person reading the file. Nothing behaves differently; the scan in your project's own CI passes again.

Scaling readiness, at the top of Observability

grit scale answered "what should I do next" from a terminal. The question people ask first is the other one: what is already handled here? The admin's Observability page now opens with all ten scaling stages and the state of each on this deployment, under the verdict.

Every line is measured off the running app rather than read from a list of features. A tick against Stage 4 means this deployment was observed keeping sessions in the database and uploads in object storage, with the driver named beside it. Stage 2 reports the cores it can see. Stage 9 reports the largest table, because that is the number that decides whether sharding is even a question, and the honest answer is almost always no.

The three measured stages go amber on the same constants the verdict uses, so the panel cannot show a green tick for the stage the verdict is calling out. Two things it will tell you about are the ones that are invisible until a second instance exists: STORAGE_DRIVER=local, which leaves uploads on one machine's disk, and SQLite, which makes every question after Stage 1 have the same answer.

A stage that is off reads "ready, not needed yet" rather than leaving a gap. That is the correct state for replicas and caching in almost every application, and a gap there looks like something missing when it is not. See Scaling.

A Grit app now says it is one

Nothing a Grit app served identified the framework, so a technology scanner could find Next.js, React and Tailwind and stop. Both frontend shapes now emit <meta name="generator" content="Grit">, the convention every static site generator and CMS uses for exactly this.

The name and not the version. Telling an unauthenticated visitor which release is running hands them that release's advisories, which is the same reason poweredByHeader is off in the Next config two files away and why the Go API still names nothing at all. One line in your own layout, so deleting it is the opt-out.

A post you could publish once and then never edit

Sentinel's firewall stepped aside for a richtext body at its public path and not at the /admin path the admin panel writes through. A body is inspected on the way in, so it is the writes that carry the markup: every PUT from the admin was answered 403 and logged as a critical threat, for a code block whose ../ reads as path traversal. Reported by Mark Cole Mukisa with the fix already in production (#90).

It was worse than the report: grit generate resource never touched the exclusion list at all, so every resource generated with a richtext field had the same fault at its own path. It now adds the resource when it emits one, and grit remove takes it back out. grit upgrade repairs a project already generated, finding its richtext resources by the sanitize:"html" tag on the models and reading their paths off the routes rather than guessing at a plural.

--public: the half that was missing

--public generated read-only endpoints behind an API key and stopped there. The hooks beside them still called the authenticated routes, and nothing in apps/web ever sent the publishable key the seeder had already written into its .env.local, so a storefront built the obvious way got 401s and the developer had to write the fetch layer by hand to find out why (#91).

There is now a read layer: apps/web/lib/<resource>-public.ts, calling the public routes with the key on every request, typed against the allowlist rather than the model, with the related and tree endpoints when the resource has them. Three more things that report found:

• Only archived_at hid a row. An admin turning active off left the product on sale. Every public read now goes through one scope, and where the model has a column that says whether a row may be seen, that scope uses it.
• Foreign keys were held back with the relation. Those are not the same thing, and a storefront could not link a product to its category from a response that had already agreed to return the product.
• Forty products called Emily Gardner. The faker gave every string a person's name and every whole number 1 to 100. It now takes the resource into account, and a price gets a price.

See The public surface.

Deploying where the platform sets the rules

From a Grit triple shipped to Laravel Cloud, running in production (#92):

• PORT is read before APP_PORT. Every platform that routes to a container injects it, and a deploy that binds the other one goes green with nothing answering.
• A cross-site warning at boot. On a platform whose domain is on the Public Suffix List, two apps of one project are already cross-site, so the browser never sends the SameSite=Lax auth cookies and sign-in returns 200 followed by 401s with nothing logged. It now says so, and says what to do about it.
• AWS_BUCKET and AWS_ENDPOINT_URL are accepted where S3_BUCKET and S3_ENDPOINT were, so attaching a managed bucket needs nothing configured.
• A separate upload host in the CSP. A bucket that serves reads from its own CDN and signs writes for the underlying S3 endpoint had every upload signed by the API and then refused by the browser, reported as a console violation and never as an HTTP status. NEXT_PUBLIC_STORAGE_UPLOAD_URL goes into connect-src and nowhere else.

And a shop in Kampala

Duuka joins the showcase: one deployment serving many storefronts for East African businesses that sell over WhatsApp, live on Laravel Cloud. The showcase no longer requires table and model counts, because those are the author's to publish and a number nobody measured is worse than a card without one.

grit scale: measure, then do one thing

Point it at a running deployment and it reports the request percentiles, connection use against the ceiling, the slowest queries, the tables being read end to end and the cache hit rate, then names one next step. Most of the time that step is nothing, and that is the feature: a tool that nags you to add read replicas at forty requests a minute is a tool you learn to ignore.

It checks connection exhaustion before anything else, because that is the only failure here that arrives as errors rather than slowness, and it refuses to mention a replica while a large table is still being scanned end to end. An index is free; a bigger database is not.

The measuring happens in the API, at GET /api/v1/scale, admin only since it reports connection counts and query shapes. Percentiles measured on a laptop describe a laptop.

Read replicas, in one environment variable

DATABASE_REPLICA_URLS, comma separated, and reads go to the replicas on the next boot with no handler changes. Routing is per statement through GORM's dbresolver rather than per call site, which matters for the rule nobody writes by hand: a read inside a transaction goes to the primary, so a balance check inside the transaction that debits the balance cannot read a replica whatever the handler was written to do. database.Primary() and database.Replica() force either side for the reads that decide a write.

Read-your-own-writes is handled by a cookie rather than a shared store: it travels with the person who wrote, costs no lookup, and cannot itself be stale. The alternative puts Redis on every read and takes the read path down with it.

cache.Remember

Cache-aside with the three things a hand-written version misses. A cache read failure falls through to the loader, so Redis being down makes the app slower rather than broken. TTLs are jittered, so ten thousand keys written by one deploy do not expire in the same second. And when a hot key expires one caller rebuilds it while the rest wait briefly and read the result, instead of every concurrent request running the same expensive query. Plus a hit rate, which grit scale reads.

grit doctor does the connection arithmetic

Instances times DB_MAX_OPEN_CONNS has to stay under max_connections, and the number people get wrong is instances: a pool of 25 is comfortable on one machine and fatal on eight, and nothing else in the config mentions the other seven. Set APP_INSTANCES and doctor does the multiplication, before production does it for you.

And a page about all of it

Scaling maps the ten stages to what a Grit app already does. The honest count: Stages 1, 3, 4 and 8 ship on the first commit, Stage 2 does not apply because Go uses every core, and Stage 9 is the one thing Grit deliberately does nothing about.

The production stack no longer asks for a subnet it does not need

Docker hands out bridge-network subnets from 172.17.0.0/12 sliced into /16 blocks: about sixteen networks for the entire daemon. It does not return them when a deploy fails or a project is deleted. Run half a dozen Compose stacks on one host and the pool empties, and after that every deploy dies at the last step with all predefined address pools have been fully subnetted, after every image has already built. Nothing is said about disk, memory or CPU, because none of them are the problem.

docker-compose.prod.yml declared a named network and attached every service to it. Compose's implicit <project>_default gives the same service-name DNS and the same isolation, so the named one took a subnet and bought nothing. It is gone. So are the pinned container_names: names are global to the daemon, so a second copy of a stack, staging beside production, could not start while they were there.

grit upgrade applies both changes to an existing project, so the stacks already deployed converge rather than keeping the arrangement that causes this.

And a way out for a host whose pool is already empty

One fewer network per stack does not help a host with none left: even the implicit default fails to allocate. Every project now ships docker-compose.shared-network.yml, an overlay that joins a network which already exists and so asks for no subnet at all.

A shared network is shared, and the overlay says so: containers on it resolve each other by service name, so every service is given a project-prefixed alias and the API is pointed at those rather than the bare names. Two projects that both call a service postgres would otherwise resolve each other's, and a silent connection to somebody else's database is a worse day than a failed deploy.

The compose repairs had never run on Windows

Found while testing the above against real deployed projects: their compose files are CRLF, because git converts them on checkout, and every repair pattern was anchored on a bare \n. They matched nothing and reported no change, which is indistinguishable from a file that needed none. The Redis password repair in particular has been a silent no-op on every Windows checkout since it shipped. All of them are line-ending agnostic now, and a CRLF file stays CRLF.

Deploy to Railway in one command

grit deploy --railway pushes the variables a deploy actually needs, uploads the API and generates a URL. --provision adds Postgres and Redis on the way and points DATABASE_URL and REDIS_URL at them as Railway references rather than copies, so rotating a password does not need a redeploy and the password never sits in the app service's own settings.

The CLI does the upload rather than the GraphQL API, and that is not a preference: Railway's API has no endpoint that accepts local source. A service is built either from a connected repository or from an archive their CLI uploads, so every step Grit runs is a documented Railway command, printed before it runs.

It does not send your whole .env. A generated one has around a hundred entries and a real project sends about sixty. Empty placeholders for providers you do not use are held back, so is PORT, which Railway assigns, and so are the MinIO, Mailhog and compose-database settings, which describe containers on your laptop and would contradict the database you just provisioned. APP_ENV is forced to production whatever the file says.

--dry-run prints the whole plan, in order, and runs none of it. Values are masked, so the output is safe to paste into an issue.

Generated projects now carry apps/api/railway.json, which builds from the same Dockerfile docker compose uses rather than letting Nixpacks guess, and adds the health check and restart policy. The upload happens from apps/api rather than the repository root, because the Dockerfile copies go.mod from the context root and the Go module is apps/api.

The dashboard says what day it is

The weekday, date, month, year and time, beside the greeting. Rendered only after mount and deliberately so: a date formatted on the server and again in the browser disagrees on both the clock and the locale, and React's answer to a hydration mismatch is to throw away the subtree and rebuild it, which is a steep price for a decoration.

A passkey could be registered and never used

The account page invited you to add one and said "you can sign in on this device without a password". There was no way to do it. The API had /auth/passkeys/login/begin and /finish from the day passkeys shipped, and lib/webauthn.ts had toRequestOptions and encodeAssertion, written for exactly this call. Nothing in any frontend ever called them, so the whole sign-in half of the feature existed and was unreachable.

The sign-in page now has a Sign in with a passkey button, with a fingerprint on it, under the password form. It uses the discoverable-credential flow: the challenge carries no allowCredentials, so the browser offers whichever passkeys it holds and you are in with one touch, no email and no password. The server issues the same tokens a password sign-in issues and records the same session row, so the device appears in Active Sessions and can be revoked like any other.

The button appears only where the browser can actually produce a passkey, and that question is asked of the browser rather than the server: before anybody has identified themselves the server does not know whether this person has a passkey, and asking it would tell an attacker which addresses have accounts. Closing the system sheet or tapping Cancel is not reported as a failure, because telling somebody "passkey sign-in failed" when they changed their mind is how a button stops being trusted.

Proven end to end against a CDP virtual authenticator rather than reasoned about: register a passkey, clear the cookies, click the button, land on the dashboard.

The account screen was the one page in the admin with no way back

It wrote its own <h1> instead of using PageHeader, and PageHeader is what derives the "Back to System Hub" link for every /system/* route. So the one screen you reach from the hub and then need to leave was the one screen with no link out, and it was also missing the refresh, theme and notification controls every other page carries.

One page instead of four tabs

Six cards were hidden behind four tab labels, so answering "where am I signed in" meant knowing that devices were under Devices and not under Security. The page this replaced showed all of it at once, and six cards is a scroll rather than a navigation problem.

Now one column: profile, password, two-factor, passkeys, sign-in links, active sessions, and closing the account last, because it is the only thing on the page you cannot undo. It used to sit in the middle, since it lived inside the component that draws the first card; it is its own card now.

Every card shares one shell: a tinted icon chip, a title, a line of explanation and a rule under it. Profile and Password had the explanation beside the fields while the other four had it above, which is the kind of difference nobody can name and everybody notices. Active sessions has a heading for the first time: under a tab called Devices the tab said what the list was, and stacked it was an unlabelled column of device rows.

The five existing deep links that pointed at ?tab=security now point at #security, and the anchored sections carry a scroll margin so the sticky header does not cover the heading you were sent to.

Grit's slogan was in the browser tab of every app built with it

The generated Next.js app set its page title to "MyApp — Go + React. Built with Grit.", so every site anybody shipped carried the framework's marketing in the tab, in search results and in every link preview. The generated docs description did the same, and the generated README managed to say it twice: Built with Grit — Go + React. Built with Grit.

A title is the project's, not the framework's. The tab now says the project name and nothing else, the docs description says what it documents, and the README credit reads once, as a link. The starter landing page keeps a short "Built with Grit" badge, which is a credit rather than a slogan.

A new tagline

Describe your data. Get the whole app. It replaces "Go + React. Built with Grit." in the CLI banner, the README and across the documentation site. The old one named the ingredients; this one says what happens.

One line of CSS had killed every border colour in both apps

globals.css set the themed border colour twice: once inside @layer base, which is right, and once more near the bottom outside any layer. Unlayered CSS beats every layered rule, so that second copy overrode border-accent, border-danger and even border-transparent, everywhere, in the admin and the web app, since the Tailwind v4 migration.

Measured rather than guessed: the active tab on the account screen, the one carrying border-b-2 border-accent, computed to the same grey as its three inactive neighbours. That is the report that the tabs do not show which one is selected, and it was every coloured border in the product.

Sixty-seven colour utilities that compiled to nothing

Tailwind v4 makes one utility per --color-* in the theme block, and the admin defines sixteen. text-text-primary, bg-card, text-muted-foreground, bg-bg-primary and the rest name nothing, so they produce no rule: no build error, no console warning, just an element keeping whatever it inherited. A page looks almost right, which is worse than looking broken.

All of them are now real tokens, and a test walks every file the scaffolder writes and checks each colour utility against the palette that app's own stylesheet defines.

The account screen, drawn one way

Six cards, built at different times, with two surfaces, three icon treatments, two heading sizes and one bordered header band nothing else had. They share a shell now: the same tinted icon chip, the same surface, the same heading scale. The active tab carries its colour and its weight as well as its underline, because an underline alone is a two-pixel line and it is the first signal somebody with low vision loses.

An authenticator on a drifted clock can now finish enrolling

v3.326.0 taught the server to say your clock is 60 seconds behind instead of "invalid code". Useful, and not enough: knowing why does not let you turn on two-factor, and "fix your clock" is not advice on a managed machine.

Enrolment now searches five minutes either way, records how far out the device is, and validates every later sign-in against that offset with the same one-step window as before. It does not widen what is accepted: the window is still 30 seconds either side, of the device's time rather than the server's. Each accepted code re-records the offset, which is the resynchronisation RFC 6238 describes, so a clock that loses a second a day is followed rather than locking the account out six months later.

Email that survives an inbox, in the project's colours

The six templates were full HTML documents with a <style> block each. That is the one part of an email that is not reliably delivered: Outlook on Windows renders through Word and drops most of it, and Gmail strips it when a message is clipped or forwarded. They arrived as unstyled serif text for a large share of recipients.

Now one table-based layout with every style inline, a preheader so the inbox preview says something, and colours from THEME: a project built with --theme emerald sends green email rather than the framework's purple. The two emails that were never in Mail Preview, the sign-in code and the magic link, are in it.

The theme paints the web app too

The five themes added in v3.322.0 went into the admin's stylesheet only, so grit new shop --theme emerald produced an emerald admin behind an Atlas marketing site. The web stylesheet now takes its palette from the admin's, and a test holds the two together. The desktop app was already fine: it reads the shared theme registry at runtime.

The audit log is documented

A new page under Security: what the hash chain is, what Verify chain actually does, why request bodies are stored as a digest rather than verbatim, what --audit-reads adds, how pruning re-anchors the chain, and what the whole thing does not defend against.

ADMIN could not be edited, and the page told you to use a control that did not exist

ADMIN holds the * grant, which means every permission there is, including any added by a later release. The roles editor read that off the role and treated it as settled: the permission grid was replaced by a paragraph saying "remove that grant to pick individual permissions", and nothing on the page could remove it. Saving sent * straight back. The first role in every project was therefore the one role nobody could change.

The wildcard is a checkbox now, sitting in the Permissions header next to the counter. Untick it and the grid appears with everything the role currently holds already ticked, so narrowing ADMIN means unticking what you do not want rather than rebuilding it from nothing. Tick it again and the role goes back to *. The server already allowed all of this; only the screen did not.

A padlock on a card that opens

Built-in roles were drawn with a padlock beside the name. They are not locked: their description and their permissions have always been editable, and the seeder never overwrites an edit. The padlock is gone, the BUILT-IN badge stays because it is worth knowing, and the notice inside the editor now says which parts are yours to change and why the name is not: route guards, the seeder and the legacy role column all resolve a built-in role by name.

Em dashes in the text a project shows its users

Fourteen of them, in the sign-in footer and the page description of every admin style and theme, plus two more in the roles screens. Replaced, and the roles screens now have a test that keeps them out.

Verifying your own email in development, and a banner you can put away

A new project has no mailer, so the "confirm your email address" banner sits at the top of every admin page with no way to act on it. The link exists, in the server log or as a file under storage/mail, and nobody goes and gets it. In development the send endpoint now returns the link with the response, and the banner offers it as something to click. The response body is guarded on APP_ENV: anywhere else it would hand a working verification link to whoever asked for one, which is the whole secret.

The banner also has a close button now. Dismissal lasts the browser session, not forever: an unconfirmed address means a password reset has nowhere to go, so the reminder comes back at the next sign-in. It is stored in sessionStorage behind a try/catch, because that throws in a private window and a banner is not worth a blank page.

"The authenticator is not working" is usually a clock

A TOTP code is valid for 30 seconds either side of the server's clock. A phone or a VM whose time has drifted past that produces correct codes that are refused, and the refusal said "Invalid verification code. Make sure your authenticator app is synced", which sends people to delete the entry and re-scan a QR that was never the problem.

The server can measure the drift, so it does. A refused code is searched five minutes either way, and if it matches there, the message says so: how many seconds out the device is, and in which direction. A code that is simply wrong gets its own message and is not told its clock is broken. The code is refused either way, the attempt is counted the same way, and the search skips the window the validator already tried so it can never widen what is accepted.

A refused password said why in a sentence nobody could read

The password rules are shown to the user as a checklist, and the API built its error by joining those checklist labels after "Your password needs ". Two of the four are phrased as negatives, so the result was: Your password needs not a password everyone tries first and nothing from your name or email. That is what the API has been returning.

Each rule now carries its own clause for the sentence, separate from its checklist label, and the clauses come out in rule order rather than the order they happened to fail, so the same two failures always read the same way.

A theme now repaints the dashboard, not just the sign-in page

The five themes added in v3.322.0 styled their auth screens and left the dashboard on the default palette: a coral project had a coral sign-in page and an Atlas-coloured admin behind it. The picker that offers them says a theme "drives auth layout, dashboard tokens, fonts and brand colours", and for those five the middle one was not true.

Each now has its [data-theme] block, with the accent matching the theme's primary, so the sign-in button and the dashboard's buttons are the same colour.

Aurora and Pulse had an invisible button label

Writing the test that holds the above turned up something older. Buttons are bg-accent text-accent-fg, and neither Aurora nor Pulse ever set --accent-fg. With that token undefined the label falls back to --text-primary: near-black text on Aurora's near-black button, which cannot be read at all, and near-black on Pulse's blue, which barely can.

This is the same fault v3.318.0 fixed for the light themes and missed for these two, and it has been shipping since. Both now name white explicitly, and the test walks every theme rather than checking the token appears somewhere in the file, which is what let one theme satisfy it for all of them.

The theme picker offers the themes

v3.322.0 added five sign-in layouts and the themes that select them. They were reachable with grit new app --theme emerald, listed in the docs, offered by the stack builder and the AI wizard, and accepted by the flag validator. The one place they were missing was the interactive picker that grit new shows when you do not pass a flag, which is what almost everybody sees. For them the layouts had not shipped.

Nothing failed, which is why it survived a release: a rejected flag says so, a missing option says nothing at all. The picker now lists all eight, and two tests hold it to ValidThemes in both directions, so a theme cannot be accepted by the flag without being offered, or offered without being accepted.

Shipped as v3.323.1: the v3.323.0 tag's release job failed on a test of mine that asserted differently on Linux than on Windows, so it published no binaries.

grit update worked once on Windows, then failed forever

A Windows executable is locked while it runs, so updating means moving the running binary aside before writing the new one. It moved to grit.exe.old, and the leftover was cleared on the next run. Except Windows does not always clear it: when anything still holds a handle, the file is marked delete-pending rather than removed, the name stays reserved, and the rename onto it fails with Access is denied. Nothing in that message names the leftover, so the fix nobody could guess was to delete a file by hand.

The binary now moves to a name carrying the process id when the plain one cannot be cleared, which nothing else can be holding, and every leftover is swept after a successful update rather than only the current one.

Both installers now prove they can update before they write

An install is also a decision about every update after it. A binary installed with sudo into a root-owned directory, or into Program Files, can never be replaced by grit updaterunning as you: it fails on permissions, long after the install that caused it, with an error that names neither the directory nor the reason.

So both installers now write and delete a probe file in the install directory before downloading anything, and stop with something you can act on if it fails: which directory refused, whether it is a system directory that would need elevation for every future update, and the one-line command to install somewhere you own instead. grit update runs the same check up front rather than discovering the problem halfway through replacing itself.

The advice is always to move the install, never to run as administrator. A CLI that needs elevation to update is a CLI that stops being updated.

Five more sign-in layouts

Grit shipped three themes with three sign-in screens. It now ships eight. The sign-in page is the first thing anybody changes in a generated app and close to the last thing they want to build, and three shapes was not enough to find one that fits.

• Coral puts the form in a card floating over a blurred glimpse of the app, the shape a marketplace uses when signing in is an interruption rather than a destination.
• Amber is a plain bordered box under a wordmark, with the legal line and footer links a storefront is obliged to carry. Deliberately unfashionable.
• Sky is a top bar and one bold heading, with social sign-in above the password field, for products where most people arrive holding an identity already.
• Mono is black and white on a fine grid with a panel of proof beside the form.
• Emerald is a narrow form column with a customer quote filling the rest.

Pick one with grit new myapp --theme emerald, or switch later with THEME=emerald in .env. A theme still carries its colours, fonts and radius: the layout is one more thing it decides.

The form inside is the same component in all eight, so none of this touches validation, the second factor, or the sign-in call. A layout decides where things sit and nothing else. The eight shells are generated from one shared preamble and one token block rather than eight copies, because eight copies of a CSS-variable list is eight chances for one theme to quietly stop publishing --auth-radius and render inputs with no border.

Emerald's quote ships attributed to "Replace this with a real one", and a test keeps it that way. A scaffold that ships a plausible-sounding fake endorsement is a scaffold that puts a lie into production the first time somebody forgets to edit it.

The desktop app keeps its three shells and maps the new layouts onto the closest of them, which is written down rather than left to a default arm: a window is not a browser tab, and a modal over a blurred page or a footer of legal links both assume a page you scrolled to. A test checks every layout is named there, because falling through silently would render Atlas for somebody who asked for Emerald.

Also

• The "Copy prompt to build with AI" button is no longer the same blue as "Get started" beside it. Two solid blue buttons side by side make neither one the obvious thing to press.
• The home page link that read "Our philosophy" now reads "Why Grit".
• The "Grit in action" section gained a seventh step for themes, because a generated admin looks like a look people assume they are stuck with.

One prompt to confirm your email, not two

v3.320.0 added a "confirm your email address" card to the dashboard, directly underneath the banner that has asked the same thing on every page since long before it. Two prompts for one job teach people to ignore both, and the next one that matters pays for it.

The banner stays, because it covers every page rather than only the dashboard. The dashboard card is gone, and the dashboard nudge now owns the one thing that had no home anywhere: turning on two-factor. A test keeps it that way.

Worth saying how this was found, because it is the whole argument for the next item: not by reading the code, which looked right, but by opening a screenshot of a running admin and seeing the two of them stacked.

The home page shows the table

The "Grit in action" section paired the grit generate resource command with a screenshot of a form. The list screen is what that command produces first and what people spend their day in, so it now shows that instead: statistic cards, search, a date filter, import and export, a column picker, and a sortable table of 500 seeded rows with bulk selection and row actions. It is a photograph of a real generated project, taken for this release.

The README gains it too, alongside the Account screen.

Sign in with a link, for the accounts that never had a password

The sign-in page now offers "Email me a sign-in link instead", under the password box and using the address already typed there. It matters most for the accounts that have no password at all: anybody who signed up through Google or GitHub, and anybody whose reset email keeps landing in a spam folder they cannot reach from their phone. WCAG 2.2 asks for a way past a cognitive test at sign-in (3.3.8). Remembering a password is one, and this is that way.

Three decisions, each of them the thing this feature is usually got wrong:

• The form answers the same either way. "If that address has an account, a sign-in link is on its way", whether or not it does, and an address with no account does no work at all. Anything else turns the sign-in page into a way to find out who is registered here. The one exception is the rate limit, which is refused out loud, because the person is sitting in front of an inbox and silence would leave them waiting for an email that is not coming.
• The token is spent by the page, not by the link. Opening the link loads a page that POSTs the token back; the server spends nothing on the GET. Corporate mail scanners follow every URL in a message before anybody reads it, and a token spent on the GET is one the scanner burns. The person then clicks their own link and is told it has already been used, with nothing in that message to suggest why.
• A link replaces the password, not the second factor. An account with two-factor on gets the same challenge it always does. A link sitting in a mailbox is exactly what a second factor exists to survive.

Links live 15 minutes, work once, and are stored as a SHA-256 hash, so a database read is not a pile of working sign-ins. Spending one is a conditional update rather than a read followed by a write, so two tabs opening the same link cannot both get in. Signing in this way records a session and an activity-log entry like any other, so the device shows up under Devices and can be revoked.

The Security tab gains a Sign-in links card listing when a link was requested, from what address, and whether it was used, expired or is still valid. It exists because the request form answers identically to everybody by design, which also means it can never warn anybody: this is the only place a request you did not make becomes visible. It never shows a token.

The dashboard asks you to finish two things

An unverified email address means a password reset has nowhere to go, which is a bad thing to discover on the day you need it. An account with no second factor is one leaked password from gone. Both facts used to live on a settings page nobody had a reason to open, so the dashboard now says so once, with a button that does the thing: send the verification email, or open the two-factor setup.

Each card can be dismissed, and both disappear on their own once the underlying job is done, so nothing becomes permanent furniture. A banner that cannot be dismissed is one people learn to look past, which costs the next one its attention too. All four dashboard styles have them, which a test now enforces.

One account screen, not two

v3.319.0 put everything about your own login on /system/account and left the older /account/security showing the same cards. Two pages for one thing is the problem the Account screen was built to fix. The old address now redirects, so a bookmark still works, and the user menu points at the new one.

A skill and a prompt, so an agent gets Grit right the first time

Grit is a code generator, not a runtime library, and nearly every mistake an AI makes with it comes from not knowing that: it hand-writes the nine files that grit generate resource would have written, produces something that compiles, and cannot work out why none of it is reachable.

So there is now a proper skill, installable with npx skills add MUKE-coder/grit --skill grit and readable at /skill.md. It covers the mental model, choosing an architecture, the full field-type table, which layer code belongs in, the response format, the list of things already in the box that agents keep rebuilding, the verification commands, and the nine mistakes that cost the most time.

A Copy prompt to build with AI button now sits in the hero, in the install tabs beside Windows, macOS and Go, on the docs home, on Start Here, and on the Build with AI page. It copies a nine-step brief that installs the skill, links every concept the agent needs, and tells it to ask you what you are building before it scaffolds anything. It is also fetchable at /prompt. The nav item formerly called "AI Integration" is now "Build with AI".

Grit in action, on the home page

A new section directly under the hero: six commands on the left, typed in the order you actually run them, and on the right the screen each one produced. The rest of the page argues; this part demonstrates. The screenshots are real generated projects, the pairing is the point, and it pauses on hover or focus with every step reachable by keyboard.

Also

• The desktop sign-in knew which second factor an account used and never read it, so every account using codes by email was told to open an authenticator app it had never set up. Only a generated project's type check caught it, as an unused variable. Fixed, and pinned by a test that checks the admin and the desktop together.
• The README is rewritten for somebody with no time: install, sixty seconds, what ships, a real five-minute tutorial that ends in a deployed support desk, and everything else folded away. Its field-type table said belongs_to was a uint; it has been a UUID string for a long time.

grit upgrade carries all of it into an existing project: the routes, the model registry, the pages and the cards.

One Account screen, under System → Security & Access

Everything about your own login was scattered across three pages: the password sat on a page called Profile next to a job title and a bio, two-factor and passkeys were on a second page, and the list of devices on a third. Somebody trying to lock their account down had to know all three existed. There is now one screen with four tabs, Profile, Password, Security and Devices, and it composes the cards that already existed rather than copying them.

The tabs are links, not an ARIA tablist: a link is keyboard-operable, shareable and survives a refresh without any roving-focus code, and the hand-rolled version is the one that fails a keyboard user.

Password rules the server actually enforces

The password box now shows four rules while you type, and the reason to trust them is that the same four run on the server, in one package, on registering, changing and resetting alike. A checklist the server ignores is theatre: every item can be green and a weak password saves anyway.

At least 8 characters; letters and something else; not one of the few hundred passwords attackers try first; and nothing taken from your own name or email address, which only the server can check because only the server knows both. A refused save says which rule it failed rather than "invalid password".

A second factor by email, for people who will not install an app

Two-factor meant an authenticator app or nothing, and for a lot of people that meant nothing. The Security tab now offers codes by email beside it. An authenticator is still the stronger of the two, because the code never leaves the device, while an emailed code is only as safe as the mailbox, which is also where a password reset goes. It is here because the alternative for those people was no second factor at all.

Turning it on takes two steps on purpose: a code is sent first, and only when it comes back is the factor switched on, so nobody enables something they cannot receive. A deployment with no mailer is refused outright, and if mail stops working later the sign-in says so instead of leaving somebody at a code box waiting for a code that is never coming. Codes are six digits from crypto/rand, stored hashed, compared in constant time, spent on use, and counted against the same five attempts as an authenticator code. The email carries the digits and no link, because an email asking you to click to sign in is the shape of every phishing message ever written.

grit upgrade carries all of it into an existing project, including the two routes and the sign-in branch, which live in files a project owns and would otherwise arrive half-wired.

The admin, audited in a browser

Not reviewed by reading it: driven with a real browser against a generated project, measuring what the page actually rendered. Six things failed, and every scaffolded admin had inherited all of them.

The primary button was unreadable. White on the default dark theme's #60a5fa measures 2.5:1, against the 4.5:1 that AA asks for: a blue rectangle with a rumour of text on it. The brightness is the point of lifting an accent for a dark canvas, so the label moved rather than the colour. There is now an --accent-fg token, dark on the light-blue themes and white on the dark ones, and the twenty-nine places that hard-coded text-white use it.

Muted text sat at 3.1:1 on the dark canvas and 2.5:1 on the light one. It is the colour of every table column header, so the labels on the densest screen in the admin were the hardest to read. Both tokens moved to values that measure over 4.5:1.

A screen reader read a page of identical checkboxes. Every row's select box announced nothing at all, so ticking one was a guess. Each now names its row, taken from the first readable column rather than from an id nobody identifies a row by, and the search box has a name instead of a placeholder that vanishes the moment you type.

There was no way past the sidebar. Eight links, on every page, before the content: a skip link now comes first and the main landmark it targets is focusable, so the next Tab carries on from the content instead of the top. The auth pages gained a landmark too, so the sign-in form can be reached without walking the hero panel.

And several targets were under 24px (WCAG 2.5.8): the row checkboxes, the password eye, the Edit and Delete links in a row, the option library's delete buttons. The option library's three fields also had visible labels attached to nothing, which is the same defect this admin shipped twelve times once before.

Five tests hold each of these, written against the templates so they fail before a release rather than after one.

One colour axis, different colours per product

Options are shared by the whole shop, which is what keeps one spelling of Colour and lets a filter match across the catalogue. On its own that left a gap any real shop hits on its second product: offering Colour offered every colour in the shop, so a shirt in ecru and navy and a tee in black, sand and olive could not share the axis. The storefront blueprint worked around it with two Colour options, one per product, which is the duplication the shared library exists to prevent.

A product now offers some of an axis's values. The admin's picker shows each ticked axis with its values under it, and the API takes them as value_ids alongside option_ids. An axis with none of its values listed is offered whole, and an axis with every value ticked stores nothing, so both mean the same thing: a colour added to the shop next month appears on every product that said yes to the axis rather than being quietly left out.

Nothing had to be backfilled. A catalogue that has never narrowed anything behaves exactly as it did, because no rows for an option means all of its values. Narrowing changes which combinations exist, so it clears the matrix the way changing the axes does, and the admin asks first. Every read of a product's options goes through one function, so the matrix generator, the public payload and the picker all see the narrowed set without knowing about it. Four shipped tests cover the rules.

On an existing project: grit add variants --resource Product again, then grit migrate for the new table.

grit plugin update: a plugin fix that reaches installed projects

Yesterday the Stripe plugin learned to record what a renewal charged. Nobody who had already installed it could have that. grit plugin add refuses once a plugin is installed, grit upgrade never touched plugin files, and remove then add loses every local edit and re-inserts the patches at their markers, which moves them relative to code the app has written since. Doing exactly that to a shop built on Grit put the payment service below the code that constructs things from it, and the API stopped compiling.

grit plugin update stripe     # the files it owns, as this CLI writes them
grit plugin update --all      # every installed plugin
grit upgrade                  # does the same, for every plugin, on its way past

An update rewrites only what it can prove nobody has touched. Every file is fingerprinted when the plugin writes it, so one whose fingerprint still matches is replaced and one that differs is left exactly as it is and named. Files a release has added simply arrive, a patch already in place is never applied twice or moved, and nothing is ever deleted. A line ending is not an edit, which matters on Windows where git rewrites them on checkout.

Two refusals are deliberate. A file you have edited is never overwritten. And a project installed before fingerprints existed cannot be judged at all, so rather than update some files and not others, it changes nothing and says which files it cannot vouch for: the file a release adds is usually the one another file has to change to use, and half an update is a project that does not build. Both have the same way out, with git to read it afterwards:

grit plugin update stripe --overwrite   # take the plugin's version of everything
git diff                                # and see exactly what that did

A subscription now records what it charged

A subscription row says what somebody is entitled to. It says nothing about what they paid, when, or whether last month's renewal went through, and that lived in Stripe and stayed there. So an app could show a customer as a member and hold no record of a single payment from them, which is a problem the first time anybody asks for a receipt, a refund, or the month's takings. A shop built on this had a sales page reporting nothing while subscriptions were selling.

grit plugin add stripe now records every paid invoice as a Payment, the same row a one-off purchase writes, with the reference subscription:<id>, and runs the app's OnSucceeded hook so a receipt is sent for a renewal without writing that twice. A failed renewal is recorded too, with what the bank said, because that is the one an app most needs to show. A redelivered invoice changes nothing, a late failure cannot unpay a paid invoice, and an invoice in Stripe's newer shape (where the subscription moved under parent) is read either way. Five shipped tests.

services.OnOAuthLogin: what the provider knew

A social login learns things only the provider knows: the GitHub login, the avatar, the locale. Grit used one field of the profile and dropped the rest, and the callback that had it is a file Grit rewrites, so an app that wanted the GitHub handle had to fork it. The shop asked people to type a GitHub username it had just been handed at sign-in, and a typed username is where a typo comes from: an invitation to somebody else, or to nobody, found out about when the repository never appears.

Register a hook at boot and it runs after every social login, with the account and the profile:

services.OnOAuthLogin(func(ctx context.Context, user *models.User, profile goth.User) error {
    if profile.Provider != "github" || profile.NickName == "" {
        return nil
    }
    // NickName is the provider's handle: the GitHub login, the Twitter @.
    return db.WithContext(ctx).Model(user).Update("github_username", profile.NickName).Error
})

A hook that fails is logged and the rest still run, and the login still succeeds: refusing somebody a session because their avatar URL would not save is a worse failure than the one it reports. grit upgrade adds both the registry and the call site to an existing project.

SQLite stops saying "database is locked"

A SQLite file opened with GORM's defaults has no busy timeout, so the second writer fails instantly instead of waiting its turn, and the pool handed out twenty-five connections to compete over one file lock. Two writes a few milliseconds apart was enough. Building a shop on Grit, a subscription webhook lost its write to a background worker's tick and the customer's purchase granted nothing, with only SQLITE_BUSY in a table to say why.

Grit now opens SQLite with busy_timeout and WAL, and takes one connection for it, so two writers queue inside the process instead of colliding in the file. Postgres and MySQL keep the pool they were given. grit upgrade repairs an existing project.

A redelivered webhook that failed is run again

A provider retrying a delivery is the one thing standing between a handler that failed and a customer who paid for nothing, and the receiver answered every repeat "skipped: duplicate". That is right for an event already processed and wrong for the two cases that bring a provider back: a handler that failed, and an event a process died holding. Both were dropped, permanently, in a table nobody reads.

A redelivery now claims the stored event with a conditional update exactly one caller wins, and runs the handler again. An event still being handled is left alone, and one abandoned by a dead process is taken over once it is too old to be in flight. Four shipped tests hold the cases apart.

middleware.Identify, for the public pages that know you

A catalogue that marks what you already own, a pricing page that knows your plan, an article with your own comment on it: each has to be readable signed out, which means no guard, which used to mean the handler could not tell who was reading even when they were signed in. Every app ended up parsing the Authorization header by hand, and that is how the cookie flow gets forgotten.

middleware.Identify reads the session if there is one and lets the request through either way, setting exactly what middleware.Auth sets. It is not a guard: a missing, expired or revoked token is an anonymous request, not a 401, so anything that must not be served to a stranger still belongs behind Auth.

grit generate field on User

Adding a field to User failed on the admin markers the resource generator writes and the ones the scaffold writes not being the same markers, and a second run could duplicate what the first had added. It now anchors on either, warns instead of failing when a marker is missing, and checks for its own work inside the block it is editing rather than anywhere in the file.

Subscriptions, in the Stripe plugin

grit plugin add stripe took one-off payments and nothing else, so anything that renews meant building card updates, failed renewals, dunning, proration and cancellation by hand. It now does recurring plans through Stripe's hosted checkout and billing portal, which are already localised and already handle 3-D Secure. Your app writes two functions: OnActive to grant what the plan buys and OnEnded to take it away, both inside the transaction that records the change.

GET /subscriptions/me answers entitled, which is the only question the rest of an app has to ask. A failed renewal keeps access while Stripe retries the card, because past_due is usually an expired card and most of those retries succeed; access ends when Stripe gives up. Cancelling leaves the days already paid for. Subscription events are conditional updates like payments, so a redelivered or out-of-order event changes nothing the second time, and a checkout session belonging to somebody else grants nothing.

Return URLs are built from SITE_URL plus a path, never from a URL the browser sends. See the plugin's page. Ten shipped tests cover it, and it was driven against a running API: a created subscription grants access, a redelivery is skipped, past_due keeps it, canceled ends it, and a subscription for nobody is recorded against nobody.

Stored images were not loading in development

next/image refuses to fetch an image whose host resolves to a private IP, and in development every host is one: the API serves stored files from localhost, and MinIO is localhost too. The optimizer answered 400, the page showed alt text, and the reason was a line in the terminal. Every app with an upload looked broken while running locally, and nothing said why.

Each Next.js app now sets dangerouslyAllowLocalIP: isDev, which is scoped to development: in production the guard stays on, where storage is a real origin and it is worth having. grit upgrade adds it to an existing web app, admin and docs site. Found building the storefront blueprint, where every product is a photograph.

Stripe payments: grit plugin add stripe

Take money for an order without trusting the browser with the price. There is no route that starts a payment: your checkout handler works out the total and calls payments.Service.Create, and the browser receives a client secret for that one payment. Reloading the checkout reuses it; a changed basket cancels the old one at Stripe, so its secret cannot pay the old price.

Stripe's word marks a payment paid, never a redirect: the signed webhook at POST /webhooks/stripe, deduplicated by event id, or POST /payments/:id/refresh reading the intent back with the secret key, so the return page works on a laptop with no webhook. Every change is a conditional update, so a redelivered or late event changes nothing, and OnSucceeded marks your order paid once, inside the transaction that marks the payment. An intent for another amount is never marked paid. Refunds come from the admin, keyed so a double click makes one. The web app gets <StripeCheckout> and <PaymentResult> in its own colours.

No stripe-go: four REST calls with the API version pinned, because its webhook parser refuses any event whose API version differs from the library's. See the plugin's page. Found missing building the storefront blueprint.

The CSP has a list plugins add origins to

Every directive of the Next.js Content-Security-Policy was one fixed string, so a plugin that loads a third party's script had nowhere to say so, and the browser refused Stripe.js with nothing but a console message. next.config.ts now has pluginOrigins, written at a grit:csp-origins marker and taken out again on removal, and an explicit frame-src 'self', which is what default-src already allowed. grit upgrade adds both to an existing web app and admin, along with the two new error codes, PAYMENTS_UNAVAILABLE and PAYMENT_PROVIDER_ERROR.

Two plugins in one project stay gofmt-clean

Plugins inject their imports at the same marker, so the second one landed wherever the first left off: a project with both video and stripe installed was no longer gofmt-clean, which fails the formatting check in its own CI. Every Go file a plugin edits is now formatted on the way out, so no plugin has to know what another injected.

Variants: a customer could reprice a variant

grit add variants mounted its routes on the group every signed-in user reaches, while the resource's own routes ask for ADMIN or a permission. So any customer could set a variant's price override to a cent and check out at that price, or create and delete the shop's options. They now ask for the resource's view permission to read and its edit permission to change, and grit upgrade moves them in an existing project. If you added variants before this release, upgrade now.

Three more from the same command, which no check caught because none ran it on a new project and built what it wrote: the public variants handler called respond without importing it, so the API stopped compiling the moment variants were added (grit upgrade adds the import); a second resource with variants wrote a second copy of the same helpers into the same packages; and the handlers it wrote did not follow the request's context, which upgrade then had to fix. The release checks now add variants to two resources of a new project and build, lint and test it.

An Expo app with push notifications opens in a browser

grit plugin add push wrote an onNotificationTap that asked expo-notifications for the notification that opened the app. On the web there is none, and the library throws rather than saying so, so an Expo app with the push plugin crashed on its first screen when opened in a browser, which is where Expo web previews and screenshots are made. It now does nothing on the web, and grit upgrade puts the fix into an existingapps/expo/lib/push.ts. Found making mockups of the WhatsApp blueprint.

A signed-in web page outlives its access token

The web app refreshes an expired session. Its API client had no 401 retry; only the admin panel added one. So every signed-in page in the web app failed fifteen minutes after sign-in, when the access token expired, although the refresh cookie was still good for days. lib/api.ts now sends /api/auth/refresh and repeats the request. Requests that fail together share one refresh: the server rotates refresh tokens and treats a second use of the old one as theft, so ten refreshes would sign the person out everywhere. Sign-in, sign-up, refresh and sign-out are never retried. grit upgrade updates an unedited lib/api.ts.

The video plugin's Expo player plays on a phone in development. It handed expo-video the stored URL as it was, http://localhost:..., which a phone cannot reach; it now goes through resolveImageUrl like every other stored file in the Expo app. And the upload example on the plugin's page named the arguments wrong: uploader.upload(file, file.name, { accepts: ["video"] }).

Both found building the Instagram blueprint.

Video plays in the browser

The web and admin Content-Security-Policy had no media-src, so <video> and <audio> fell back to default-src 'self' and the browser refused every clip the API or storage served. Nothing played video before v3.307.0's video plugin, whose VideoPlayer was therefore blocked in every Next.js app. media-src now admits the same origins as img-src, in the Next.js and Vite configs and in the nginx config a built Vite frontend is served with. grit upgrade adds it to an existing project. Found building the Instagram blueprint.

grit plugin add video: clips converted for every client

A new plugin. grit plugin add video turns an uploaded clip into one H.264 MP4 that starts playing before it has downloaded, capped at 720 on the short side, plus a poster frame and the size and length a feed needs. Every browser, iOS and Android plays that, so there is no HLS to serve and no player to choose per platform. POST /videos takes the key of an upload you own and answers 202; GET /videos/:id reports pending, processing, ready or failed. VideoPlayer and useVideo come for the web app and, with expo-video, for the Expo app. See the plugin's page.

The table is the queue. A worker claims a pending video with a conditional update, so a conversion survives a restart and replicas share the work with or without Redis. One conversion at a time per replica, and a claim held by a replica that died is taken over. The owner hears video.ready or video.failed on their realtime channel.

A crafted file cannot read the server. ffmpeg follows what a file says it is, and a playlist posing as a video can name other files for it to open. Only MP4, MOV and WebM are converted, each read with a forced demuxer and local files only; a playlist is refused before ffmpeg takes it as input.

Presigned uploads allow a video up to 300 MB. The form-field path already did for a field that accepts video; the direct-to-bucket path capped every file at 50 MB, so a minute of phone video was refused, or deleted after it landed. /uploads/profiles reports the new ceiling as max_video_upload.

A place in the Dockerfile for plugins. The API image has a # grit:runtime-packages line where a plugin adds what it needs at runtime, which is how the video plugin gets ffmpeg into the image. grit upgrade adds it to an existing Dockerfile.

The security scan passes on a project with the Expo app

pnpm audit. A project with the Expo app failed its security workflow on four high advisories, all in Expo's bundler, which the audit counts because Expo is a production dependency of the app. pnpm-workspace.yaml now moves the bundler's PostCSS to 8.5.28, which fixes the four PostCSS advisories and still bundles the app. The two image-size advisories have no fixed 1.x release, only 2.x, which metro cannot take, and metro only reads the sizes of the project's own image assets at bundle time, never a file a user uploads, so they are listed underauditConfig.ignoreGhsas with that reason, to remove when metro moves on.

Run pnpm dedupe after the React pin, not pnpm install. v3.305.0 said install. It keeps a version the lockfile already holds when it still satisfies the range, so the upload package, which asks for "react": ">=18", kept its own 19.2.7 in an upgraded project and there were still two Reacts. pnpm dedupe re-resolves, and installs.

One React in a project with the Expo app

Web and admin tests pass in a project with the Expo app. Expo SDK 54 needs React 19.1.0 exactly, because React 19 checks that react and React Native's renderer are the same version, while the web apps pinned 19.2.7. With both in one hoisted node_modules, Expo's copy sat at the root and every other app got its own, so a test loaded React more than once. Testing Library'sact() flushed a different React from the one rendering, and every component test in a new --expo project failed with "Invalid hook call" or an empty render.

With the Expo app in the project, the web app, the admin, the desktop app and the docs site now pin Expo's React, and the monorepo holds one copy. Nothing Grit generates uses an API added in 19.2. Projects without Expo keep 19.2.7. grit upgradealigns an existing project; run pnpm install afterwards.

An upgraded project's lint is green too

v3.303.0 took golangci-lint to no findings on a new project. A project upgraded to it kept one: the realtime presence heartbeat, which grit upgrade does not rewrite once a project has it. The upgrade now adds the same note a new project gets, saying why each presence write makes its own bounded context, and golangci-lint reports nothing on either.

A duplicate value answers 409, and a new project's CI passes on its first push

A value a unique field already holds is a conflict, not a server error. Saving a second contact with the same code came back as a 500 "Failed to create contact", which tells the person filling in the form nothing they can fix. respond.WriteErrorrecognises a unique violation on SQLite, Postgres, MySQL and SQL Server and answers 409CONFLICT, with the field in details when the database says which: SQLite names the column, and the others name GORM's idx_ or uni_index, read against the route's table. Every generated handler already routes through it, so this reaches existing resources on grit upgrade. A soft-deleted row still holds its value, so re-creating one is a 409 too. internal/respond has tests now.

The security scan accepts the one advisory with no fix. GO-2026-6452 is in excelize, reached only through GORM Studio's Excel import, and no release fixes it, so every new project's security workflow failed. It now reads.github/govulncheck-allow.txt, the same list Grit's own scan keeps: each entry names why it is accepted and the issue tracking the fix, prints as a warning on every run, and anything not listed still fails.

golangci-lint starts green again. The shipped config promises no findings on a new project, and there were nine, which a first push reports because there is nothing to diff against. The real one: the encrypted-column backfill never checked rows.Err, so a read that failed partway looked like the last batch and left plaintext behind. The rest are fixed or, where a fresh context is deliberate, say why at the call.

The gzip test passes under -race. The race detector makessync.Pool drop a quarter of what is returned to it, so the pooled-compressor check failed every project's CI. The limit is now half of an unpooled compressor's cost, measured, rather than near zero.

Generated desktop lists pass Biome. The bulk delete and import callbacks returned a value from forEach, which Biome reports as an error.grit upgrade fixes existing lists.

Tidier generated code, and date windows that are right on SQLite

A project stays gofmt-clean after grit generate. Registering a model with the API reference or GORM Studio left a comma before the marker comment, which gofmt removes, sogofmt -l listed apidocs.go after the first generated resource. The file is formatted after each change now, and a second run of the same resource still finds it already registered.

Count windows and daily charts on SQLite. GORM writes created_atin local time, and SQLite compares times as text, so a "last 24 hours" count or a 30-day chart bounded by a UTC time was off by the machine's UTC offset. The bounds are now the same instant written in local time. Postgres compares instants and was never affected.

No empty sign-in folders in the web app. A new web app got five empty(auth) folders for pages that only grit add web-auth writes. They are created with the pages now.

The desktop app catches up: realtime channels, and generated screens that type-check

The desktop app gets the realtime client every other app has. It shipped its own older client with no channels, presence or client events, and nothing in the app used it. It now gets the same client and hooks as the web, admin and Expo apps (useChannel,usePresence, useWhisper, useRealtime), signing the socket in with the token from the OS keychain.

Generated desktop screens failed tsc. A form for a resource with a relation to a user imported a use-users hook that did not exist; a select field was held as a string where the model types it as its options; a file field used the desktop's looser file type; and the list screen wrote each related record's name over the relation itself, so its rows no longer typed as the model. The generator now writes the users hook, types the form's payload, and gives related names their own column key. Relation pickers and columns also show a person's name instead of their id.

No more stray vite.config.js. The desktop'stsconfig.node.json had no output directory, so every pnpm build wrotevite.config.js and vite.config.d.ts beside the source. They go tonode_modules now; delete any that were written before.

grit upgrade repairs all of it in an existing project. Found putting the WhatsApp blueprint on the desktop, where its chat now runs live with typing, online status and read receipts.

Push notifications: grit plugin add push

Grit had realtime, email and background jobs, and no way to reach a phone that was not open. The push plugin adds it, through Expo's push service, which relays to Apple and Google, so the API holds no APNs certificate or Firebase key. From Go it is one line,services.NewPush(db).Go(userIDs, msg), sent in the background so no request waits on it. The Expo app gets lib/push.ts, which asks permission, registers the device, tells you which notification was tapped, and unregisters on sign-out.

A token Expo reports as no longer registered is deleted on the spot, a phone that signs in as someone else stops getting the previous user's notifications, sends go 100 to a request, and each user keeps their ten newest devices. Checked against Expo's live service: a message went out through it, and a token no device owned came back as not registered and was removed.

Plugins can add npm packages. A plugin could declare npm dependencies, but the installer only wrote them to the lockfile. It now adds each to the package.json of the app it names, as text so the file keeps its formatting, and skips an app the project does not have. Push is the first plugin to need it, for expo-notifications. Found building the WhatsApp blueprint, whose plan listed push as already shipped.

Generated Expo screens type-check

Relations to a user broke the build. A resource with a belongs_to field got Expo screens that imported a use<Plural> hook for the related model and named it asrecord.name || record.title. For a relation to the built-in User there was nouse-users hook, and most models have neither field, so tsc failed as soon as such a resource was generated. The screens now call relationLabel(), which uses whichever of name, title, first and last name, label or email a record has, and the generator writes a use-users hook when a relation needs one.

Typed routes rejected every list screen. Expo Router's typed routes are on in every Grit Expo app, and they accept a template literal shaped like a route but not a plain string. The generated list screens and the roles screen navigated with "/items/" + id, so tsc failed the first time expo start wrote the route types. They use template literals now.

grit upgrade fixes screens it generated before, adds the missing hook, and adds.expo/ to .gitignore, where Expo's cache was being committed. Found running the WhatsApp blueprint's mobile app, which now type-checks cleanly with its route types in place.

grit env: clone a project and run it

grit new writes a .env with generated secrets and a.env.example with CHANGE_ME in their place, and only the example is committed. A teammate who cloned the project had no .env, and the API rightly refuses to start on a placeholder, so their first job was generating ten secrets by hand.grit env does what grit new did: it copies the example and generates everyCHANGE_ME in the shape that variable takes, 32 bytes of base64 forFIELD_ENCRYPTION_KEY and hex for the rest. It prints the names it filled and never a value. Run again, it fills only placeholders still left, such as one a pull added, and leaves every value you set alone.

A new FIELD_ENCRYPTION_KEY cannot read data encrypted with another one, sogrit env says so when it makes one: on a database you share, use the team's key. A new project's README now has a "Cloned this project?" section with the three commands. Found cloning the WhatsApp blueprint to check its own instructions.

Two Expo fixes: realtime connects, and users stay signed in

Realtime never connected in an Expo app. React Native has no cookie jar, so the socket passes the access token itself, through a getter that setRealtimeToken was meant to replace. Nothing called it: the getter returned null and the server refused every mobile socket. It now reads the token the API client already keeps, through the app's web-safe SecureStore wrapper, and setRealtimeToken stays for an app that stores it elsewhere.

Expo apps signed users out after 15 minutes. The API client refreshed once per failed request. A screen that loads two things after the access token expires sent the same refresh token twice, and the server, which rotates refresh tokens and treats a spent one as stolen, revoked the session. Requests that fail together now wait on one refresh, as the admin and desktop clients already did. grit upgrade applies both to an existing Expo app and warns instead where you have rewritten the file. Both found building the WhatsApp blueprint's mobile app.

Realtime works in production Next.js apps

The browser blocked the realtime socket. The Content-Security-Policy a Next.js web app or admin panel sends named the API as http:// or https:// inconnect-src, and a CSP source matches its scheme exactly, so the socket atws:// or wss:// on the same host was refused. Development hid it, because the development policy allows every socket for hot reload. Under next start, live notifications, presence, client events and every other realtime update were dead. The policy now names the API's socket origin too, and the nginx policy a Vite frontend is served with allows sockets. grit upgrade fixes an existing project's config, and warns instead when you have written your own policy. Found building the first Grit UI blueprint, a WhatsApp clone.

Build artefacts are ignored. A new project's .gitignore ignores*.tsbuildinfo and next-env.d.ts, which TypeScript and Next.js write on every build, so they stop turning up in the first commit. grit upgrade adds the two lines to an existing project once.

First names seed as first names, and a CRM built end to end

Name fields seed the right part of a name. A --faker seeder filledfirst_name and last_name with a full name each, so a contact came out as "Ada Nakato Brian Okello". A field named for a first name now seedsgofakeit.FirstName(), and one named for a last name or surname seedsgofakeit.LastName(). A plain name field still gets a full name. Regenerate a seeder with grit generate seeder Contact --faker to pick this up.

New on the blog: build a CRM with Grit. One project that uses this month's features together: phone numbers from any country with the tel type, nine other field types, a million seeded contacts with grit seed Contact --count 1000000, and a live "who else has this contact open" banner built on presence and client events. Every command in it was run while writing it, and every number is the one it printed.

Seed a million rows in under a minute: batched, resumable seeding with grit seed --count

Batched inserts. A --faker seeder inserted one row per statement, each in its own transaction. It now inserts in batches, one transaction per batch, sized to what the database accepts for the table's column count. Ten thousand rows went from 96.6 seconds to 3.7 on SQLite, and from 31.9 seconds to 2.4 on Postgres. A million rows took 3 minutes 14 seconds on SQLite and about 50 seconds on Postgres, where the old seeder would have taken nearly three hours and about 53 minutes.

grit seed Contact --count 1000000. Give grit seed a resource and a count and it tops that table up to exactly that many rows. It counts what is there and inserts only the rest, so a second run does nothing and a run that was stopped partway carries on from where it stopped. With no arguments grit seed runs every seeder, as before.

Flat memory, clear failures. Rows are built in chunks by a few goroutines and written as they are ready, so a million rows used about 15 MB of heap. Progress prints every two seconds with rows per second and time left. The first batch that fails stops the run with an error; before, a failed row was logged and skipped, and the run reported success over a half-empty table. The count query's error, which was ignored, is checked.

Unique columns stay unique. A column marked unique seeds from the row's number (SKU-0000001) instead of four random letters and four random digits, which collided about a hundred times in a million rows.

grit upgrade adds the shared seeding helper, internal/database/seedbatch.go, and the new seed entry point. Seeders generated before this release keep working withgrit seed; regenerate one with grit generate seeder Contact --faker to use--count.

Ten new field types: email, url, domain, tel, country, color, percent, rating, time and json

Fields that know what they hold. grit generate resource acceptsemail, url, domain, tel, country,color, percent, rating, time andjson. Before, email, url and phone were only guesses from a field's name, andtel was refused outright.

Checked and normalised on every write. A new internal/fieldtypes package checks each value on create, update, patch, bulk edit, CSV import and sync, and stores it in one form: lowercase email addresses, bare punycode domains, #rrggbb colours, HH:MM times and E.164 phone numbers. A local Ugandan number such as 0772 123456 is stored as+256772123456. A value the column cannot hold is a 422 that names the field, for example "Phone is not a valid phone number for UG".

Inputs built for each type. The admin gets a searchable country picker covering 245 calling countries with flags and dial codes, shared by tel and country; a phone input that formats as you type; a colour picker; keyboard-accessible stars; and a JSON editor that checks as you type. The phone and country inputs load only on forms that use them. Tables and detail pages show phone numbers as tel: links, emails as mailto: links and colours as swatches.

Options in the third position. phone:tel:UG sets a field's default country, country:country:UG its default value, and score:rating:10 its number of stars. Phone numbers are checked against libphonenumber's metadata in the API (github.com/nyaruka/phonenumbers, added only to projects with a tel field) and in the admin (libphonenumber-js), so both sides agree.

Realistic seed data. --faker seeds values every rule accepts: in a 1,200-row test every email, domain, URL, colour and phone number was distinct, and the phone numbers were valid mobiles from 20 countries. grit upgrade adds the checks and the inputs to existing projects. In a project with the admin panel inside the web app, upgrade now also adds any dependency the panel needs to apps/web/package.json when that file has been edited, matched by package name and leaving your own versions alone; before, an edited file never received the new inputs' libraries and the build failed on an unresolved import.

Biome replaces ESLint and Prettier, and pnpm lint finally passes

Linting works on a new project. Before this release pnpm lint failed on every new project: the Next.js apps called next lint, which Next.js 16 removed, and the Vite apps called ESLint, which was never installed. Generated projects now lint and format with Biome 2.5.14, andpnpm lint passes with 0 errors on triple, double and single projects with either frontend. CI runs it on every pull request.

One tool instead of three. A single biome.jsonc and one pinned devDependency replace .prettierrc, .prettierignore and two Prettier packages, so a new triple project has 30 devDependencies instead of 33. Every rule that is switched off carries its reason next to it in the config.

Seven template bugs it found are fixed. Among them: the export menu called a hook after an early return, which breaks React's hook order, and the two error pages were namedError, shadowing the global. Unused imports, isNaN, and callbacks that returned values from forEach are cleaned up too.

Formatting is on demand for now. pnpm format formats in the style the templates already use: double quotes, semicolons, 100 columns. pnpm lint checks rules only, because the templates are not yet Biome-formatted and a format check would fail every new project. Runpnpm format once in your project if you want to turn formatting checks on.

grit upgrade adds Biome to existing projects. It removes the Prettier files only if they are exactly what Grit wrote, and it keeps any ESLint or Prettier setup you customised, printing one line to say so.

Less dead admin code, real types instead of any, and named upload components

New projects stop carrying code nothing renders. The old sidebar, the old view modal, and the four dashboard widgets that only the modern, minimal and glass styles use were written into every admin, and a panel inside the web app got its own second realtime client instead of using the web app's. That is 6 fewer files and 583 fewer lines in a standalone admin, and 8 files and 1,059 lines in a web app with the panel inside it. grit upgrade deletes an existing project's copies only when Grit wrote them, nobody edited them and nothing imports them; an edited copy is kept and named in the upgrade output.

Real types instead of any. Form errors, the stepper trigger, the toast hook's callbacks, the passkey options, the observability cards, the backups page and the Vite compatibility shim now have real types. A standalone Next.js admin goes from 22 explicit anys to 1, a web app with the panel inside it from 26 to 1, and a single app from 27 to 1. The ones that remain, the realtime payload and React's own lazy-component bound, are explained where they stand.

Upload components with names. The dropzone took 17 props, including a five-wayvariant and a provider hint. It now comes as five named looks,AvatarDropzone, InlineDropzone, CompactDropzone,MinimalDropzone and BoxDropzone, each built from Dropzone.Root,Dropzone.Target, Dropzone.FileList and Dropzone.Progress, which you can also compose yourself. The image, images, video and videos form fields use them directly.<Dropzone variant="..."> still works with all 17 props, so existing code keeps working. The Next.js admin ships 9 tests covering every look.

No panics on a missing user, no leftovers, an allowlist read once, named ticket values, and SSO errors that keep their cause

A missing signed-in user is a 401, not a crash. Four handlers took the signed-in user out of the request with an assertion that panics when it is absent: two in the dashboard layout, one in uploads and one in two-factor setup. Mounted without the auth middleware, 4 of 6 test routes panicked, and the upload one did so after the file was already stored. All six now answer 401, and a fresh project has no unchecked assertion on a request value, down from 4.

Leftovers removed. Blank variables that only kept imports alive, a value set and never read, an unused reflection helper, three unused types, two dead initialisers and 13 doc comments written twice are gone. On a fresh project golangci-lint's unused count drops from 10 to 2, and ineffassign and wastedassign from 1 each to 0.

The upload allowlist is read once. It was an exported map that an init()changed from the environment. UPLOAD_ALLOWED_MIME is now read by config.Loadinto Config.UploadAllowedMIME, and the upload handler gets a list built from it at startup. Generated resource handlers take the app name for their PDF export from config instead of reading the environment on every request. grit upgrade adds the config field and the wiring, so a project that set UPLOAD_ALLOWED_MIME keeps its extra types.

Ticket values have names. Ticket statuses and priorities are constants in the model (TicketStatusOpen, TicketPriorityCritical and the rest), and the label cap of 8, the notification list limit of 50 and the 500-character user agent cap on form submissions are named too.

SSO refusals keep their cause. SSO sign-in returned user-facing sentences as errors. Its 9 refusals are now named errors, 3 of them wrap the database failure that caused them, and each refusal is logged with its cause. The login page shows the same wording as before, chosen in one place for both OIDC and SAML.

grit upgrade repairs the dashboard layout handler, adds the ticket constants and the upload allowlist wiring; the upload, two-factor and SSO handlers arrive whole.

A refresh that reloads only the page, lazy table images, a quiet idle timer, and sidebar groups that open themselves

The refresh button reloads only what the page shows. With no keys passed, the admin page header's refresh called invalidateQueries() with no filter, so one click refetched every query in the app, including the signed-in user, their permissions and the notification list. On a page with two data queries, one click made 5 requests; it now makes 2.

Table images load when they come into view. Table thumbnails and avatars now load lazily, decode off the main thread and carry a fixed size, so a table's images are no longer fetched before they scroll into view and the layout no longer shifts when they arrive. On the public site, blog covers get a size and the cards decode asynchronously, while a post's main cover still loads first. Covers stay a plain image, so a cover pasted from any website keeps working.

The idle timer stops churning. The session timeout warning cleared and set a timer on every mouse move and scroll: 2,000 events cost 4,000 timer calls. Activity now only records the time, and one check every 5 seconds decides whether to warn. The warning appears after the same idle time.

Sidebar groups open on their own pages. A group was meant to open when you were on one of its resource pages, but the check compared the wrong path and it never did. It now opens, and the open group is worked out while the sidebar draws instead of in a second pass, so a navigation renders the sidebar once instead of twice. A group you open or close by hand stays that way.

grit upgrade delivers all of this with the admin and web app files it already refreshes. An existing Vite admin keeps its current files, as before; new ones get the fixes.

One Redis connection for the jobs screen, a streaming GDPR export, fewer queries per write, and a faster notification bell

The jobs screen stops opening Redis connections. The admin jobs screen built a new Redis connection pool for every request and closed it again, so fifty refreshes of the queue stats opened fifty connections. The handler now builds one inspector the first time it is needed and keeps it: the same fifty refreshes use one connection.

The GDPR export streams. An export read a person's entire activity log into memory before writing a byte, ignored the error from every query, and kept running after the client went away. It now follows the request's context, returns every database error, and writes the activity log 500 rows at a time. If a page fails partway, the file will not parse, so it cannot pass for a complete export. The two-factor flag in the export now says whether two-factor is actually on, not merely set up.

Generated writes stop reading their row back. A generated service wrote a row and then read it back with its relations: a create took 5 statements and an update or patch 6. Resources whose relations are all belongs-to now write in one statement with RETURNING and read only the related rows, so a create takes 2 statements and an update or patch 3. A patch on a resource with no relations drops from 5 to 2. MySQL, which has no RETURNING, still reads the row back.

A faster notification bell. Notifications had only single-column indexes, so the unread count for a user with 20,000 notifications read all 20,000 and threw half away. New(user_id, created_at) and (user_id, read_at) indexes let the count read only the unread entries, and a light user's list reads 50 rows from the index instead of reading all of them and sorting.

The admin root redirects on the server. Opening the admin's root returned a page with 20 scripts that then asked the API who was signed in before redirecting. The server now answers with a redirect to the dashboard before any JavaScript loads.

grit upgrade patches the jobs and GDPR handlers, updates the GDPR service and the notification model (grit migrate builds the indexes, and grit migrate down removes them), and rewrites generated services that are still in the shape the generator wrote.

Forwarded headers only from trusted proxies, a tighter image policy, safe stored links, and a checked SSO redirect

Forwarded headers are trusted only from your proxies. The API believedX-Forwarded-For, X-Real-IP and X-Forwarded-Proto from any client, so a request could choose the IP address its sessions, audit rows and rate limits were recorded under, and claim HTTPS over plain HTTP. Those headers are now honoured only from the proxies in the newTRUSTED_PROXIES setting and removed from every other request. The default trusts loopback and the private ranges (10/8, 172.16/12, 192.168/16, fc00::/7), which covers Caddy on the same host and a proxy on the Docker network, so both documented deploys keep real client addresses. Sentinel follows the same list unless SENTINEL_TRUSTED_PROXIES is set; before, it saw only the proxy's address.

Images load only from hosts the app uses. The frontends' Content Security Policy let images load from any https host. img-src now names only the API, the storage origin and the Google and GitHub sign-in avatar hosts, with NEXT_PUBLIC_IMAGE_ORIGINS (orVITE_IMAGE_ORIGINS) for anything else. Inline scripts are still allowed: removing them in Next.js needs a nonce on every request, which would make every page render dynamically, and that trade is not one to make silently.

Stored links cannot run code. Links built from stored data, such as a URL column filled in by a public form or a notification link, were rendered as given. React stops javascript:links, but data:, vbscript: and //other-host links still worked. A new safeHref helper allows only http, https, mailto, tel and paths on the site; table link cells show anything else as plain text, and notification links fall back to nothing clickable.

The SSO redirect goes only to the API. SSO sign-in followed the server'sredirect_url by appending it to the API address, so a value such as@evil.example turned into a link to evil.example. The address is now resolved as a URL and followed only when it is a path on the API's own origin.

A locked account gives nothing away, even to the right password. Since v3.287.0 a temporarily locked account answers 401 INVALID_CREDENTIALS whether the password is right or wrong. Answering ACCOUNT_LOCKED only to the right password would let someone guessing keep going through the lockout and learn which guess was correct. The lock still holds: the right password is refused until it lifts.

grit upgrade adds the proxy middleware and setting, tightens the image policy, and applies the link and redirect checks in the admin, the web app and the embedded admin panel.

Sign-in that reveals nothing, encrypted two-factor secrets, and a field encryption key in every new project

Sign-in no longer tells anyone what state an account is in. A wrong password for a locked account got 429 ACCOUNT_LOCKED, a disabled one 403 ACCOUNT_DISABLED, and a social-login account 400 SOCIAL_AUTH_ONLY naming its provider, so anyone could learn which addresses held accounts and what state they were in. An unknown address also answered in under a millisecond, against about 56 ms for a real one. All of them now get the same 401INVALID_CREDENTIALS after the same bcrypt work. A disabled or unverified account is told why only once its password is right.

Two-factor secrets are encrypted at rest. Anyone who could read the two-factor table or a backup of it could generate every user's codes. Secrets are now encrypted withFIELD_ENCRYPTION_KEY. Secrets stored before the upgrade keep working: grit migrateencrypts them in place, and any that remain are encrypted the first time their code verifies.

A field encryption key in every new project. grit new writes 32 random bytes to FIELD_ENCRYPTION_KEY in .env, so two-factor secrets and encrypted columns are encrypted from the first sign-up instead of only when someone remembered to set a key..env.example carries CHANGE_ME, and an API started with that placeholder refuses to boot and names the variable. grit upgrade never writes a key into an existing project, because a key nobody knows they have is a key nobody backs up; it prints one line saying how to generate one, back it up and run grit migrate. The go-live checklist has a new section on backing the key up: losing it locks out every two-factor user, and changing the value is not a rotation.

A stricter trusted-device cookie. The cookie that lets a browser skip the two-factor code is now Secure on HTTPS and SameSite=Lax, like the sign-in cookies. It was neither.

A refused socket token is not explained to the caller. A bad token on the realtime socket got the token parser's own error back. It now gets "Invalid or expired token", and the reason goes to the server log.

Import jobs belong to whoever started them. An import job now records its starter, andGET /imports/:id answers only that user or an admin. Before, any signed-in user with a job id could read another user's import counts and row errors, which quote the file's contents.

grit upgrade applies the sign-in, socket and import fixes whether a project has the handler shapes from before v3.285.0 or after, adds the import job's owner column, and updates generated importers. The sign-in fix also reaches projects created before v3.283.0, which never received the release that split Login into smaller functions: upgrade recognises Login as any earlier release wrote it and replaces it. A Login someone has changed is left alone, with a message saying what to change.

Tiptap 3, one editor that keeps your formatting, a paginated blog admin, and shared types for built-in models

Tiptap 3, and the security advisory is gone. The admin moves from Tiptap 2.27.3 to 3.31.3, clearing GHSA-cp6q-959q-f8rh (prototype pollution through mergeAttributes()), sopnpm audit on a new project goes from 8 advisories to 7, and the 7 left are all development tooling. Every Tiptap package is pinned to exactly the same version, because each one requires its siblings at that version and a range could install two copies of the core. The package list shrinks from 15 to 10, since Link and Underline are now part of StarterKit and the table parts part of TableKit.

One editor, one content schema. The form field and the blog editor each built their own list of extensions: the field knew 13 kinds of content and the blog editor 22. Saving a post from the field silently dropped 9 of them, including tables, text colour, highlight, underline, images and alignment; a test post went from 954 bytes of HTML to 440. Both now uselib/tiptap-extensions.ts, and a test in every new project loads and saves a post with every kind of formatting and checks nothing is lost.

The blog admin runs on its resource definition. The list was a hand-written page that fetched one page of 100 posts, so post 101 could not be reached, and the columns, filters, bulk actions and export declared in blogs.ts did nothing. It is now ResourcePage, 20 posts a page with all of those working, the detail page is ResourceDetailPage, and posts are written on a full form page.

Shared types for the built-in models. New projects had no shared types for API keys, form shares, form submissions, notifications, SSO connections, tickets and ticket replies untilgrit sync first ran, so pages declared their own copies that drifted. New projects ship them, byte for byte what grit sync writes, along with the profile page's Zod schemas, and the support pages, ticket thread and notification hook import them.

One page header and a smaller resource controller. The admin had two page headers, one used only by the resource page; the stat cards moved into components/chrome/StatCards.tsx and the second header is gone. The 759-line resource controller with 19 pieces of state is now 583 lines with 1, built from three focused hooks, and returns exactly what it did before.

A version conflict names the current version as a number again. v3.285.0 changed the 409 for a stale If-Match write to send "current_version": "2"instead of 2, which broke any client comparing it with the version it holds. It is a number again, as it was through v3.284.0, and a test in every new project checks the shape.

grit upgrade adds the shared type files without overwriting existing ones, replaces the blog pages and removes the old header when they are unedited, and raises the Tiptap versions in any app whose editor has moved onto the shared extension list. An edited file gets a message saying what to change.

No theme flash, a server-rendered shared form, one source for errors, a ticket service, and mail on the queue

The admin applies its theme before the first paint. The stored theme was applied in an effect inside the dark mode toggle, which lives in the dashboard chrome and only mounts once/auth/me answers, so every load of a dark dashboard showed a light one first. A small script in the layout's head now sets the theme before anything paints, in the Next.js admin, the panel embedded in apps/web and the Vite SPA. The second theme system is gone:theme-provider.tsx stored a key nothing else read, and its only consumer was a navbar no layout has rendered since v3.29.

The public shared-form page renders on the server. It was a client component that fetched in a useEffect, so someone opening a link waited for the bundle, then a round trip, behind a spinner. The page now reads the share on the server with no caching, so a disabled link stops working at once and the form arrives rendered. The interactive half posts through the web app's own API client, and every input has a label tied to its field.

Error responses have one source of truth. In a project upgraded from v3.284.0, hand-built error envelopes fall from 306 to 167 and respond.Fail calls rise from 2 to 139; a new project has 25 envelopes and 281 calls. respond.Fail takes the status from the generated error catalogue, and the named helpers such as respond.NotFound are now one line over it instead of hardcoding a second copy of each status and code. The envelopes left either choose their status in a switch, carry a list in their details, or are text an upgrade repair still matches.concurrency.WriteConflict now sends current_version as a string, which is what its type always said.

Tickets have a service. The ticket handler held every ticket query and rule, 396 lines with 9 direct database calls, and there was no service. services.TicketService now holds Open, Query, Visible, Reply, SetStatus and Assign, each taking a context and the acting user. The visibility rule stays part of the query, so somebody else's ticket still answers 404 exactly like one that never existed. The handler, now 256 lines with no query of its own, binds, calls one method and responds. Services no longer need a gin context to learn about the request: a middleware records the client IP, user agent and request id on the request context, so a job or a test can callLogActivityCtx, CreateSessionCtx and RotateSessionCtx.

Mail no longer leaves a handler from a bare goroutine. Registration, resend verification, forgot password and new ticket each started one: nothing bounded them, nothing retried them, and a restart dropped whatever was in flight. The verification and new-ticket emails now go on the job queue, keyed so a replayed request does not send twice, and send inline with a 15 second timeout when the project runs without Redis. Forgot password keeps its work off the request path, so its response time still does not reveal whether an address has an account, but through a helper that caps concurrent tasks at 32, recovers panics, and runs the work inline rather than dropping it when the cap is reached.

grit upgrade adds the theme script, rewrites the shared-form page while it is still the old one, writes the ticket service together with its handler, and moves the auth handlers onto the queue by anchor, leaving all three auth files alone if any of them has been edited.

Supported images with health checks, no guessable seed accounts, private dev storage, and a faster admin

Supported, pinned base images with health checks. The API runtime moves from Alpine 3.19, which is out of support, to Alpine 3.24, Node is pinned to 22.23 and nginx moves to 1.30. All three images (API, web, admin) now carry a HEALTHCHECK, where none did; the API's calls /api/health. The Next.js runtime image starts from a clean Node image with npm, corepack and yarn removed, instead of inheriting pnpm from the build stage, and Dependabot opens pull requests for the base images.

One pnpm everywhere. The Dockerfiles installed pnpm 9.15.0 whilepackage.json named pnpm 10.0.0, so image builds ignoredonlyBuiltDependencies and ran every dependency's install script. Both now use pnpm 10.33.4. Not the newest 10.x on purpose: from 10.34.0 pnpm refuses a tarball dependency whose lockfile entry has no integrity hash, and pnpm 10 never records one for the SheetJS CDN tarball the web app installs xlsx from, so a fresh project could not install at all.

No guessable accounts outside development. grit seed createdadmin@example.com with the password admin123, plus four demo accounts, in any environment not spelled exactly "production", so a staging database got five guessable logins. Those accounts are now seeded only with APP_ENV=development. Anywhere else the seeder needs a SEED_ADMIN_PASSWORD of at least 12 characters and skips the demo users.

Maintained dependencies. The two-factor QR code now comes fromboombuler/barcode v1.1.0, which has no dependencies, in place ofskip2/go-qrcode, unreleased since 2020. gorilla/mux, which the social sign-in library still requests at v1.6.2 from 2018, is pinned to v1.8.1.

Development storage stays on your machine. Dev MinIO answered on every network interface, so anyone on the same network could reach the bucket. Its API now listens on 127.0.0.1 unless MINIO_BIND_ADDRESS says otherwise, and its console always does. Projects with the Expo app need the phone to reach it, so they get MINIO_BIND_ADDRESS=0.0.0.0, andgrit upgrade adds that line to an existing Expo project's .env so its images keep loading.

A faster admin. Tables checked every row against the whole selection and redrew every row when one box was ticked: on a 200-row, 5-column page that was 1,000 cells redrawn per tick, and it is now 5. usePermissions builds its permission set once per fetch and returns the same can function every render, so components depending on it stop re-running their effects. The upload dropzone releases the preview URLs it creates, where picking three files used to keep all three in memory for the life of the page. Each route now preloads one font file (48 KB) instead of two (80 KB), and the generated CSS has 13 font rules instead of 46.

No invented numbers on the dashboard. The "Activity, past 7 days" chart plotted Math.random(), because no API endpoint counts activity per day. It is gone, along with its dashboard setting, and "Recent activity" sits beside "Severity mix" in its place, both showing real data.

grit upgrade patches existing Dockerfiles, package.json, the compose file, the seeder and a single app's main.go, and swaps the QR library; the admin fixes arrive with the rest of the admin files.

GDPR erasure needs a reason, the API address lives in one place, and four admin screens use hooks

A GDPR erasure now needs a reason. The handler ignored its request body, so a call with no body at all erased an account and wrote an empty reason into the deletion journal. It now answers 422 unless the reason is 3 to 500 characters, identifies the caller withauthz.CurrentUserID, and writes its audit row throughservices.LogActivityErr: if that row cannot be written, the response says so instead of reporting a clean erasure. The admin's confirm button stays disabled until a reason is typed. An erase call that sends no reason, which used to succeed, is now refused.

The API's address is written in one place. A new lib/api-core.tsexports API_URL, apiUrl(), createApiClient() andgetApiErrorMessage(), and both frontends build their client from it. Copies of the environment expression went from 15 to 7, and hand-built URLs that skipped the /api/v1prefix from 8 to none: public forms, the OAuth buttons, SSO discovery, and the SAML URLs an admin pastes into their identity provider. /api/health now also answers at/api/v1/health, so the admin's System Health page no longer reads a 404 as degraded.

Four system screens go through hooks. Form shares, access reviews, SSO and API keys made 21 API calls inline from their pages; they now make none, through four new hook files. The observability and security screens poll with useQuery instead of asetInterval loop that also hid the browser's own fetch.

Less copy-pasted error handling. getApiErrorMessage(err, fallback)replaces the error cast in the resource hooks, the toasted-mutation hook, the roles page and the auth pages, taking the copies from 26 to 17, and the four near-identical resource mutations are one factory.

Three oversized functions got smaller. routes.Setup went from 966 lines to 703: the middleware chain, Sentinel, Studio, Pulse and the public auth routes are named functions. registerAPIDocs went from 567 lines to 40 plus seven section functions, andLogin from 189 to 111. The route groups with grit: markers stay inSetup, because plugins and generated resources insert code there that uses its variables.

grit doctor is quiet on a fresh project again. v3.282.0 moved the built-in users and ticket lists onto paginate, and doctor had been recognising a generated resource by its list config. So every project fresh from grit new reported User and Ticket as resources, with an error about encryption keys and a warning about ownership, neither of which applied. A generated resource is now recognised by its bulk request, which the generator has written since v3.142.0 and no built-in declares.

grit upgrade fixes the GDPR handler and registers the versioned health route in existing projects, and delivers the new frontend files with the rest of the frontend.

Race-free signups, working user filters, tickets that do not leak, honest dashboards, and errors.Is everywhere

A duplicate email is a conflict, not a race. Registration and the admin's Create User both looked the email up and inserted only when nothing came back. Two signups for the same address arriving together both passed that check, and the one that lost at the unique index got a 500. Both now insert through services.CreateUser, which lets the index decide and answers a duplicate with 409 EMAIL_EXISTS. Updating a user is one transaction: the role assignment used to be committed first, so a failed row update left the account with the new role's permissions while users.role still showed the old one. The two reloads that ignored their error now report it instead of returning the row as it was before the update.

The users list goes through paginate, and its filters work. 65 lines of hand-written paging are gone, including a Count whose error was thrown away, so a failed count showed a total of 0 above a full page of rows. The list now reads ?role=,?active= and ?provider=. Before, the admin's Role and Status filters had no effect, and the Active Users card showed the total number of users. The ticket list applies its latest-activity order only when the caller asks for no other sort, so ?sort_by=priorityno longer only breaks ties, and ticket search ignores case, so on Postgres "Billing" finds tickets filed as "billing".

One visibility rule for tickets, answering 404. Get, Reply, Assign and the close and reopen actions each had their own copy of the rule, and each answered someone else's ticket with a 403, which confirms the id exists. The owner check is now part of the query, so a ticket you cannot see looks exactly like one that does not exist. The notification scope was written out three times and missing from MarkRead, so any signed-in account could mark any notification as read by its id. One helper now covers all four paths and answers 404 for notifications that are not yours. Role checks in those handlers use models.RoleAdmin instead of the string "ADMIN".

The security and performance dashboards say when Sentinel or Pulse is down. Seven upstream calls threw their errors away, so a dead service rendered as a 200 full of zeros: no banned IPs, no threats, no errors, which reads as safe and fast. Each response now carries adegraded list naming the calls that failed, and the admin pages show it in a banner. When nothing answers at all, the endpoint returns 502 with SENTINEL_UNAVAILABLE orPULSE_UNAVAILABLE, both in the error code catalogue.

Sentinel errors are compared with errors.Is. A generated API had 27 comparisons against errors such as gorm.ErrRecordNotFound using ==, plus twoswitch err blocks. Each one stops matching the moment someone wraps the error with%w, which quietly turns a 404 into a 500, and wrapping is exactly what a careful developer does. All of them now use errors.Is, including the generated tests and the cache'sredis.Nil check, and .golangci.yml turns on errorlint's comparison check, which reports nothing on a fresh project.

No more false alarm about the realtime hub. On any project already on v3.281.0,grit upgrade warned that internal/realtime/hub.go "does not send the way Grit wrote it" and could panic, about a hub that was exactly as Grit wrote it. The check predated the counted sends v3.281.0 introduced and recognised neither form. It now accepts them, and nothing in the file changes.

grit upgrade patches the user and auth handlers where they still read as Grit wrote them, refreshes the ticket, notification, security and observability handlers (an edited copy is reported as a conflict, not overwritten), and rewrites sentinel comparisons across apps/api/internal, tests included.

Client events between browsers, a hub that reports itself, and no panic on a revoked session

Client events. A channel could only carry what the server published, so "Ada is typing" cost a POST per keystroke or was never built. A connection subscribed to a private or presence channel can now send a client event, and the hub relays it to the other subscribers of that channel on every replica, storing nothing:

{"type":"client-event","channel":"presence-rooms.1","event":"typing","payload":{"typing":true}}

The hub fills in user_id from the connection's token, so a receiver can trust who sent one. The rest is the sender's browser talking, so treat it as user input. The rules are the server's: private and presence channels only, whose subscribers passed an authorizer; only a channel this connection is subscribed to; ten a second per connection; a payload under 1 KB; and an event name of 1 to 64 characters. A refusal comes back on the sender's socket alone, and the rate limit answers once a second however many it drops. The socket read limit goes from 1024 to 2048 bytes to fit one. Every frontend gets whisper() and a useWhisper hook, and a handler keyed client-event:typing sees one kind and ignores the rest.

The numbers the hub had and never showed. A hub that dropped a message for a slow client said so in a log line and nowhere else. /api/health now carries arealtime object: this replica's open sockets, distinct users and channels, and counters for messages sent, messages dropped for slow clients, client events relayed, client events refused by the rate limit, and events that never reached the other replicas. The admin's System Health page shows it as a sixth card. The three counts are per process, so with several replicas each reports its share.

A revoked session no longer panics a connecting socket. Connect queued its "you are connected" greeting after the hub had taken the connection, so a session revoked in that instant closed the send channel underneath it and the send panicked, taking the API down. 300 sockets signed out as they were admitted panicked 7 times on v3.280.0 and 0 times now. The greeting is queued before the hub can reach the connection at all.

Docs and the chat course. The realtime page documents channels, presence, client events and the health numbers, and corrects three things that were wrong: the ping interval is 54 seconds, a browser authenticates with the grit_access cookie rather than a query string token, and the socket takes three kinds of message rather than none. The realtime chat course is rewritten on the scaffolded hub: it used to tell readers to install a separate plugin with its own routes, which is a second hub with a second connection and no share of the application's authentication. It now builds rooms as authorized channels, a member list from presence, typing indicators from client events and history from REST, with 12 challenges against a project that installs nothing.

Storage helpers, named disks, private files that stay private, and AWS S3 with no endpoint

Store and serve files in one call. storage.Store andstorage.StoreAs save a form upload under a generated<dir>/<yyyy>/<mm>/<uuid><ext> key. They sniff the real content type (HTML and SVG are always refused), enforce a size limit and return the key.storage.ServeFile streams a stored file through the API with Content-Type, Content-Length, Last-Modified, inline or attachment disposition, 304 and single-range 206 support; on S3 a range is one ranged GET. The upload handler now uses them, so the name a file arrived with never reaches a storage key, and the new GET /api/v1/uploads/:id/download serves any upload the caller can see, private files included, on every driver. A range outside the file answers 416 with the new RANGE_NOT_SATISFIABLE code, which is in the error code catalogue.

Named disks. STORAGE_DISKS=backups withSTORAGE_DISK_BACKUPS_BUCKET opens a second store, reachable throughstorage.Disks.Get("backups"). The Data & Backup page, scheduled backups and grit backup write archives there when it exists, and older archives on the default disk still download and prune. grit backup now opens the storage the API uses: withSTORAGE_DRIVER=local it used to exit withbucket "" not accessible, and now writes the archive.

Visibility. PutOptions.Visibility states whether a file is public or private, and Put refuses a key whose prefix says otherwise, so a private file cannot land where anyone can read it. STORAGE_PUBLIC_PREFIXES sets the public prefixes (default uploads/,thumbnails/) and the bucket policy follows them. Cloudflare R2 and Backblaze B2 have no bucket policies, so there private files belong in a private bucket, served with a temporary URL.

Upright thumbnails. Thumbnails for presigned uploads, and for images the upload pipeline skipped, now go through the media pipeline: EXIF orientation applied, metadata stripped, at 400px. A portrait phone photo used to get a sideways 300x300 thumbnail; it now gets an upright 400x400 one.

AWS S3 without an endpoint. STORAGE_DRIVER=s3 with noS3_ENDPOINT now connects to the AWS regional endpoint, and with no access key the SDK credential chain (an IAM role) is used. Before, the API silently skipped storage and every upload answered STORAGE_UNAVAILABLE.

A clean security scan for the image API. v3.279.0'sDominantColor tripped gosec in generated projects (an 8-bit conversion it could not prove safe, and an index it could not bound). It is rewritten so the scan passes, with the same result.

The file storage docs are rewritten to cover drivers, local development, the Disk interface, the helpers, named disks, visibility, the presign fallback, file lifecycle and the real endpoints.grit upgrade updates config.go, main.go, routes.go, cmd/backup and .env.example in existing projects.

Work on images in code, and one-sided resizes that no longer produce empty images

A chainable image API. The media package could only run an upload through a fixed profile, so a handler had no way to crop, rotate, blur or inspect an image itself.media.Open(r), media.FromDisk(ctx, disk, key) andmedia.FromURL(ctx, url) now return an image with Cover,Fit, Resize, Crop, Rotate,FlipH, FlipV, Grayscale, Blur,Sharpen and Orient. Width, Height,MIME, Extension and DominantColor inspect it, theTo... methods pick the output format, and Encode orStore(ctx, disk, "avatars", media.PublicFile) finishes it and returns the stored key.

Every step returns a new image, so one decode can feed several outputs, and an error anywhere comes out at the end. The pixel limit is checked on the header and after any step that can grow an image, and all pixel work shares the per-CPU limit uploads already use. FromURL goes through the safe fetch client with a 20 MB and 10 second default, so loopback and cloud metadata addresses are refused before a connection is made. Lossy WebP and AVIF need the libvips build; without it they return an error naming -tags vips instead of quietly writing a lossless file. No new dependencies, and no cgo in the default build.

One-sided sizes keep the aspect ratio. media.Fit(800, 0) on a 2000x1000 photo produced an empty 0x0 image with no error, and it would have been stored. It now gives 800x400, and Fill(800, 0) scales the same way, on both the pure Go and libvips backends.

The Image Optimisation docs gain a section on the chain, and grit upgrade delivers the new media files with the rest of the media package.

Mail: queued sending, grit generate mail, and a preview of the real templates

Queued mail. mail.Queue(ctx, jobs, message) sends any message through the background worker, which retries a provider that is briefly down. The job existed all along with nothing able to use it. Attachments over 256 KB in total are refused with an error telling you to store the file and send a link, because a queued message waits in Redis for every retry. In a fresh project, a queued message with an attachment reached the local inbox through the worker, and a 300 KB attachment was refused before it reached the queue.

grit generate mail. grit generate mail OrderShipped writes a typed email: a data struct, a body inside the shared mail layout, a plain-text part, andSendOrderShipped and QueueOrderShipped helpers. It registers itself for the admin's Mail Preview.

Mail Preview shows what the API sends. The admin page used hand-written copies of four templates. It now renders the real ones from GET /api/admin/mail/templates and/api/admin/mail/preview/:template, staff only. The preview matched the Go render byte for byte, generated templates appear on their own, and a non-staff account gets 403. System Health names the mail driver in use instead of saying Resend.

Two quiet failures fixed. Adding a recovery email claimed a code had been sent even when sending failed; it now answers 502 MAIL_FAILED. Turning off notification emails in Settings now stops the new-ticket email, which ignored the setting.

grit upgrade now brings the mail drivers, queueing and the preview to single-binary projects too; before, its API repairs only ran for projects with a separate API app. The email docs, the generated project docs and the AI skill file describe the drivers, queueing, the test fake and the generator, and no longer show APIs that do not exist. The cloud .env template lists the mail driver keys.

Realtime presence, and a crash when a socket closed mid-send

A message sent while a connection was closing could crash the API. The realtime hub picked its recipients under a lock and sent after releasing it, so a connection that closed in between turned the send into a "send on closed channel" panic, which stops the whole process. Sends now happen under the lock and never block. In a stress test of 50 rounds of 200 closing connections, the previous hub crashed 3 runs out of 3; the fixed one completed 2,000 sends against 10,000 closing connections with no panic. Revoking a user's sessions also no longer panics ten seconds later for a connection that has no socket.

Presence channels. Channels named presence-* now know who is in them. A subscriber receives the member list right after subscribing, and everyone else is told when a user joins or leaves, once per user however many tabs they have open. An authorizer can attach a name or avatar with c.SetInfo. With Redis, every replica sees the same list, and the members of a replica that dies leave on their own once their entry expires, 45 seconds by default. In a two-server test, a closed socket's member left in 17 ms and a dead server's member left in 3.9 seconds with a 4 second expiry. The React hook usePresence(channel) returns the list in the web app, the admin panel and the Expo app.

grit upgrade repairs the hub in existing projects and adds presence to projects that already have channels.

Storage behind a Disk interface, and a local driver

A Grit project without MinIO credentials answered every upload with 503STORAGE_UNAVAILABLE, so trying uploads in development meant running MinIO first. Storage now sits behind a Disk interface (put, get, exists, stat, delete, copy, move, list, URL and temporary URL) with two drivers: S3-compatible buckets andSTORAGE_DRIVER=local.

The local driver. Files live in STORAGE_LOCAL_ROOT (defaultstorage/app) and are written atomically. Keys that try to leave the root are refused. The API serves uploads and thumbnails from /files, with Range support, and serves any other file only through an HMAC-signed temporary URL, which answers 403 once it expires. Outside production, a project without MinIO credentials uses the local driver automatically; production refuses it unless ALLOW_LOCAL_STORAGE_IN_PRODUCTION=true.

Uploads keep working. When storage cannot presign a direct upload, the presign endpoint says so and the upload package sends the file to POST /uploads instead, so the upload UI works on either driver.

On a fresh project with no MinIO credentials, an upload went from 503 to 201, and the file was then served (200, and 206 for a range), served through a signed URL (200), refused once the URL expired (403) and deleted. The same checks pass against MinIO, and a project on MinIO behaves exactly as before. *storage.Storage keeps every method, so existing handlers and generated resources compile unchanged. grit upgrade adds the driver to existing projects.

Mail drivers: SMTP, Resend, Mailgun, Postmark, SendGrid, Amazon SES, log and failover

Email could only go through Resend, and a new project with no Resend key sent nothing at all: a password reset wrote its link to the log, and the Mailhog in docker compose received nothing. The mailer now sends through a driver picked by MAIL_MAILER: smtp,resend, mailgun (US or EU), postmark,sendgrid, ses, log or failover. They use the standard library only, with no vendor SDKs.

Development mail arrives in Mailhog. With no driver set outside production, mail goes to Mailhog over SMTP and falls back to the log and storage/mail when Mailhog is not running. In a fresh project, one password reset delivered 2 emails to the local inbox where it used to deliver none.

Nothing breaks for existing code. A project that only setsRESEND_API_KEY keeps sending through Resend, and mail.New,Send and SendRaw work unchanged. The new SendMessage adds several recipients, cc, bcc, reply-to, a text part, attachments and custom headers.

Safe by default. A driver named without its keys stops startup with a message naming the missing keys. HTTP drivers retry once on a network or server error and never on a rejected message, and a Resend retry cannot send twice. Production refuses the log driver unlessMAIL_ALLOW_LOG_IN_PRODUCTION=true. /api/health reports which driver is in use.

Testing mail. The new mailtest package gives tests a fake mailer that records messages, with AssertSent and AssertNothingSent. New projects use it to test the password reset and verification emails.

grit upgrade brings the drivers to projects with a separate API app. Single-binary projects keep working on Resend and get the drivers in new projects only.

Realtime channels with authorization

The realtime socket could send to one user or to everyone, so a page had no way to follow a single record, and an app could not reach whoever is allowed to read it. Clients can now subscribe to a named channel, and the server answers subscribed, subscription_error orunsubscribed.

Authorization. Register who may join a channel withrealtime.Channel("invoices.{id}", authorize). public-channels are open to any signed-in connection; private- and presence-channels admit only users the authorizer accepts, and a channel with no authorizer is refused. A connection may hold up to 100 channels.

Publishing across replicas. hub.Publish(channel, event) reaches subscribers on every API process through the Redis backplane, andservices.RealtimeChannels can route resource events to channels.SendToUsers and RealtimeAudience work as before.

Clients. The web, admin and Expo clients gainsubscribe(channel, handlers), which returns an unsubscribe function, and theuseChannel hook. After a reconnect they subscribe again on their own.

In a live check with two API processes sharing Redis, 5 of 5 channel events crossed replicas, an unauthorized user received none, delivery stopped after unsubscribe, and a client whose connection dropped got its channel back without calling subscribe again. grit upgrade adds channels to existing projects and warns instead of rewriting a hub that has been edited.

Realtime: the WebSocket refuses other origins, the module switch works, and connections are capped

Another page could open a signed-in user's socket. The WebSocket accepted a handshake from any origin while authenticating it with the grit_access cookie, which the browser sends whichever page opens the socket. A page on another origin could connect as the signed-in user and read their live events. A cookie handshake is now accepted only from an origin in CORS_ORIGINS (or the cors.origins setting) or from the API's own host, and refused with 403 otherwise. Clients that authenticate with ?token= or anAuthorization header, such as mobile and desktop apps, are unaffected, and the socket now accepts the Authorization header. On a test project, an attacker page opened the victim's socket before the fix and was refused after, while the admin panel's own origin still connected.

MODULE_REALTIME=false turns realtime off. The flag hid the UI, but/api/ws stayed mounted and the Redis backplane stayed subscribed. With the flag off,/api/ws now answers 404 and the API holds no realtime subscription.

Connections are capped. Each user may hold 10 sockets and each process 10,000, set with REALTIME_MAX_CONNECTIONS_PER_USER and REALTIME_MAX_CONNECTIONS. A socket past either cap is closed with code 1013 and logged. One user opening 12 sockets held 12 before and 10 after.

grit generate resource finds the realtime hub again. It looked for a line routes.go stopped containing when the hub gained options, so a project without the event bus got a warning instead of having it started.

grit upgrade adds the origin guard and repairs routes.go and the realtime handler in existing projects, and says so when those files were edited and need the change by hand.

Connection pools, the response cache, and a lighter admin panel

Five more findings from the contact-app review, each measured on a generated project before and after upgrading, and two bugs found while fixing them.

Upgrading a project with the admin panel inside its web app dropped your resources from the panel. Upgrade wrote the template over admin-panel/resources/index.ts, so every resource added with grit generate disappeared from the admin while its definition and pages stayed on disk. Upgrade now leaves resource definitions, their pages and the registry alone, in the web app's panel and in a single app's. If an earlier upgrade already dropped them, this one registers them again and says which.

A generated API could open more database connections than Postgres allows. Each process allowed 100, and Sentinel opened up to 10 more on the same database. Under load, one process held 96 connections and 153 requests failed when Postgres refused more. The app pool now defaults to 25 (DB_MAX_OPEN_CONNS) and Sentinel's to 5 (SENTINEL_DB_MAX_OPEN_CONNS): the same load held 31 connections with no errors, and three replicas held at most 91. In production the API now connects through pgbouncer, where three replicas used at most 20 Postgres connections. pgbouncer also listens on the port its health check probes; before, that check could never pass.

An expired cache entry sent every waiting request to the handler. Of 100 requests arriving together at a cold key, between 13 and 71 ran the handler. Now one does, and the rest share its response. Entries also stored the body as base64 inside JSON; they now store it as sent, so a 6,004-byte response takes 6,040 bytes in Redis instead of 8,081. Clients see the same status, headers and body on a hit.

The admin asked for the same data under different query keys. The dashboard's stat card and latest table each fetched a resource's stats, and the dashboard and the notification bell both polled notifications. A dashboard with five resources made 17 requests on load and 15 a minute while idle; it now makes 11 and 9, with no duplicates. Tab counts are queries that refresh after a create or delete, and a list with three count tabs loads with 4 requests instead of 7. Relationship pickers fetch their options when opened and search on the server, and the multi-select picker shows records created elsewhere instead of a list up to five minutes old.

The admin's React Query client was shared by every server render. It was created when its module loaded, which becomes a leak between users the moment anything prefetches. The admin now creates its client once per mount, in all three admin shapes, and admin pages inside the web app no longer build a second, unused client.

Every form loaded the rich text editor. Tiptap and ProseMirror came with any page that could open a form, and with the blog editor. They now load when the editor appears: a user's detail page went from 1,347 KB (418 KB gzipped) to 824 KB (260 KB), the blog editor from 1,228 KB to 815 KB, and the Vite admin's entry script from 1,503 KB to 978 KB. The editor still opens and saves.

The blog editor could not save. It saved, published and deleted through/api/blogs/:id, which the API does not serve, so each of those returned 404. It now uses /api/admin/blogs/:id, and grit upgrade fixes the editor page in existing projects.

Background work: audit and activity writes, sync pushes, the outbox relay, cleanup jobs

Five more findings from the contact-app review, each measured on a generated project before and after upgrading, against Postgres, MySQL and MinIO.

The audit writer inserted one entry at a time while holding the chain lock. Every replica's writer waits on that lock. A batch is now chained in memory and written as one multi-row insert: 2,560 entries took 69 statements and 3.8 seconds instead of 2,920 statements and 9.0 seconds, and the chain verified.

A sync push had no size limit and ran three queries per change. A push now carries at most 500 changes; a larger one is refused with 413 TOO_MANY_CHANGES. The rows it updates or deletes are read with one query per model rather than one per change: 500 updates ran 501 queries on the table instead of 1,000 (and took 5.7 seconds instead of 12.7, with 88 activity inserts instead of 500). The web and desktop sync clients now send their outbox in pushes of 500, and grit upgrade updates both. An app already installed on a device, built before this release, with more than 500 changes queued will be refused until it is rebuilt. Changes in a push are still applied without a shared transaction: each one stands on its own, and a savepoint per change overflows Postgres's subtransaction cache.

Every create, update and delete waited on an activity-feed insert. The row is still built in the request, where the IP address and user agent can be read, and is now written by a batching writer. Emitting 1,000 events took 0.02 ms each instead of 10 to 11 ms (and all 1,000 rows were stored within a quarter of a second). The server writes whatever is still queued when it shuts down. Sign-ins and other security events are still written before the request returns.

The outbox relay was never pruned, blocked other replicas, and could not be stopped. Claims now use SKIP LOCKED: on Postgres, a second relay claimed the free messages at once instead of waiting 3.2 seconds for the rows another relay held. On MySQL a claim's locking read covers every row it scans, so the second relay no longer waits but claims nothing until its next poll. SKIP LOCKED needs MySQL 8.0 or MariaDB 10.6. The relay now deletes delivered messages older than seven days, in chunks, about once an hour; 100 delivered messages a month old were all still there before and none after. On shutdown the server stops the relay, and messages it had claimed but not tried go back to the queue instead of waiting out the five-minute claim timeout on another replica.

Cleanup and scheduled jobs were unbounded and retried 25 times. The orphan upload cleanup now works 1,000 uploads at a time and deletes their files with one storage request per page: 2,500 orphans took 3.9 seconds, 7 statements and 3 storage requests instead of 48.6 seconds, 2,502 statements and 2,500 requests. The built-in scheduled jobs retry 3 times with a deadline, and so do jobs made with grit generate job --cron. The activity-log prune deletes 5,000 entries per transaction (pruning 100,001 of 200,000 entries took 1.2 seconds with no transaction longer than 132 ms, where the single DELETE it replaces took 210 ms and grows with the backlog).

Pruning the activity log broke its verification. Found while measuring the prune: it rewrote the hash of the oldest remaining entry, and the entry after it still pointed at the old hash, so every prune that deleted anything left a log that failed verification. Remaining entries now keep their hashes, and each prune appends a security entry naming where the log now starts. Verification accepts a log that starts after deleted entries only when a prune recorded it: after pruning 100,001 of 200,000 entries the chain verified, and deleting the 10 oldest remaining entries by hand was reported as a break.

Performance under load: request context, flags, API keys, dashboard stats, images

Five more findings from the contact-app review, each measured on a generated project before and after upgrading.

Database calls ignored the request's context. A request the client had abandoned kept its queries running and its connection held. Database calls in the handlers now carry the request's context: 157 calls across the handler templates, and in methods that take the request as their first argument. The auth middleware's user lookup and API key check do too, and the three background jobs that write use the job's context. grit upgrade applies the same change to the handlers Grit wrote. Thirteen calls sit in methods that are never given the request, such as the failed-login counter, and are left as they are.

Every feature flag check started a goroutine and an INSERT. Checking one flag 2,000 times for one user wrote 2,000 exposure rows. Exposures now go to one writer through a bounded queue, are written in batches, and are recorded once per user, flag and variant per day; the same 2,000 checks write one row. When the queue is full an exposure is dropped rather than slowing the request.

API key requests queried the key twice each. Fifty requests with one key ran fifty lookups and fifty last_used_at updates on the same row. A verified key is now trusted for 30 seconds, and its last use is recorded at most once a minute: the same fifty requests ran one of each. Revoking a key clears it on the replica that revoked it; another replica can accept it for up to those 30 seconds.

Dashboard stats loaded a month of rows to count them. The stats and chart widgets read the timestamp of every record created in the last 30 days and counted per day in the API. They now count per day in the database, for SQLite, Postgres and MySQL. With 50,009 users, the users widget went from 1,905 ms to 406 ms, and 208 ms once warm; its daily query went from loading 50,009 rows to returning 30. On all three databases the new counts and sums matched a count done row by row. Days are now UTC days.

Image uploads had no limit on concurrent work. Each image is decoded whole, about 200 MB at 50 megapixels, and uploads arriving together each decoded at once. Decoding now runs at most once per CPU at a time, and an image's extra sizes upload four at a time instead of one after another. The review also flagged the transparency check as reading every pixel slowly; for the images the decoder produces, Go's own check already reads the pixel bytes directly, so that was left unchanged.

Deployment hardening: images, the production stack, CI and the admin gate

Five more findings from the contact-app review, checked on a generated project before and after upgrading.

Docker images carried local state. The .dockerignore patterns only matched at the root of the build context, and the API builds from apps/api, which had none. Its build context was 179 MB and put the development database, the Sentinel database and three local binaries into the image. The patterns are recursive now, apps/api has its own file, and the same context is 862 KB with none of them in it.

The production stack ran on SQLite. The API took DB_PROVIDER=sqlite from the development .env, so the database lived inside the container and a redeploy started from nothing while the Postgres beside it sat unused. The production compose file now sets Postgres, and an API started with APP_ENV=production on SQLite refuses to start unless ALLOW_SQLITE_IN_PRODUCTION=true says the file is on a volume you back up. A deployment that runs SQLite in production on purpose needs that line after upgrading. Redis now takes a password, REDIS_PASSWORD, generated into .env for new projects; grit upgrade says to add one to an existing .env, and compose refuses to start the production stack without it. PgBouncer and MinIO run pinned versions, and MinIO now comes from quay.io: Docker Hub no longer serves the minio/minio image both compose files used.

CI could be changed from outside the project. Every action in the generated workflows is pinned to a commit, with its version beside it for Dependabot. The release workflow is read-only by default and only its publishing jobs can write or sign. Syft is installed from Anchore's pinned action instead of a script downloaded at release time, the Wails CLI has a version, and golangci-lint is pinned to v2.13.2 with an action that can run it: the shipped .golangci.yml is a version 2 config, which the previous action could not load. grit upgrade now also updates a ci.yml that Grit wrote.

The admin was guarded only in the browser. A visitor who never signed in loaded every admin page, and a user with no permissions could open System pages. The API now sets grit_signed_in, a marker with no secret in it, and the web app's middleware sends a visitor without it to the login page before any admin page loads. Browsers only share it when the web app and the API are on the same host, so on separate hosts the middleware stands aside and the page's own check applies. A user with no permissions is sent to their profile from any admin page. Before, /admin/system/roles answered 200 with no cookies; now it redirects to the login page.

SAML metadata skipped the SSRF guard. The metadata URL an administrator enters is now fetched through the same guard as every other server-side fetch, so it cannot reach loopback, private or cloud metadata addresses.

Account security: replays, provider sign-in, user records and profile changes

Five findings from the contact-app review, each reproduced on a generated project first.

An Idempotency-Key replayed another user's response. The cache that makes retries safe keyed each stored response on the method, the path and the key, and answered before authentication. Anyone who learned a key got the stored response: sending only a user's key, with no credential at all, replayed the 201 that created their API key, secret included. The key now includes a hash of the credential the request carries, a request with no credential is never replayed, and sign-in and API key routes are never cached. After upgrading, the same request gets 401.

Signing in with Google or GitHub could inherit a planted account. The callback linked the provider to any account with the same email and left its password working, so someone who registered the victim's address first kept password access after the victim signed in with the provider. Linking to an account whose email was never confirmed now clears its password and ends its sessions first, and a provider that shares no email is refused. The OAuth cookie store also has its own key, derived from the JWT secret rather than being it, and an HttpOnly, SameSite=Lax cookie that is Secure over https.

Any signed-in user could read any user's record, email, role and IP address included. GET /api/v1/users/:id now takes users.view, like the user list; your own record is GET /api/v1/profile. It went from 200 to 403.

A stolen session could change the password and the email. Changing either now takes the current password: without it the answer is 422, with a wrong one 401. A new email is checked against other accounts first, where it used to fail with a 500 from the database, is unconfirmed until confirmed, and signs out every other session. An account with no password, one made through a provider, changes these through a password reset instead. The admin profile pages and the web account page ask for the current password and show the API's reason when a change is refused. The old address is not yet notified of the change.

The fifth finding, the xlsx package with two known vulnerabilities, was already fixed in v3.259.0, which moved every template to the patched SheetJS build. grit upgrade applies the four fixes to the API files Grit wrote, and leaves a note with what to change in any it cannot recognise.

The upload codes from v3.267.0 are in the error catalogue

v3.267.0 added two error codes to the upload handler, UPLOAD_KEY_FORBIDDEN and UPLOAD_ALREADY_RECORDED, without adding them to Grit's error catalogue, the list every code a generated API can return has to appear in with its status and what a client should do. The test that holds the templates to the catalogue failed, so the v3.267.0 release was never published. Both codes are catalogued now, and appear on the error codes page. The upload fix itself is unchanged: see v3.267.0.

A user can no longer claim, or delete, a file someone else uploaded

A presigned upload finishes with POST /api/v1/uploads/complete, which records the file. That call recorded whatever object key it was given, for whoever asked. A signed-in user could name another user's upload, get a row for it, and delete that row, which deleted the other user's file from storage. Naming a key outside the uploads also told them whether that object existed, and the same upload could be recorded any number of times.

Presigned keys now sit under the caller's own prefix, uploads/<user_id>/, and completing an upload accepts only a key under that prefix. The key is checked before storage is asked about it, so a refused key reveals nothing, and a key that already has a row is refused too. Nothing is kept between the two calls, so it needs no Redis. Clients that send back the key the presign returned need no change. grit upgrade delivers the upload handler. This finishes the second half of the upload access fix; listing and reading were scoped to their owner in v3.241.0.

Checked live against MinIO, with a second account. Before, it recorded the admin's upload (201) and deleted it, and the admin's file was gone from storage; a key outside the uploads answered 404, and its own upload could be recorded twice. After upgrading, the admin's key and the outside key are refused with 403, its own upload is recorded once, and the second attempt gets 409.

Server errors reach the log, and their text stops reaching clients

Many of Grit's handlers answered a 500 with the error itself. A notification that could not be marked read came back as SQL logic error: no such table: notifications (1), which tells whoever sent the request about the schema. The public /api/health endpoint did the same for anonymous callers, reporting why Redis or the database was down. Meanwhile respond.Internal, which the role and SSO handlers call, threw away the error it was given, so those 500s left nothing in the log at all. Database errors did appear in GORM's own log at its default level, but with nothing to tie them to the request that failed.

A new respond.ServerError answers 500 with the error code and a message safe for the client, and logs the cause with the method, path and request id. The id is the X-Request-ID header the client received, so a reported failure leads straight to its log line. respond.Internal and respond.WriteError go through it. Every handler template that sent the error text with a 500 now calls it instead: 38 places, plus three 400s that passed a server error through (the dashboard chart, the resource stats widget, and the public shared form submission). The health endpoint logs a failed ping and reports only that the dependency is down. Sync push results log a failed write rather than returning it to the device. Messages about the request itself, such as validation errors, are unchanged.

grit upgrade delivers the new respond package and applies the same rewrite to Grit's handlers and the health endpoint in an existing project. It only rewrites responses in the exact shape Grit generated, and a test holds every template to the rewrite.

Checked against a copy of a project's database with its notifications table removed. Before, marking all notifications read answered 500 with the SQLite error; after upgrading, it answers 500 with "Internal server error", and the log has the SQLite error under the same request id the client was given. With Redis paused, /api/health went from returning the ping error to returning only that Redis is down, with the error in the log.

A resource list is one request per view, per search and per save

Opening a resource list in the admin sent five requests: the list, and one for each of the four stat cards above it. Typing in the search box sent a request per keystroke, and each one blanked the table to a skeleton until its answer arrived, in whatever order the answers came back. Saving a record sent the list and all four cards again. On the users and blog pages three of those cards were also wrong: their handlers never read the date windows the cards asked for, so This Week, This Month and Updated Recently all showed the grand total.

The search now waits until typing pauses, and a request the next keystroke replaces is cancelled. The rows stay on screen while the next page, sort or search loads, with a thin bar above them instead of a skeleton. The default stat cards read the list response: Total is the total the table already has, and the list asks for the three windows beside it with a new?counts=created_7d,created_30d,updated_7d parameter, which paginate.List answers for every generated resource and a new paginate.Counts answers for the users and blog handlers. The cards now describe the rows the table matches, search and filters included. Saving an existing record refreshes the list and the record, and leaves any custom stat cards to refresh the next time they are shown. Custom cards set in a resource definition work as before.

grit upgrade delivers the admin files and the pagination package, and adds the counts to the users and blog handlers when they are the files Grit wrote, or says what to change when they are not. A new test in the generated project covers the counts.

Measured on the users list of a project upgraded from v3.264.0, against its API log: a page view went from 5 requests to 1, typing "admin" from 5 requests and 5 skeleton flashes to 1 request and none, and a save from 6 requests to 2, the save itself and the list.

Resource lists and the dashboard stop downloading spreadsheet and chart code up front

The admin's spreadsheet helpers imported SheetJS at the top of their module, and every resource list page imports those helpers, so about 500 KB of SheetJS arrived with every list whether or not anyone exported or imported. A comment on the list page called it lazy; it was not. The dashboard and its resource stat cards imported recharts the same way, adding about 400 KB to the dashboard's first load.

SheetJS now loads the first time a spreadsheet is written or read. CSV export needs none of it and still downloads inside the click. The dashboard's two charts and the stat card's sparkline moved into modules of their own that load after the page renders, behind a placeholder, so the greeting, stat tiles and activity feed do not wait for them. This applies to the Next.js admin, the admin inside the web app and the Vite admin, where the charts sit behind Suspense. grit upgrade delivers the changed files and the two new chart modules to projects that have not edited them.

Measured on a fresh project, then again after upgrading it, by fetching each page and adding up the scripts it asks for. The users list went from 1,352 KB (432 KB gzipped) to 861 KB (270 KB), with SheetJS gone from it; the dashboard went from 1,241 KB (366 KB) to 836 KB (261 KB), with recharts gone from it. In the browser, SheetJS arrived only on clicking Excel export, which still produced a valid workbook, the import template still downloaded, and all four dashboard charts rendered.

Admin pages start loading without waiting for the signed-in user

The admin layout showed a spinner in place of the page until /auth/me answered, so no page request could start before it did. The permissions request lived in the sidebar, which also waited for the user. Every full load of an admin page paid for one whole round trip before its lists, stats and widgets were asked for.

The page now renders straight away behind a loading overlay, and the layout asks for permissions beside /auth/me instead of after it. The overlay stays until the user is known, and a signed-out visitor is still sent to the login page: the page's own requests are refused with a 401, and the API client makes one refresh attempt before it redirects. Pages render on the first pass in the browser rather than on the server: admin pages read browser state while rendering, and prerendering them failed the build. The route group layout is no longer marked "use client", since the admin layout is already the client boundary. grit upgrade delivers both files to projects that have not edited them.

Measured on a fresh project against a local API, then again after upgrading it. On the dashboard, the first page request started 376 ms after /auth/me finished; now all ten start within 30 ms of it starting, most before it finishes. On the users list, permissions now start together with /auth/me, and the list query starts 78 ms after it finishes instead of 372 ms. Against a slower API the saving grows by the length of that request.

Removing the blog leaves an API that compiles

The other half of what v3.260.0 found. After grit remove resource Blog, the web app built again, but the Go API did not: removal reported the API reference entries gone while six of the seven were still there, naming a model and two request types it had just deleted, and the blog's public route group stayed in routes.go with its routes taken out, an unused variable Go refuses to compile. The same failure happens with v3.257.0, so it is older than the pages that turned it up.

Removal matched an API reference entry only when its path was the resource's base or the base followed by /:id. The blog documents /:slug, and its admin endpoints sit under /api/v1/admin/blogs. It now removes every documented path under the resource's base, and under its admin base, and still stops at a path segment so removing order leaves orders alone. It also removes a route group declared on the versioned group, which is how the scaffold declares the blog's, together with its comment.

Checked on a fresh project: after removing the blog, no reference to it is left in the API reference or the routes, and the API builds, passes vet and passes its tests.

Two migrations in the same millisecond no longer collide

Found by CI rather than by the review. The live suite for v3.260.0 failed once in the migration history's own tests, with UNIQUE constraint failed: grit_migrations.id, and passed when the job ran again. A recorded run's ID was the time to the millisecond, so two runs recorded within the same millisecond had the same ID. The test records a run and then another straight after, and on a fast machine both could land in one millisecond. A test that recorded two runs back to back failed on the second one every time.

A run's ID is still the time it was recorded, in the same format, so a history from an earlier version reads and sorts as before. When that time is not later than the latest recorded run, as with two runs in one millisecond or a clock that stepped back, the new run takes the next millisecond after it, so IDs are unique and always in order. A test now records fifty runs back to back and checks each ID comes after the last.

grit upgrade delivers the fix and the test with the rest of internal/migrate.

The home page and blog render their posts on the server

The next finding from the review of a scaffolded app. The home page, the blog list and every blog post in a Next.js project were client components that fetched their posts after the JavaScript loaded. The HTML the server sent held loading skeletons and no posts, which is what a search engine indexed and what a reader saw first, and all three pages shared the site's one title. Checked against a running project: the seeded post's title appeared in the server HTML of none of the three pages.

They are server components now, reading through lib/blog-api.ts and refreshed every minute. The blog list pages with links (/blog?page=2), a post has its own title, description and share image, and a missing slug is a real 404. Server-side, DOMPurify has no page to work with, so the API's public blog endpoints sanitise the HTML they serve, which also covers posts stored before the API sanitised on write. In production Docker the web container reaches the API by service name through API_INTERNAL_URL. An API that cannot be reached, as during a CI build, leaves a list empty rather than failing the build. The same check afterwards: the post is in the server HTML of all three pages, each with its own title.

Checking grit remove resource Blog against the new pages found it broken before this release. It still looked for the home page at the app root, which moved into a route group in an earlier release, and it never deleted the blog pages, so removal left the home page and both blog pages importing files it had deleted, and the web app failed to build. It now cleans the home page where it is and deletes the blog pages. The API still fails to compile after removing Blog, because the API reference and the route group keep references to it; that is a separate bug, older than this release, and next on the list.

grit upgrade delivers the pages and lib/blog-api.ts where they are unedited, and adds the sanitising to the blog handler and API_INTERNAL_URL to the production compose file where those are still what Grit wrote. TanStack and single-app frontends are single-page apps with no server rendering, so they are unchanged.

A project's CI scans its real code, runs its tests, and releases

The next finding from the review of a scaffolded app. Every generated project gets Dependabot and a security workflow, and both were written for the single-app layout whatever the project was: a go.mod at the root and the frontend in frontend/. In a monorepo, govulncheck ran where there is no Go module, the audit ran in a directory that does not exist, and Dependabot watched neither. No workflow ran the tests on a pull request at all.

Checking every generated workflow found more. The release workflow gated its desktop job with hashFiles in a job-level condition, which GitHub does not allow there, so the whole workflow was rejected on the first tag; and it built from apps/api even in a single app. turbo.json had no test task, so pnpm test failed. And once the audit pointed at the right place it failed on a fresh project: xlsx 0.18.5, the last release SheetJS published to npm, has two high advisories and no patched npm version.

The workflows now follow the project's shape. Dependabot watches the Go module and the pnpm workspace. The security workflow scans the API with govulncheck (pinned, on the Go the API builds with), audits production dependencies at high severity, and runs CodeQL on Go and, when there is a frontend, JavaScript. A new ci.yml runs vet and race-enabled tests for the API and type-check, tests and build for the frontend on every pull request. A single app's jobs stub the frontend it embeds, so Go compiles. The release job is valid for every shape and has a desktop job only when there is a desktop app. xlsx comes from SheetJS's patched 0.20.3 build. Every workflow passes actionlint for single, double, triple, API-only and mobile projects, and the commands they run pass on a fresh project, the audit included.

grit upgrade rewrites Dependabot, the security, lint and release workflows where they are still what Grit wrote, adds ci.yml when the project has none, and adds the test task. package.json is yours, so where a frontend still takes xlsx from npm, upgrade prints the command that replaces it. There is no lint step yet: the generated frontends ship no ESLint configuration, and Next.js 16 removed next lint.

Sync pull stops losing rows, and works on MySQL

The next finding from the review of a scaffolded app, and the test for it found data loss. Offline clients page through /api/v1/sync/pull with a cursor. The cursor was a bare timestamp and the next page asked for rows changed after it, so rows that shared a timestamp and fell across a page boundary were skipped for good: of 1,200 contacts written in the same instant and pulled 500 at a time, 500 reached the client. Bulk writes and imports produce exactly that.

What the review found was the ordering. A soft delete set only deleted_at, so to carry deletes, pull sorted by the later of updated_at and deleted_at. No index serves that expression, so every pull sorted the whole table: about 60 ms a page on 300,000 Postgres rows. And on MySQL the expression was written with a two-argument MAX, which MySQL does not have, so pull failed with a SQL error on every request.

A soft delete now sets updated_at to the same instant as deleted_at, through a hook in internal/sync that database.go installs, and generated and blog models index updated_at. Pull pages on (updated_at, id) with a cursor of the form time~id, and still accepts a bare time from a client that stored one before. It runs with the request's context. Measured again: 16 ms a page on the same Postgres table, 30 ms on MySQL, all 1,200 tied rows arriving in three pages, and a delete made after a cursor still reaching the next pull.

grit upgrade delivers the sync handler and the hook, installs the hook in database.go, and indexes updated_at on generated and blog models where the line is still what Grit wrote. Run grit migrate: it builds the indexes and moves updated_at forward on rows deleted before this release, so their deletes are carried too. On a project made with v3.257.0 the upgraded handler, model and hook came out identical to a fresh project's.

CSV imports over 1 MB work, take turns, and look each group up once

The next finding from the review of a scaffolded app, and the test for it found a worse problem first. Every generated resource's CSV import sits behind Sentinel's WAF, whose 1 MB body cap refused any larger file with 413 WAF_BODY_TOO_LARGE before the importer ran. The 100 MB limit an import route has had since v3.252.0 was never reached: a 5 MB file of 100,000 contacts could not be imported at all.

What the review found was in the importer itself. A belongs_to column looked its record up once per row: 19,000 contacts in 1,000 groups was 19,000 lookups of the groups table. Any error from that lookup, not only "not found", was taken as a reason to create the group, and the create was not checked, so a failed create left the row with no group and a confusing error later. And nothing limited how many imports ran at once: four started together all ran together, each holding a database connection.

Imports are now excluded from the WAF's body inspection, like uploads: they still pass through auth, permissions and rate limits. The importer resolves each distinct value once and remembers it, creates a missing record and checks the create, and fails the row on any other error. Id and user lookups check their errors the same way. Imports take turns through internal/imports, two at a time by default (IMPORT_CONCURRENCY); a waiting job says so in its status. Measured on the same project: the 100,000 contact file imports in 18.7 s with every row in its group, and of four imports started together two run and two wait.

grit upgrade delivers internal/imports, adds the exclusion to routes.go, and rewrites the lookups and adds the turn-taking in every generated importer where the code is still what grit generate wrote. On a project made with v3.256.0 the upgraded importer came out identical to a freshly generated one. Upgrading it also found a bug in upgrade itself: the helper that adds an import took a map key named "errors" for the import and skipped it. It now looks only in the import block.

A list page on a million rows answers in 10 ms instead of 122

The next finding from the review of a scaffolded app. A generated list sorts by created_at, which had no index, counted the whole match on every page, and searched with LOWER(col) LIKE '%term%', which no ordinary index can serve. Measured against a running API on Postgres with a million contacts: page 1 took 122 ms, page 2 142 ms, page 500 159 ms, and a search 543 ms.

Three changes. Generated models, uploads and users index created_at, so a page reads the newest rows from the index. A list's total is reused across its pages until the table is written to through the API, or for at most 15 seconds, so paging no longer counts the table each time; paginate.Install wires it in when the database connects. And on Postgres, grit migrate gives every column a list searches (tagged search:"trigram") a pg_trgm index, built CONCURRENTLY and recorded in the migration history so a rollback drops it. Where the extension cannot be created the indexes are skipped with a message and search works as before.

The same API and data afterwards: page 1 in 10 ms, page 2 in 7 ms, page 500 in 37 ms, and a search for a distinctive term in 8 ms. A short, common term is still slow on the page itself (175 ms for "4242" across a million numbered names), because so many rows match that Postgres walks the date index instead. Deep pages still pay for their offset; ?mode=cursor does not. The first live run also caught a bug in the count cache before release: it was keyed on a value GORM copies for every request, so it never hit, and its test did not list the way a service does. Both are fixed.

grit upgrade delivers the paginate package and the migrate command, installs the cache in database.go, and adds the index and search tags to generated models, uploads and users where those lines are still what Grit wrote. The indexes are built the next time you run grit migrate.

An XLSX export no longer holds the whole table in memory

The next finding from the review of a scaffolded app. A generated resource's export read its rows in batches for CSV, but for XLSX it collected every matching row into one slice and then built the sheet cell by cell in excelize's in-memory workbook. The comment above it said excelize had no streaming writer; it does. Measured on a fresh project with 300,000 contacts: one export took the API from 80 MB to 1,328 MB. A few at once, from anyone allowed to export, would take the API down.

export.NewXLSXStream writes the header, takes rows a batch at a time through excelize's stream writer, which moves them to a temporary file past a few megabytes, and sends the finished workbook. The generated handler adds each batch as the service reads it. The same export of 300,000 contacts now peaks 122 MB above idle, with every row in the sheet. More rows than a worksheet holds (1,048,576) is refused with export.ErrTooManyRows rather than a truncated file; CSV has no such limit. --audit-reads resources count the rows with sheet.Written(). export.XLSX still takes a slice, for small in-memory exports, and now uses the stream too.

grit upgrade delivers the export package and its tests, and rewrites the XLSX branch of every generated handler that is still exactly what grit generate wrote. On the test project the upgraded handler came out identical to a freshly generated one. An edited branch is left alone, with a note saying what to change.

Streams stream, and gzip stops costing a megabyte a response

The next finding from the review of a scaffolded app, and the tests written for it found three more problems in the same thirty lines. The gzip middleware built a new compressor for every request: 1,198 KB allocated per compressed response. Its writer did not pass Flush through the gzip buffer, so a server-sent event stream, the AI stream among them, reached the client in one piece when the handler returned. It compressed zip, xlsx, PDF and image responses a second time. It sent a 204 with a 10 byte gzip body. A handler that declared its length, as DataFromReader does, had the compressed body sent under the uncompressed Content-Length, which a client reads as a truncated or corrupt response. And gzip;q=0, a client refusing gzip, got gzip.

The middleware now lives in middleware/gzip.go. Writers come from a pool. The decision waits for the handler's first write, when its status and headers are known: only text-like types are compressed, never an event stream, never a bodyless status, never a body declared under 1 KB, and a declared length is removed when the body is compressed. Flush flushes the compressor and then the connection. A test that ships with each project covers every case above, and failed six of its seven checks against the old middleware. Checked end to end with a fake AI gateway sending a chunk a second: through the old middleware /api/v1/ai/stream delivered all five chunks after five seconds; now each arrives when the gateway sends it.

grit upgrade removes the old middleware from middleware/logger.go when it is exactly what Grit wrote, and delivers the new file. When it has been edited, upgrade says what to change and leaves both files alone.

The health check no longer stalls Redis

The next finding from the review of a scaffolded app. /api/health counted asynq's keys with a Lua script that called KEYS asynq:* inside Redis on every request. Redis runs commands on one thread, so the scan blocks every other client while it runs: the cache, rate limits, the job queue, the realtime backplane. The 500 ms client timeout does not stop a script already running on the server, asynq keeps a key for every task, and anyone can call the endpoint. Reproduced with a million keys: the worst Redis round trip went from 3 ms to 1,261 ms while the health check ran, and the check itself took 813 ms.

The jobs probe now reports up when Redis answers its ping, and takes its queue counts from jobs.StatsCache: asynq's inspector, which reads each queue's list and set sizes, refreshed in the background at most every 30 seconds. A probe never waits for it. Against the same million keys the worst Redis round trip stayed at 20 ms and the health check answered in 5 ms. The response reports queued and active in place of queue_keys, and the admin's System Health page shows them.

grit upgrade delivers jobs/stats.go and the admin page, and replaces the probe in routes.go when it is still exactly the code Grit wrote; otherwise it says what to change.

Uploads over 10 MB work, and a slow export is no longer cut off

The next finding from the review of a scaffolded app. Every request passed through a 10 MB body cap before it reached a handler, so the upload handler's own 512 MB limit never applied: no upload over 10 MB could succeed, whatever a field advertised. The server's 15 second read and write timeouts were each one deadline for a whole request or response. Reproduced on a fresh project: a 20 MB upload was refused with 413, and a CSV export of 300,000 rows to a slow reader answered 200 and stopped after 3,935 of them, so the partial file looked like a success. The AI stream was cut at 15 seconds while its client allows 120.

middleware.RequestLimits replaces the global cap. It chooses the body limit and the deadlines by route. An ordinary route keeps 10 MB and the server's timeouts, now 10 seconds for headers, 30 to read and 60 to answer. Routes listed as transfers in routes.go get their own limit and 30 minutes to read or write, extended per request with http.ResponseController: uploads (512 MB), the AI endpoints, the GDPR and audit exports and backup downloads. Every generated resource's /export and /import (100 MB) is a transfer without being listed. The server timeouts stay short on purpose: they are what stops a slow client holding a connection open.

Checked against a running API with MinIO: a 20 MB upload succeeds, and so does one sent over 25 seconds; the 300,000 row export reaches a slow reader whole; an 11 MB JSON body to an ordinary route is still refused. tests/live/verify_limits.py runs those checks. grit upgrade delivers the middleware and its tests, and updates routes.go and cmd/server/main.go where they are still the files Grit wrote.

A failed database write no longer passes for a successful one

The next finding from the review of a scaffolded app. Writes in the two-factor, session and auth paths ran without checking their error, and three of them mattered. Two sign-ins presenting the same backup code at the same moment could both use it, because each read the list of codes and then saved the shorter one. Turning 2FA off ran three deletes outside a transaction and answered "disabled" whether or not they had run. And when a refresh token was replayed, the session it belonged to was revoked with an unchecked write, so a database error left a captured session live.

A backup code is now spent by an update that matches only while the list is still the one the request read. The request that loses the race gets a 401, which counts as a failed attempt. Checked against a running API: two concurrent sign-ins with one code return exactly one 200 and one 401. Disabling 2FA runs in one transaction and answers 500 if it fails. A replay whose revocation fails is refused with that error. A passkey ceremony is claimed by deleting it, so two requests presenting one challenge cannot both finish.

The other writes the review listed, and those a scan of a fresh project turned up, are checked too: the outbox relay, the passkey sign counter, API key last use, SSO, webhooks, form shares, GDPR requests, tickets, notifications, import job progress, device pairing and the thumbnail URL. Where failing the request would be wrong, the failure is logged. The thumbnail job returns it, so the job is retried.

CI had been hiding two problems. The step that runs a generated project's tests piped go test into tail and reported tail's exit code, so the module flag tests had failed since v3.243.0 made production the default. The workflows now set pipefail, and those tests run in development. A fresh project's own lint config also reported two findings, now fixed: the API key seeder treated any database error as "no admin yet", and the lockout window multiplied a duration by a duration.

grit upgrade delivers the 2FA handler, the session and passkey services, the outbox relay, SSO and GDPR, and fixes config/modules_test.go in place. Form shares, tickets, notifications, API keys, webhooks, device pairing, import handlers and the jobs worker are yours once written, so those changes reach new projects and newly generated resources.

An image cannot claim enough pixels to take the API down

The next finding from the review of a scaffolded app. The image pipeline behind a direct upload read an image's dimensions from its header and refused one too large to decode. The thumbnail job did not: a file uploaded through a presigned URL went straight to image.Decode, which reserves memory for every pixel the header claims before reading any of them. Reproduced with a 72-byte PNG that claims 8000x8000: decoding it allocated 244 MB before failing. At 30000x30000 the same file asks for 3.4 GB. The job runs inside the API process and was retried five times, so a file that size would crash the API, and crash it again on every retry.

The storage package's image helpers now read at most 50 MB, check the pixel count against the media profile's limit from the header, and only then decode. They return storage.ErrImageTooLarge or storage.ErrUnreadableImage, and the thumbnail job treats both as permanent (asynq.SkipRetry), so an image that cannot be processed is set aside instead of retried. The media pipeline's own pixel check now multiplies in 64 bits, so dimensions near the integer limit cannot wrap past it.

grit upgrade delivers the storage and media changes and updates the thumbnail job in jobs/workers.go. A test that ships with each project feeds the helpers a PNG claiming 30000x30000 and fails if refusing it allocates more than 64 MB. One thing this does not change: jobs still run inside the API process. For heavy image work, run the workers as a separate process.

A generated API builds on Go 1.26.6, and govulncheck finds nothing

The next finding from the review of a scaffolded app. A fresh project's go.mod said go 1.25.0, which is what its release workflow installs, and its lint and security workflows asked for Go 1.24. Run on this machine's Go 1.26.4, govulncheck reported eight standard library vulnerabilities that the API's own code reaches, among them net/http and the encoding/xml behind SAML sign-in, which anyone can reach before signing in. Two modules were also below their fixed releases: golang.org/x/crypto and filippo.io/edwards25519.

The API's go.mod now says go 1.26.6. That one line is what setup-go and the release workflow install, and an older Go downloads 1.26.6 on first build, so it raises the version everywhere at once. The Dockerfiles pin golang:1.26.6-alpine, the generated lint and security workflows pin 1.26.6, the desktop app follows, and the scaffold requires x/crypto v0.57.0 and edwards25519 v1.2.0. On a fresh project govulncheck ./... now reports no vulnerabilities.

grit upgrade raises an older go directive, raises both modules to their floors (so grit doctor reports a project left below them), and raises Go pins below 1.26.6 in your Dockerfiles and workflows, leaving a newer pin alone.

MinIO no longer runs on minioadmin, and side containers get only their own settings

The next finding from the review of a scaffolded app. MinIO's root credentials were minioadmin / minioadmin everywhere: in .env, as the fallback in the API's config, hard-coded in the development compose file, where MinIO's port is open to the local network so a phone can load images, and as the default in the production compose file, where presigned uploads put MinIO behind the public proxy. Whoever reached it owned the bucket. The production stack also gave Postgres and MinIO the whole .env: the JWT secret, the Sentinel keys and every dashboard password.

A new project's .env now carries MinIO credentials generated like its other secrets. Both compose files read them from there and refuse to start without them, as the production file does for the Postgres password, which used to fall back to grit. Postgres and MinIO in the production stack receive only the settings they read. And the production check from v3.243.0 now covers MinIO too: outside development, an API using MinIO refuses to start with a default or short MINIO_SECRET_KEY, and names it.

grit upgrade updates both compose files and the production check in config.go. It does not rewrite .env, which holds your secrets: if it still says minioadmin, the upgrade tells you, and a production server will not start until you set new MinIO credentials. MinIO takes them on its next start; files already stored are unaffected.

Verified on a fresh project and on one upgraded from v3.247.0: the rendered production stack gives Postgres, pgbouncer, Redis and MinIO none of the API's secrets, an empty MinIO secret stops the stack, and a production API refuses minioadmin. The CI live suite checks both on every push, and the docs no longer tell you to sign in to MinIO with minioadmin.

A delegated role can no longer make itself ADMIN

The next finding from the review of a scaffolded app, reproduced before it was fixed. An account given only users.edit and roles.edit, the kind of role you would hand a support lead, made itself ADMIN by setting its own role, made itself ADMIN again by assigning itself the ADMIN role, reset an administrator's password, deleted that administrator, wrote * into its own role, and created a role with a permission it did not have. Every one of those requests was answered 200.

There is now a grant ceiling, in internal/authz/ceiling.go. An ADMIN hands out anything. Anyone else hands out at most what they hold: a role they create or edit may grant only permissions they have, a role they assign may grant only permissions they have, and a wildcard counts as every permission it expands to. Only an ADMIN makes an ADMIN, changes or deletes an ADMIN account (the ADMIN role, or roles that together grant everything), or edits a built-in role. A delegate still edits ordinary accounts and creates roles within their own grants.

grit upgrade adds ceiling.go and puts the checks into your user and role handlers where they still read as Grit wrote them. The role tests that ship with the project now act as an ADMIN, which they always meant to, and gain a test of the ceiling.

Verified live on a fresh project and on one upgraded from v3.246.0: all six escalations are refused and the three legitimate actions still work. The CI live suite gains the same checks. Also fixed: since v3.242.0, grit upgrade added dompurify to the web app's package.json without recording that the edit was its own, so the next upgrade treated the file as yours and stopped updating it. It now records the edit; a file already marked that way stays marked, and grit upgrade --diff shows what it holds back.

Database backups are no longer in a public bucket

The next finding from the review of a scaffolded app. On every start the API set a bucket policy granting anyone s3:GetObject on every key, and backups are written to the same bucket under backups/. A backup's address, seen once in a proxy log, browser history or a Referer header, was a permanent anonymous download of the database: password hashes, 2FA secrets and every record. The fifteen-minute signed download link protected nothing, because the same URL without its signature worked too. The error from setting the policy was also thrown away. Reproduced against MinIO: backups/, originals/ and exports/ all answered 200 to an anonymous request.

The policy now covers uploads/ and thumbnails/ only, which is everything the API hands out a plain URL for, so images and download links keep working. Backups, the private originals kept by the image pipeline and every other key can only be read through a signed URL. Setting the policy replaces the one a bucket has, so an existing bucket is narrowed the first time an upgraded API starts, and a provider that refuses the policy is now reported in the log rather than ignored.

One case this cannot reach. Cloudflare R2 and Backblaze B2 have no bucket policies: public access is switched on for a whole bucket in their dashboards. If yours has a public domain, keep backups in a different bucket from uploads.

Verified against MinIO on a fresh project and on a project upgraded from v3.245.0 whose bucket had the old policy: an uploaded image still loads without a signature, and objects under backups/, originals/ and exports/ are refused. tests/live/verify_storage.py runs the check against any MinIO, and a test that ships into every project pins the policy to the two public prefixes.

A two-factor code can be used once, and cannot be guessed

The next finding from the review of a scaffolded app, reproduced before it was fixed: five of nine checks failed. Anyone who had the password could get past 2FA.

• Unlimited guesses. A pending token took as many codes as could be sent in its five minutes, and a correct password cleared the account's failure count, so signing in again handed out a fresh supply. A code has a million values and three of them are valid at any moment.
• Replay. A code signed in again for as long as it was valid, including the code used to turn 2FA on.
• Silent re-enrolment. Enabling 2FA replaced a secret that was already enabled, so a stolen session could move the account to the attacker's authenticator.
• Skipped checks. The second step did not refuse a disabled or locked account, which the password step does.

Now each pending token takes five wrong codes and is then spent. Every wrong code also counts against the account on the same counter as wrong passwords, which is cleared only when a sign-in completes, so ten wrong codes across any number of sign-ins lock the account for fifteen minutes (totp.MaxFailedAttempts, totp.LockoutDuration). The time step of each accepted code is stored and only a later one is accepted, through a conditional update so two requests cannot spend one code; the code that enabled 2FA is spent too. Codes are compared in constant time, the pending token is spent by exactly one request, enabling is refused while 2FA is on, and the second step checks for a disabled or locked account. A backup-code sign-in now sets the browser's cookies as well.

grit upgrade delivers the TOTP package, its models (two new columns, added by grit migrate) and the handler, and moves the failure-count reset in your login handler to after the 2FA step.

After the fix all nine checks pass, computing real codes against a fresh project and an upgraded copy of the reviewed app, and they run in the CI live suite.

A refresh token is not an access token, and logging out ends the session

The next finding from the review of a scaffolded app, reproduced on a fresh project before it was fixed. Seven of thirteen checks failed.

• Refresh tokens worked as access tokens. The two were the same shape, so the seven-day refresh token, which the login response also returns in its body, was accepted as a bearer token on every route and on the WebSocket.
• Revoking a session reached nothing already issued. The auth middleware never read the sessions table, so after logging out, signing out everywhere or changing a password, every access token kept working until it expired.
• The refresh cookie never reached its routes. It was scoped to /api/auth, and refresh and logout are mounted under /api/v1/auth. A browser never sent it to either, so a web session could not refresh (the admin sent you back to the sign-in page when the access token expired) and logout revoked nothing.

Tokens now carry a type and the id of the session they belong to. ValidateAccessToken, which the auth middleware and the WebSocket handshake call, accepts only an access token whose session is live, checked against the database and trusted for 30 seconds. Revoking a session through this process takes effect at once, and through another replica within those 30 seconds./auth/refresh accepts only a refresh token and keeps the session id through rotation, and the cookie is scoped to the versioned auth routes. Two-factor sign-in and impersonation now record sessions, which they did not before. The JWT parser also insists on HS256 and an expiry.

grit upgrade delivers the new auth and session services and edits the middleware, the WebSocket handler, refresh, two-factor sign-in, the impersonation plugin and the service wiring where they still read as Grit wrote them. Existing sessions survive: an access token from before the upgrade is refused once, and the client refreshes with its old refresh token, which is still accepted. If you mint tokens yourself with GenerateTokenPair, record the session with services.CreateSession, or the access token is refused.

After the fix all thirteen checks pass, on a fresh project and on an upgraded copy of the reviewed app, and they run in the CI live suite on every push. The session tests that ship into each project cover token types, revocation and rotation.

Production is the default: login limits that fire, no SQL console, no default passwords

Two more findings from the review of a scaffolded app, both about what a server runs with when nobody configured it carefully.

The login rate limit had never fired

Sentinel matches the request path exactly. The five-per-fifteen-minutes login limit, the register limit, AuthShield and the CSRF exemptions for signing in were all written as /api/auth/login, while the router mounts /api/v1. Not one of them matched a request, so a password could be guessed as fast as the server answered. They are now built from the API version, and the forgot-password, reset-password and 2FA routes get limits of their own. Verified against a running server: five wrong passwords are refused as credentials, and the sixth is a 429.

A forgotten APP_ENV meant development

Without APP_ENV the API ran as development: no rate limits, the WAF only logging, password-reset links written to the log. And nothing outside development refused studio, sentinel or pulse as a dashboard password, or a short JWT secret. Unset now means production. Anywhere but development, the server refuses to start with a JWT secret under 32 characters or a dashboard password that is short or a known default, and names the settings to fix. A scaffolded .env says APP_ENV=development and has generated secrets, so nothing changes on your machine.

GORM Studio and /docs in production

GORM Studio, a browser SQL console with write access to every table, was on in production behind basic auth, and /docs published every route, admin, backup, SSO and GDPR ones included, with a console to call them. In production Studio is now off whatever GORM_STUDIO_ENABLED says, because .env files get copied to servers whole; GORM_STUDIO_IN_PRODUCTION=true turns it on there, read-only and with no SQL editor. /docs is served in production only with API_DOCS_PUBLIC=true. Development keeps both as they were.

Upgrading

grit upgrade applies all of it to config.go, routes.go, the CSRF middleware and the startup log, anchoring on the text Grit generated and naming anything it had to leave alone. Check one thing before you deploy: a server started without APP_ENV, or with a default dashboard password, will now stop with an error instead of starting. That is the point, but it is a change.

The CI live suite now starts the fixture a second time with APP_ENV=production: Studio and /docs answer 404, a sign-in with a stale session cookie is judged on its credentials rather than refused for CSRF, the sixth failed login is a 429, and a start with PULSE_PASSWORD=pulse exits naming it.

Stored XSS: rich text is sanitised on its way into the database, and again in the browser

The next finding from the review of a scaffolded app. The demo blog stored a post's HTML exactly as it was sent, and the web app rendered it with dangerouslySetInnerHTML on the same origin as the admin panel. There was no sanitiser in either tier. So an account allowed only to edit posts could save <img src=x onerror="...">, wait for an admin to read it, and let the script call the API as that admin: issue itself an API key, or give itself the ADMIN role. Any richtext field on a generated resource had the same problem the moment somebody rendered it.

Every API now has internal/sanitize, installed on the database handle when it connects. Every field tagged sanitize:"html" is cleaned on every write that has a model, whichever way the write arrives: create, PUT, PATCH, bulk edit, the CSV importer, sync push and GORM Studio's row editor. The generator tags richtext fields, and the blog's content is tagged. The policy keeps what the admin editor produces (headings, lists, links, images, tables, code blocks with their language, text alignment, colours and highlights) and removes scripts, event handlers, javascript: URLs, iframes and any other styling. The blog pages, in the Next app, the Vite app and the single-app SPA, also render through DOMPurify, which covers posts stored before this release.

grit upgrade adds bluemonday and the package, wires it into database.go, tags the blog's content and adds dompurify to the web app, so run pnpm install afterwards. It cannot tell a rich text column from a plain text one in a resource you already generated, so add sanitize:"html" to those fields' tags yourself. Rows already stored are not rewritten; saving one again cleans it. Raw SQL and db.Table without a model bypass the sanitiser.

Verified live on a fresh double: the attack is gone from the stored row and the public page after a create and an edit of a post, and from a generated richtext field after create, PUT, PATCH and bulk patch, while centred text survives. The sanitiser's own tests ship into the project and pass there and on an upgraded copy of the reviewed app, and the Next and SPA builds pass with DOMPurify. The CI live suite gains four checks.

A security review of a scaffolded app: the three criticals, and the secrets in .env.example

An independent review ran thirteen specialist skills over a double scaffolded with v3.239.0, a small address book, and reported 109 findings: 3 critical, 26 high, 44 medium and 36 low. Nearly all of them are framework code, so they are being fixed in the templates rather than in that app. This release is the set the review marked "before the first commit". Every one of them was in a project freshly scaffolded today.

Any account could make itself ADMIN through sync

The default sync registry held users and uploads, and /sync/push was a generic write: it loaded the row the client named, decoded the client's JSON over it and saved it. Register, push {"op":"update","model":"users","data":{"role":"ADMIN"}}, done. Pull returned every row of every synced table to any signed-in account.

Users and uploads are no longer synced; both have APIs with their own checks. Each pushed change now asks for <model>.create, .edit or .delete, or for the row to be the caller's own in a table whose rows have owners, and an owner cannot hand a row to somebody else by rewriting its owner field. The id, version and timestamps are never taken from the payload. Pull reads a table with <model>.view, and otherwise only the caller's own rows of an owned table. A row the caller may not touch answers NOT_FOUND, so its existence is not confirmed.

SQL injection and IDOR in the upload handlers

GET and DELETE /uploads/:id passed the path segment to First(&upload, id). With a string, GORM treats that as a SQL condition, not a primary key, so /uploads/1=1 matched a row and a longer expression was a blind oracle over the whole database. Neither checked who owned the file, and the list and stats covered every user's uploads. Lookups are now parameterised and scoped: an ADMIN or a holder of uploads.view (or uploads.delete) reaches every upload, anyone else only their own, and anything else is a 404.

Generated resources were open to any signed-in account

Only delete and bulk asked for a permission. List, read, export, import, create and update sat on the protected group, and on an app with open registration signed in means anybody: the review exported the whole address book from an account made a minute earlier. Each generated route now asks for the permission the roles screen already grants for its verb (view, create, edit), on the staff group, so an ADMIN holds them all and a role can grant them. The same applies to the workflow, append-only and --tree routes, where a move or a rebuild rewrites every row beneath a node.

A resource generated with --owned-by or --tenant-owned keeps its protected routes: its queries are already narrowed to the caller's own rows or organization. A project whose routes predate the staff group puts shared routes on the admin group instead.

Real secrets in .env.example

.env.example, the file meant to be committed, was a byte-for-byte copy of .env: the JWT secret, the database password and the dashboard passwords, in the repository from the first git add, and in production for anyone who deployed with cp .env.example .env. Generated secrets are now CHANGE_ME there, and *.db and *.sqlite files, which hold password hashes, sessions and API keys, are ignored.

Upgrading

grit upgrade applies all of it to an existing project. It moves generated routes behind their permissions, in the route files and the tree routes in routes.go, takes users and uploads out of the sync registry and the desktop app's sync list, delivers the new sync and upload handlers, replaces the secrets in .env.example and adds the ignores. Each edit anchors on the exact text Grit generated, so a route you wrote by hand is left alone, and is still open to every account if it is on m.Protected.

Two things it cannot do for you. If .env.example was ever committed or shared, rotate the secrets in .env, because they are the same values. And an ordinary account that used a shared resource before now needs a role that grants it: give <resource>.view and the rest in Roles & permissions.

Verified live on a fresh double (24 checks) and on a copy of the reviewed app after grit upgrade (26 checks): a new account gets 403 on shared resources and cannot push or pull them, cannot change its role through sync, and gets 404 for /uploads/1=1 and for another user's file, while ADMIN and owners keep working. The CI live suite gains the same checks. The rest of the review is tracked as Phase 8.

--append-only broke grit migrate on ordinary MySQL

v3.240.0 added the append-only resource to the live suite, and its MySQL job was the first time the MySQL trigger met a real MySQL. Run locally against MySQL 8.4, it showed what production would have met: with binary logging on, which is the image default and the norm on RDS, a user without SUPER cannot create a trigger. Error 1419. InstallTriggers returned it, so the whole migration failed, including the default roles seeded straight after it, which left authorization broken as well as the table unguarded. And because AutoMigrate had already created the table, a raw UPDATE on the "append-only" rows went straight through.

On that refusal, grit migrate now logs what is missing and how to add it, and carries on: the GORM guard still refuses every change that goes through the API, and the roles are seeded. With log_bin_trust_function_creators set, the trigger installs and MySQL refuses a raw UPDATE with error 1644. Verified both ways against MySQL 8.4.11. Any other trigger error still fails the migration, because only the privilege refusal has a safe fallback.

Also, the v3.240.0 append-only live checks reached only the Postgres fixture. The SQLite and MySQL fixture is built in a separate job and never generated the resource. It does now, and the MySQL job sets the variable so the trigger is installed and checked rather than skipped with a warning.

A double-entry ledger under load, and the three gaps it found

The second of the reviewer's stress projects: a ledger with multi-currency transfers, stock, an append-only journal and the transactional outbox, driven by 32 concurrent workers. 3,000 transfers and 300 orders later the invariants all held. Every transfer wrote exactly two lines, every same-currency pair moved the same amount both ways, every balance reconciled against its own journal to the minor unit, 609 currency conversions rounded without drift, the product sold exactly its 250 units and refused the 51st, and not one journal row was ever mutated: not through the API, not in SQL, not by TRUNCATE.

What it found was not in the arithmetic. It was in what the framework leaves to you without saying so.

Nothing delivered the outbox. The event bus runs a relay for its own event: topics and deliberately leaves the rest of the table alone, so an application that enqueues ledger.transfer needs a relay of its own. Nothing says so at run time: the write succeeds, the transaction commits, and the rows sit at pending with zero attempts. 2,200 of them piled up before anybody looked. grit doctor checks for it now, reading the topics your code enqueues and the relays your code starts, and the outbox finally has a documentation page rather than one comment in a changelog.

The taxonomy had no code for "not enough of it". Grit ships stock.Take and money.Sub and had nothing for what they refuse, so every application that sells something or moves money invented a code. INSUFFICIENT_STOCK and INSUFFICIENT_FUNDS are in the catalogue now, both 422, and the generated TypeScript union knows them.

An append-only resource had lost its bulk load. --append-only dropped the CSV import along with update and delete, and the import only inserts: CreateInBatches with OnConflict DoNothing. A ledger's history arrives as a file of rows that already happened, and there was no way to load it. The import is routed again, and the live suite now imports 2,000 rows into an append-only table while transfers run against it, then checks that the table still refuses an update.

The outbox itself came out of this well: 3,250 messages, delivered by a relay whose Deliver refused a third of the time, drained in ten seconds with 1,639 retries, every key delivered exactly once. The retry path, the claim, the backoff and the dedupe key all behaved.

A two-app project on Vite had a panel that could never have run

grit new x --double --vite wrote the Next.js panel into a TanStack Router app: 41 route files under an app/ directory a Vite app does not route, and 129 components importing next/link, which it cannot resolve. Nothing linked to any of it and nothing would have compiled if it had. The shape shipped that way since the panel was embedded at all.

The machinery for doing it properly already existed: it is what a single project's SPA uses, and the only single-specific thing about it was a hardcoded path. The panel now lands in src/routes/admin/ with its code under src/admin-panel/ behind the @admin alias, in the TanStack dialect, with the aliases and dependencies written into that app's own Vite config, tsconfig and package.json. grit generate resource writes a new resource's screens there and registers it, grit add web-auth writes the sign-in pages and the customer area there, and grit upgrade deletes the Next.js panel that could not compile before writing the one that can.

Six bugs fell out of building it, and five were not about this feature. Every Vite web app ever scaffolded shipped a navbar linking to the literal string {{ADMIN_HREF}}, because the substitution ran only on the Next.js writer. The realtime client wrote apps/web/hooks/use-realtime.ts into an app that keeps its code under src/, and the resource generator then followed that directory, putting every generated hook beside it. Four writers appended src to a path that already had one, or did not append it when it was needed, so the standalone Vite admin's dashboard widgets were landing outside the application.

The one that would have bitten hardest: the SPA's API client authenticates with a bearer token and never echoed the CSRF cookie. That is fine on its own, because the API exempts bearer requests, and wrong the moment the admin panel in the same app signs in with cookies. After that the browser holds a session cookie for the host and sends it with everything, so a customer signing up on the public site was refused with CSRF_INVALID. It echoes the token now, which fixes the same latent bug in every single-binary project.

Verified on a scaffolded --double --vite: the web app builds and typechecks clean, the panel signs in and renders its dashboard with live data at /admin/dashboard, a generated resource appears in its sidebar, a customer registers and lands on the account dashboard, and a project scaffolded before this upgrades, loses the panel it could not compile, and builds green.

The single gets the sign-in pages its auth library never had

A single project's SPA has shipped lib/auth.ts since it existed: login, register, refresh, logout, the two-factor challenge, and a session-expiry monitor watching a session nothing could start. There was no sign-in screen. grit add web-auth writes those screens for a Next.js web app and refused a single outright, because it looked for apps/web and found a binary.

It writes them now, in the dialect that app speaks: /login, /register, password reset, and the customer area at /account behind a route guard that turns away a visitor with no token before a screen renders. Same dashboard shape as the two-app and three-app projects got in v3.237.0, same account overview and profile form, and the navbar gains the account menu.

The SPA is four sections now, and the root route is none of them: it renders an outlet and nothing else. routes/_site draws the navbar and the footer, routes/admin the panel's sidebar, routes/_auth a full-bleed card and routes/account the customer shell. The names beginning with an underscore are pathless layout routes, TanStack's answer to a route group, so not one URL changed. The root used to decide by asking whether the path started with /admin, which is the hand-kept list the Next.js app stopped using yesterday, and it was two entries away from being wrong again.

Verified on a scaffolded single: 2,920 modules built with no type errors, a customer registers and lands on the account dashboard, the profile form saves (200 on PUT /api/v1/profile), signing out and returning to /account lands on /login, the landing page keeps its chrome and the panel keeps its own. grit upgrade moves an existing SPA's pages into the section, rewriting the id inside each one, and that project builds green too.

A web app serves three kinds of page, and now has three layouts

Somebody opened the admin panel in a two-app project and found the marketing navbar above its sidebar and the site footer under its tables. The root layout wrapped every page in that chrome, and a client component took it away again for a hand-kept list of path prefixes: /login, /register, /forms/. The list had never heard of /admin, and a list that has to be kept in step with the routing table by hand is going to be wrong eventually.

Next has route groups for exactly this, and they cost nothing at runtime. The root layout is the document now: fonts, theme, providers, no chrome. app/(marketing)/ is the public site and its layout draws the navbar and the footer. app/admin/ keeps its own. And app/(app)/ is the third thing a web app serves and never had a home: the pages a signed-in customer sees. No URL changes, because a group name in parentheses is not part of the path.

That customer area was a hole, not a nicety. The user menu has linked to /account since v3.31.42 and the middleware has protected /account for just as long, and the page did not exist: signing in and clicking your own name was a 404. grit add web-auth now writes it as a dashboard, sidebar and all: an overview of the account and a profile page that edits the name, email, job title and password through PUT /api/profile. Add a section by adding a line to one array.

And the Admin link in the navbar, which in a double still pointed at http://localhost:3001 where nothing runs. v3.235.0 fixed the value the app compiles in and left .env alone, and .env set NEXT_PUBLIC_ADMIN_URL to that port in every project ever scaffolded. The environment wins over the default, so the fix never showed. That line is written per architecture now: a URL for a triple, a commented-out override for a double, absent in a single. grit upgrade retires it in projects that already exist, moves their public pages into the group, and says which of your own pages it left behind for you to place.

Verified on a scaffolded double: the admin panel renders with only its own chrome, the landing page keeps the navbar and footer, a customer registers and lands on a working account dashboard whose profile form saves, a generated resource appears in the admin sidebar with a working list screen, and an upgraded project built before any of this builds green.

A single gets the admin panel too, inside its SPA

Yesterday a two-app project got the panel. A one-binary project had the same hole and a smaller excuse: the whole point of --single is that one binary is the entire product, and the thing you administer it with was not in it. It is now, as a section of the same SPA at /admin/dashboard: 35 screens, 201 files, the same dashboard, resource CRUD, system hub, settings and account security a three-app project has.

The source is the Vite admin rather than the Next one, because a single project's frontend is already a TanStack Router app. Its routes move into the SPA's tree under /admin and the id inside each route file is rewritten to match, since TanStack refuses a file route whose id is not its path; everything else moves to frontend/src/admin-panel/ behind an @admin alias. The SPA's root route yields: the panel draws its own sidebar and topbar, so the site navbar and footer step aside for anything under /admin, and nothing else changes. grit generate resource writes its screens there and registers it in the sidebar, and grit upgrade adds the panel to a single you already have: 212 files, plus the aliases, dependencies and dev-proxy entries inserted into your own config only where they were missing.

Most of what this turned up was not about the feature. The panel's api-client defaults to http://localhost:8080, which is right when the admin runs on its own port and wrong when the binary serving the page is the API: it asks the origin it was served from now, in dev through the Vite proxy and in production directly. That proxy only forwarded /api, so the panel's links to GORM Studio, Pulse and Sentinel landed on the dev server; it forwards those too. The api-client also read process.env.NODE_ENV, which Vite does not polyfill, so every Vite admin ever scaffolded carried a "process is not defined" in the browser that vite build could not catch, because esbuild does not typecheck.

Three more, all from asking the wrong question. Writers that wanted to know whether the panel is a TanStack app asked UseTanStack, which reads a field that is empty for a single project, so the account-security screen was written as a Next.js page into an apps/admin directory a single does not have: one orphan file, no package.json, nothing that compiles it. The generator had two copies of "where does admin code live" and only one learned about the new shape, so a generated resource was written and never registered, which means the screens existed and the sidebar did not know. And the shared schemas and types were written to packages/shared, which a single project does not have, so grit generate emitted a customisation overlay importing a type it had just skipped, and grit sync had nothing to sync. grit remove resource now finds the panel in all three shapes as well.

Also the Redis noise, in the single binary this time. v3.235.0 quietened apps/api's main; a single project has its own, and it still printed a wall of driver failures, then "Background worker started", then an asynq error every second or two forever. Two lines now, and the worker and cron start only when Redis answered.

Verified on a scaffolded single: 2,908 modules built with no type errors, the panel serves at /admin/dashboard with its own chrome, a generated resource appears in the sidebar and lists its records, and grit upgrade delivers all of it to a project scaffolded before this existed.

A double gets the admin panel, at /admin

Somebody scaffolded a two-app project, opened the web app, clicked Admin in the navbar, and arrived at http://localhost:3001 where nothing was running. The panel was built for three-app projects only: a double had the link and no panel behind it, which is worse than not offering it.

It is there now, as a route group inside the web app: 147 screens at /admin/dashboard with their own layout, the same dashboard, resource CRUD, system hub, settings and account security a triple has. Not a second copy of the code. The file map is the one the standalone app uses, put through a transform that moves the routes under app/admin, moves the components, lib and hooks under admin-panel/ behind their own @admin alias, and prefixes the internal links, so a fix to an admin screen reaches both shapes at once. grit upgrade adds it to a double you already have, 157 files, manifest-guarded so anything you edited is reported rather than overwritten.

Four bugs came out of building it, and three were not about this feature at all. @repo/upload ships raw TypeScript and neither the web app nor the admin app listed it in transpilePackages, so the standalone admin could not have built either: the failure reads "Module parse failed: Unexpected token" on a type-only import. Several admin screens are written by feature writers rather than by the file map, and those asked whether the project has an admin app when they meant whether it has a panel, so an embedded one arrived without its account-security page while the link to it sat in the user menu. Fourteen writers built the path apps/admin by hand rather than asking, which is the failure the path-helper comments already warned about. And grit upgrade assumed every project was a triple, because Normalize defaults to it and upgrade never set the architecture: upgrading a double wrote thirteen files into an apps/admin that does not exist, plus a components.json for an application that is not there. Upgrade now reads the shape off the directories.

The panel guards itself, as it always did: the layout redirects anybody who is not signed in and sends a plain USER role to their profile rather than the dashboard. grit add web-auth is unchanged and does not collide with it: its middleware matches /account, /login and /register, none of which are the panel's routes under /admin. It did need one fix, because it writes the navbar and would have left the literal placeholder for the admin link in it.

Separately, the startup noise on a project with no Redis. Four identical pool failures from inside the driver, a warning saying caching was disabled, then "Job queue connected" which was not true, then an asynq error every second or two forever because the worker polls regardless. The driver's own logger now collapses repeats, the job queue reports what actually happened, and the worker and cron scheduler only start when Redis answered. Two lines instead of a wall.

Single is next: its admin has to go inside the embedded Vite SPA rather than a Next.js route group, which is the same idea and different work.

Say which database, and have it tested

Somebody opened a fresh project's .env to point it at MySQL and found Postgres settings, a commented DATABASE_URL mentioning Postgres and SQLite, and nowhere to put MySQL credentials. They were right: the engine came from the scheme on DATABASE_URL and nothing in the file said so, for an engine that had been supported for months.

There is a setting now. DB_PROVIDER takes postgres, mysql, sqlite or memory, each with its own block of settings beside it, and grit new myapp --db mysql picks it at scaffold time. DATABASE_URL still wins when set, because a managed database's connection string carries options these parts do not model, and when the two disagree about the engine the app says so at boot instead of leaving you to wonder why the settings you edited do nothing.

memory is new, and it migrates itself. An in-memory database cannot outlive the process holding it, so a separate migrate command would build the schema and take it away again: the server migrates at boot when the provider is memory, which is safe precisely because there is never anything to lose. It also uses a shared cache rather than a bare :memory:, without which every pooled connection gets its own empty database and a freshly migrated app reports that its tables do not exist.

The part that mattered more than the setting: these engines are now tested. The live suite, 68 checks over a running app covering ownership, trees, the public surface, money, encryption at rest, CSV import and optimistic locking, runs on MySQL 8 and SQLite as well as Postgres 15, 16 and 17, with a smaller set on an in-memory database. It reads the database directly on each of them rather than only over HTTP, which needed one Postgres-only query fixed: || for concatenation, which MySQL reads as OR.

Building the first project on MySQL found a real bug within a minute. grit generate resource --tree produced a table MySQL refused to create: the materialised path was an indexed varchar(1024), and utf8mb4 counts four bytes a character, so the index was 4096 bytes against a 3072-byte limit. The path is 700 characters now, about eighteen levels of uuid, and the whole suite passes on MySQL. That is the value of running the thing: the support was claimed, the documentation was correct, and the first table with a deep index did not exist.

grit doctor gained one more check, for the failure this release makes easy to reach: DB_PROVIDER=memory with APP_ENV=production is an error, because the app works perfectly until it restarts and then every row is gone with nothing to recover from. SQLite in production is a warning that names the tradeoffs rather than a refusal.

Three bugs where tenancy, roles and impersonation meet

A reviewer proposed building applications that deliberately combine subsystems which have each had bugs on their own, on the theory that intersections are where the next ones live. The first of those is multitenancy with custom roles and impersonation, all at once. It found three, and the first is the kind of thing that makes a framework unusable for the case it advertises.

Every DELETE on a tenant-owned resource answered 500. The plugin mounted its organization resolver on the protected route group only. The staff group carries every delete and every bulk route, and the admin group every admin-only endpoint, so on those the request never resolved an organization at all: the scoping callback fails closed, as it should, and the caller got "Failed to delete deal". The resolver is now mounted on all three groups, and the routes file has markers for the other two so a plugin can reach them.

A role held through an organization membership granted nothing. The middleware read the membership, put its role id on the request context, and nothing ever read it: permissions came from platform roles alone, so somebody made an administrator of one organization was an administrator of every organization they belonged to. Per-organization roles now grant inside that organization, and only there. They add to platform roles rather than replacing them, so an organization can grant and cannot take away.

"No active organization" was a 500. It is now 400 NO_ORGANIZATION, with a message saying to send the header or join an organization. The mechanism is worth having on its own: an error can implement respond.Coded to say what it should look like on the wire, which is how a package the response layer cannot import gets a decent answer instead of an opaque 500.

Ordering turned out to matter as much as presence. The first fix put the resolver after the permission gate, so a member whose only permission came from their organization role still got a 403: the gate read their grants before the organization had been resolved. On every authenticated group it now runs after authentication and before authorization, and CI asserts that order rather than trusting it.

The application that found these is kept rather than thrown away, which was the other half of the reviewer's advice. A new CI job scaffolds it on every push, with both plugins and both resource shapes, and runs 26 checks across the seams. That also closes something the stability page had listed as untested: multitenancy was not in the live suite at all. And grit doctor gained two checks, because a project that installed the plugin before today still has the old wiring and grit upgrade does not rewrite routes.go: one names the missing mount with the line to add, the other reports that a user provisioned by SSO joins no organization, which is a policy decision the framework should not make quietly.

One code, one status: the error taxonomy, end to end

A client needs two things from an error: a code it can branch on, and the certainty that the code always arrives with the same status. Grit had the first and not the second. VALIDATION_ERROR came back as 422 from thirty-eight handlers and 400 from twenty-five. INVALID_TOKEN was both 401 and 400. An upload that did not exist answered 400. And no page listed the codes at all, so the only way to learn one was to trigger it.

There is now one catalogue, and three things are generated from it so they cannot disagree: internal/respond/codes.go in every project, with a typed constant and the status for each of the 105 codes; packages/shared/types/errors.ts beside it, so a TypeScript switch over codes is exhaustive and a client that forgets one fails to compile; and the error codes page, which says what each code means and what a caller should do about it.

The part with teeth is a test that walks every template: a code a handler returns that is not in the catalogue fails the build, and so does a code returned with a status other than its own. That test is what made the statuses consistent, by listing the 31 sites that disagreed. Two of those were worth more than a status change: a request whose body could not be read is not a validation failure, so it answers INVALID_BODY, and a one-time link that has expired is not a credential, so email verification and password reset answer INVALID_LINK (400) rather than borrowing a 401.

Generated handlers now write errors through respond.Fail, which takes the status from the catalogue rather than having one typed beside the code, which is how the split happened in the first place. And the API reference says, per route, which errors it can return: a 401 on every authenticated route, a 403 only on resources where ownership or a role makes it reachable, a 409 on an update that can conflict, and for an owned resource the note that somebody else's row answers 404 rather than 403, on purpose.

Three of the release's own bugs, each caught before it shipped and each the same shape: a generated file that compiles in a test and not in a project. codes.go was only on the upgrade path, so a new project had generated handlers calling a function that was not there. The category constant for "notfound" was generated as CategoryNotfound, which gofmt parses happily and the compiler does not. And the per-route error responses were emitted without the dot that continues a method chain. Each now has a test: the scaffold path as well as the upgrade path, every identifier the generated file refers to, and a build of a real project.

The build reads the docs

"The docs said to do X and X did not work" is the most repeated root cause on this page. A command had been renamed, a flag never existed, a field type the generator refuses was in a tutorial. Every one of those was found by a person following a page, which is the most expensive way to find anything, and nothing in the build knew the docs existed.

Now it does. Every grit command shown anywhere in the docs, 586 of them, is resolved against the real command tree: the command has to exist, and so does every flag it is given. Every --fields spec goes through the same parser the generator uses. It found two bugs on its first run: a page telling people to run grit migrate:fresh, a Laravel spelling Grit never had, and a tutorial whose status:select field the generator refuses because a select needs options. Both are fixed.

That catches a command that is wrong, not steps that are each valid and do not work in order. So a block can claim more by naming a flow, verify="migrate-rollback", and the new Docs workflow scaffolds a project per flow, migrates it and runs that flow's blocks in page order on a real Postgres. Three flows are covered: the rollback walkthrough, grit doctor reporting nothing on a correct project, and a generated resource compiling and vetting clean.

What is deliberately not claimed: most blocks are not marked, because they start a server, bring up docker compose, or carry a placeholder only the reader can fill in. Marking those would be pretending. They still get the command and field-spec check, which is the half that rots quietly.

The checker is conservative by design, and two of its own mistakes are worth recording. It read prose as commands, because a changelog sentence began "grit can keep itself current" and a heading read "grit sync: Manual Type Generation", so it now only reads inside code blocks. And it was missing the first command of every multi-line block, the one sharing a line with code={`, which was most of the commands in these docs. The test now fails if that count collapses again.

Down migrations, for a framework that has no migration files

Grit migrates with AutoMigrate, so there is no up script and nothing to write a down script against. What there is instead is a fact worth using: AutoMigrate only ever adds, and never drops a column. So the reverse of a run does not have to be written by hand, it can be computed. Each run now snapshots the schema before and after, records the difference in two tables in your own database, and grit migrate down drops exactly what that run added: indexes, then columns, then tables.

grit migrate status shows the history, newest first, with what each run changed and whether it has been rolled back. grit migrate down takes --steps N, --dry-run, and --yes for CI. Every statement is printed before anything runs, because this is the one part no rollback can undo: a dropped column takes the data written into it since. Each drop is skipped if the thing is already gone, so a rollback interrupted halfway can simply be run again.

Two things it refuses. The first run on an empty database is the one that built the schema, recorded as a baseline: rolling that back would drop the database rather than undo a change, so it points at grit migrate --fresh instead. And a project scaffolded before this existed gets a baseline on its next migrate, because the schema it finds was built by runs nobody recorded. grit upgrade delivers the package and the rewritten cmd/migrate together, since either alone is a project that does not compile.

The tests that prove it ship into the project rather than staying in the CLI, and one of them found the first bug before release: SQLite reports its own sqlite_sequence table, which the history's autoincrement id creates, so a snapshot of an empty database was not empty. On SQLite no run would have been recognised as the baseline, and the first rollback would have offered to drop the whole schema. The live suite now adds a real column with grit generate field, rolls it back on Postgres 15, 16 and 17, and checks the column is gone, the table is not, and the baseline is refused.

Writing that check found a second bug, in grit generate field: it wrote to packages/shared and apps/admin without looking, the way grit generate resource never has. On an API-only project it failed on the first missing file, after the model had already gained the field, so the command reported an error having half done the work. It now injects the frontend where there is one, including the case of an admin panel with no definition for that resource.

A stability matrix per subsystem, and a weekly rollup over 343 releases

Three of the worst entries on this page were docs asserting a guarantee the code did not provide. So the stability and hardening page has one rule: a claim under "Grit guarantees" names the test that would fail if it stopped being true, and anything without such a test is listed as your responsibility instead. Twenty subsystems, each with an honest status (stable, beta, new), what is guaranteed and what proves it, what stays yours, and what went wrong once. It also gathers the numbers: 492 test functions in the CLI, 256 tests shipped into every project, 57 live checks on Postgres 15, 16 and 17, 13 grit doctor checks, and the scanners.

It says what is not covered, too, because a matrix that lists only strengths is marketing: no independent security audit, the framework's own handlers still query from their handlers, multitenancy is not in the live suite and not at all in combination with --tree or --public, there is no LTS channel, no signed desktop release has been verified end to end, and there are no production case studies yet.

The security guide asserted exactly this kind of guarantee while showing code from before v3.224.0: authz.MustOwn inside a generated handler. It now shows where the check actually lives, scoped in SQL for a list or an export and checked after loading for anything by id, answering 404 rather than 403 so a wrong guess cannot be told from a right one, with authz.MustOwn kept as the path for a handler you wrote yourself and the caller travelling on the context. Its pre-launch checklist gained rows for FIELD_ENCRYPTION_KEY, the Studio password, SENTINEL_AUDIT_KEY, --owned-by and grit doctor, and no longer points at a workflow file that does not exist.

This page now opens with "Releases by week", generated from its own entries by scripts/changelog-rollup.py, which also gave all 343 entries an anchor to link to. The generator refuses to write a partial result: its first version required an h3 title and would have silently dropped the 160 older entries that title themselves differently, which is the class of quiet half-success this changelog keeps recording.

The verification that found the bugs now runs in CI, on three Postgres versions

Grit's worst bugs were never found by a unit test. An export that returned an empty file with a 200, a list that handed one account another account's rows, a save that silently overwrote a newer one, a replace that appended instead of replacing: each was found by building a real application and using it, then fixed and verified by hand, once. tests/live/verify.py is that verification kept. It drives a running generated application over HTTP and reads Postgres behind it, because for some of these the database is the only witness: whether a column is really ciphertext, whether a move rewrote a subtree. 57 checks, green on the first run against a real project.

A new workflow scaffolds a project, generates the resource shapes those bugs lived in (owned, tree, public, money, encrypted, a relation, line items), migrates, starts the server and runs the suite, on Postgres 15, 16 and 17. The matrix is there because these are database behaviours: RETURNING, a materialised-path rewrite with REPLACE, sliding-window limits, and the way FindInBatches pages.

Two scanners join it. gosec runs over the CLI and over a generated application, with the rules a file-writing program trips by construction excluded: writing files at paths built from its own inputs is what a scaffolder is, and those rules produced 500 findings that would have taught everyone to ignore the scanner. What is left is zero across 317 files, so the next finding is a new one. Trivy scans a generated project's dependencies, secrets and Dockerfiles.

Trivy earned its place on the first run. A freshly scaffolded project carried five HIGH CVEs that govulncheck had not reported, because none are reachable from generated code: an XML signature validation bypass in goxmldsig, which on the SAML assertion path is an authentication bypass, where the newest release of the library that pulls it in still asks for the vulnerable version; two parser denial-of-service issues in excelize, which is what the CSV and XLSX importer hands user uploads to; an allocation DoS in golang.org/x/image, which decodes user images; and token parsing in golang.org/x/oauth2. All four are pinned as floors now, so grit upgrade carries them into existing projects too.

gosec found one pattern worth changing: two formatting loops in generated code indexed bytes while iterating runes. Harmless for the digits they are given, and the exact shape that truncates the first multi-byte character somebody passes in, copied into two files. Three findings that are right to keep now carry their reason in the code instead: TOTP is HMAC-SHA1 because RFC 6238 says so, the backup's table name comes from the model registry, and safefetch checks the destination itself. The README now carries CI, live and scan badges.

grit doctor: the mistakes that do not announce themselves

A build catches a type error and a test catches a wrong answer. Neither catches an encrypted column with no key, a list that was never scoped to its owner, or a database browser whose password is still studio. Those work, which is the problem, and every one of them was found the hard way once. grit doctor turns that into 13 checks over a project's models, handlers, services, routes, .env and go.mod.

It reports an unset FIELD_ENCRYPTION_KEY against encrypted fields, an encrypted column in a search or sort whitelist, an owned resource nothing scopes or one method that lost its scoping while the others kept it, the owner accepted from a request body, a resource that references a user and is scoped to nobody, a resource with no tenant.Owned in a multitenant project, PII-shaped columns left in the clear, an append-only resource still mounting writes, Studio with no login or a default password, default dashboard credentials and weak JWT secrets, framework libraries below their floors, Sentinel counting rate limits per process while Redis is configured, and a public allowlist publishing a held-back column. Each finding names its check and a fix; errors exit non-zero, so CI can run it, and --json prints the report for a machine.

The first thing it found was in the scaffold: every project shipped GORM_STUDIO_PASSWORD=studio, a known password on a tool that browses and edits every table, while the Sentinel and Pulse passwords beside it were generated per project. That is fixed here, so a new project reports nothing at all.

A linter that cries wolf gets turned off, so quiet on a correct project is a tested property, and the framework's own tables are not audited as resources: asked the loose way it called four of them possibly-owned in every project, including one with no resources of its own. Verified live: a fresh project reports nothing; a project with ten resources reported one real error and five real warnings; and on a generated owned resource, deleting the scoping from one method was reported as that method, with exit code 1.

Sentinel v2.5.0, GORM Studio v1.1.0 and Pulse v1.0.0, and grit upgrade raises them

Every new project pinned Sentinel v2.2.1, and v2.2.2 is a security release. Behind a trusted proxy a client could choose its own IP through X-Forwarded-For and slip per-IP rate limits, blocks and lockouts; sort_by on the dashboard's threat listing reached ORDER BY as it was sent; and several SSRF bypasses were open. Existing projects were worse off. grit upgrade rewrote framework files and never go.mod, so nothing would ever have moved them.

New projects pin Sentinel v2.5.0, GORM Studio v1.1.0 (read-only SQL enforced on the read path, fail-closed imports, composite keys matched in full) and Pulse v1.0.0, the tagged release of the commit already pinned. grit upgrade now raises each of the three to at least that version, never lowers one, and says why. On a project scaffolded with the old pins it raised all three, and the project still built, vetted and passed its tests.

New projects also use what the new Sentinel offers. When Redis is configured, rate limits and AuthShield lockouts are counted there, so replicas share them: counted per process, N replicas gave a client N times every limit. Two production replicas sharing one Redis refused the sixth failed login on a replica that had itself seen only three. The audit log's hash chain is keyed by a generated SENTINEL_AUDIT_KEY, and a UserExtractor reads the caller from the context, without which anomaly detection sees nothing. Both replicas booted with no Sentinel config warnings.

An existing project's routes.go is its own, so the counters, the audit key and the extractor are not added to it; the Sentinel page has the lines to add.

The import, public and tree endpoints query through the service too

v3.224.0 moved a resource's CRUD into its service, and three generated surfaces still queried from their own handlers. The CSV import ran every lookup and insert from a goroutine in the handler, the --public endpoints read through h.DB, and the tree handler looked a node's parent up itself before a reorder, outside the move's transaction. None of them passed the request's context down, which the multitenant plugin needs: it refuses a tenant-owned query that carries no organization.

The import's handler now takes the upload and answers 202, and services/<name>_import.go reads the rows, resolves their relations and writes them in batches. It runs on context.WithoutCancel of the request's context, so it keeps the caller and the organization and is not cancelled when the response goes out; an owned resource's rows still belong to whoever imports them. The public reads are service methods, with the allowlist left in the public handler you edit and passed in; a public handler you already have is kept as it is. Every tree service method takes a context, and Move takes the parent as a pointer, where nil keeps the one the node has.

Verified on a fresh project with 29 live checks against Postgres: moves, reorders and a rebuild on a tree; the public list, slug lookup, related items, category tree and subtree ids behind an API key; a CSV import that finds or creates categories by name; and owned imports, where an ordinary account's file cannot name another owner and an admin's can. grit upgrade on that project left every handler and service untouched. The generator's tests now check every generated handler for a stray query and every generated file's imports against what it uses.

The checks turned up one thing that is by design: public responses are cached by URL for cache.public_ttl_seconds (60 by default), so an archived product can stay in a cached list for up to a minute. Still to move are the framework's own handlers: auth, two-factor, uploads and the rest.

Generated handlers ran every query themselves, and the service beside them was never called

Reported by a user: in a new Grit app every handler talked to the database. It was worse than a matter of style. A generated handler made 27 GORM calls, and the services/ file generated beside it had its own List, Create, Update and Delete that nothing called, so a job that wanted the resource's rules had no way to get them.

The service is now the resource's data layer: list, export, get, create, update, patch, delete and bulk, holding the list whitelists, the writable columns, the --owned-by scoping, the If-Match version check and every transaction. Each method takes a context.Context. The handler puts the caller on it with authz.WithActor, a job uses authz.AsSystem, and on an owned resource a context with no caller matches nothing. The handler binds the request, calls the service, answers its error with 409, 404, 422 or 500, and sets the ETag. It runs no query.

The move turned up two more bugs, both fixed. A many-to-many id that matched nothing was dropped, so a PUT whose only tag id was mistyped answered 200 and left the row with no tags; it is refused with 422 now, and nothing is written. And the first live build failed on an import cycle, the service reaching for the database package that already imports services; single-statement writes are methods on the service instead, and a new test checks every generated file's imports against what it uses.

Verified on a fresh project with ten resources covering relations, money, encrypted and file fields, line items, a tree, audited reads, a public API and an owned workflow. go build, go vet and the generated tests pass, and so do 58 live checks against Postgres. They include 20 simultaneous saves of one version, where one landed and 19 got 409, and a staff user with delete permission who still could not delete another user's row.

Existing resources keep their handlers until regenerated: grit upgrade does not rewrite API code. It does add internal/authz/actor.go and the new concurrency helpers, which grit generate also adds when they are missing. Not moved yet: the CSV import, public and tree endpoints, and the built-in handlers (auth, two-factor, uploads and the rest), which still query directly. They are next.

Feature flags could not target a business unit, or be checked at all

Found building an ERP whose configuration differs by business unit. A flag could target individual user IDs, a percentage and a date window, so "on for the EU unit" meant listing every EU employee by hand and keeping the list in step with hiring. Worse, the flags package documented flags.IsEnabled(c, ...) and flags.Variant(c, ...), and neither existed: the only engine was a local variable inside routes.Setup, so no handler, service or job could check a flag.

Flag rules take attributes now, such as {"business_unit": ["eu", "ke"]}, matched against the attributes flags.AttributesFor supplies for the request (the user's role by default; replace it with whatever your users carry). A subject without the attribute does not match, so the rule fails closed. flags.IsEnabled, Variant and IsEnabledFor work from anywhere, and answer false before the engine has started. Both files moved to the set grit upgrade refreshes; in the API's own file list, no flag fix had ever reached an existing project.

Every project gets internal/flags/flags_test.go, which checks a business-unit rule and the package-level API against a real engine; it passed in the ERP project after the upgrade. Flags are still managed through the API: the admin has no flags screen yet.

v3.222.0's dashboard fix reached new projects only

v3.222.0 made the dashboard's stat cards and custom charts ask the API for a resource by its own name rather than the admin slug, which had failed every resource with a two-word name. A project upgraded to it kept failing: the widgets are written by two writers of their own, outside the admin's file map, and grit upgrade ran neither, so no fix to those files had ever reached a project that already existed.

Upgrade now runs them, from the same list the scaffold uses, so the two cannot drift apart again. They are written through the same guard as every other framework file, so a widget you have edited is still reported rather than overwritten. Verified on the ERP project: the upgrade rewrote the stat cards and the chart card, and the dashboard's requests for its three two-word resources, which had each answered 400, answered 200.

--i18n projects did not compile, and the admin was English-only anyway

Found building an ERP for a multi-region workforce. A project scaffolded with --i18n failed its type check in both the admin and the web app: the language switcher imported a dropdown menu component neither app ships, and even with that fixed, every production build stopped with "Couldn't find next-intl config file": the scaffold pinned next-intl 3, which supports Next up to 15, on Next 16. It pins next-intl 4 now, and an upgrade moves an existing pin up. The switcher was also never mounted anywhere, and not one admin component read the catalogues that were written, so nothing a user could do changed the language. Every upgrade then reported the six files i18n edits as edited by you and never updated them again, because the edits were never recorded.

The switcher is a native select now, mounted in the admin's page header and the web app's navbar. The admin translates through a small t(key, fallback) in lib/i18n that needs no dependency and returns the English it always showed until i18n supplies a catalogue: the sidebar, toolbar, pagination, empty state, row actions and form buttons and headings, plus each resource's own name, column headers and field labels, keyed under resources.<slug> and falling back to the definition's label. grit add i18n records what it writes, adopting its edits only in files that were untouched, so a file you edited stays yours.

grit upgrade repairs an existing i18n project: it replaces the broken switcher, mounts it, feeds the admin its catalogue, and takes back the files that differ from its template only by its own i18n wiring. It does the same for a tsconfig.json that next build rewrote: Next 16 sets "jsx": "react-jsx" and adds its dev types on the first build, which made the file read as edited by you from then on. The templates carry those values now, and a rewritten file that means exactly what the template means is taken back. Catalogues are yours to edit and are still never replaced, but keys added in a later release are merged into them, so an upgraded project does not show English in the middle of a translated page.

Two more things the same project turned up. The dashboard's stat cards and custom charts asked the API for a resource by its admin slug (purchase-requests) while the API registers it under its own name (purchase_requests), so they failed for every resource with a two-word name; they ask by the API's name now. And a generated resource was labelled with its Go type name, so the sidebar read "InventoryItems"; new resources are labelled "Inventory Items".

Verified on an ERP project scaffolded with --i18n before this release: both apps failed their type check, one upgrade adopted all six files and re-wired them, both apps then type-checked clean, and a second upgrade left nothing alone.

A workflow could change a status, and nothing else

Found building an ERP, where approving a purchase request has to draw down the department's budget and reserve the stock, and fulfilling it has to reach the HR ledger. A generated transition was one UPDATE and an in-memory event. Work belonging to the move could only go in a subscriber, which ran after the approval had committed, could not refuse it, and, being async, was lost on a restart or a full queue and never retried. The outbox that would have made it reliable was scaffolded into every project, and nothing started its relay.

Transitions now run in a transaction. Hooks registered with workflow.OnTransition run inside it, after the status changes: what they write commits or rolls back with the move, and workflow.Refuse undoes it with a 422 carrying your reason. A new Durable delivery, with events.OnDurable for subscribers that write to the database, writes the event to the outbox in that same transaction, and a relay started at boot delivers it with retries, across restarts and replicas. events.On called from an init(), which used to be dropped silently because it ran before the bus existed, now takes effect. A transition that failed for any unrecognised reason answered 403; it is now a 500, with the detail in the log.

Verified on Postgres with a purchase-request workflow: an over-budget approval and one without stock were refused, the second rolling back its budget draw-down; ten simultaneous approvals of 100 against a budget of 600 approved six and left it at zero; twenty simultaneous approvals of one request drew it down once; seven fulfilments reached the ledger through a subscriber that failed its first two deliveries, once each; and one the ledger refused until the API was restarted was delivered by the restarted process. grit upgrade adds the files and starts the relay in an existing routes.go; regenerate a workflow resource to give its transitions the transaction.

A custom role could not reach a single admin endpoint

Found building a marketplace with a support team who should see users and nothing else. Every admin route sat in one group behind the ADMIN role, so the perm: guards written on some of them never ran: a role granted users.view was refused by GET /api/users, and the seeded EDITOR was shown admin pages the API then refused. The same was true of generated deletes: granting products.delete did nothing.

New projects split the admin API in two. A staff group admits anyone holding a permission, and every route on it names the one it needs: users, roles, access reviews, the audit log, jobs, backups, blogs, the Sentinel and Pulse summaries, and the per-resource dashboard stats (which ask for the view permission of the resource in the URL). The admin group stays ADMIN-only for routes that name no permission, such as SSO connections, form sharing and writing settings, so anything that forgets one, a plugin's route included, fails closed. Generated delete and bulk routes go on the staff group and ask for <resource>.delete. The sidebar shows the System Hub by permission instead of by role name.

Verified on a fresh project: the EDITOR lists users and is refused deleting one, backups, jobs, SSO and settings; a USER is refused at the gate; a custom role granted products.delete deletes a product and still cannot list users. grit upgrade does not restructure an existing routes.go; it says so, and the Roles & permissions page shows the change. Until then generated deletes on such a project stay ADMIN-only, as before.

Two people saving the same record: the second silently won

Found building a bidding marketplace. Every generated record carried a version that each update incremented, and nothing ever checked it, so two people who loaded a lot at the same version and both saved got last-write-wins with no word to the first. For a bid, that is a lost bid.

Generated PUT and PATCH routes now honour If-Match. Reads return the version as an ETag; a write carrying it lands only if the record is still at that version, and otherwise gets a 409 VERSION_CONFLICT naming the current one. The check is the WHERE clause of the update, so it holds under contention and across replicas. Without the header nothing changes. Verified with twenty simultaneous bids on version 1 split across two copies of the API: one landed, nineteen were refused, the stored bid was the winner's, and the same twenty without the header all went through as before.

Resources generated from this release on get it. grit upgrade adds the internal/concurrency package; regenerate an existing resource to give its routes the check.

A revoked permission kept working on the other replicas

Found running two copies of an API behind one database, as a load balancer would. Each copy caches who may do what, and a role change cleared the cache only in the copy that made it. Reproduced: a permission revoked through one copy was still granted by the other ten seconds later, and would have been until it restarted.

Copies now share a small cluster_generations table. A role change bumps it, and every copy checks it at most once a second and drops its cache when it moves. The same table carries SSO: a connection created through one copy was unknown to the others, and now every copy rebuilds its identity-provider connections when another saves one.

Every replica ran every scheduled job

asynq's schedulers do not coordinate, and every copy started one, so each copy ran the token sweep, the orphan-upload cleanup and the log prune. Only the copy holding a Redis lock runs the scheduler now. The lock is a 30-second lease renewed every 10, so if that copy dies another takes over.

Running more than one instance

A new page, Running more than one instance, covers what the copies must share, what is already shared between them, and what is still counted per copy. Realtime needed nothing: one event caused on one copy reached 1,000 sockets on another in 0.16 seconds, through the Redis backplane that was already there. Sentinel's per-IP rate limits are still per copy, which is filed as Sentinel #18.

grit upgrade adds the cluster package, updates the permission cache and the SSO service, wires both into routes.go, and patches the four generated lines of cron.go that start the scheduler. Verified with two copies after the upgrade: a revoked permission stopped working on the other copy within three seconds, where before it was still granted ten seconds later; a new SSO connection worked on the other copy within a few seconds; one copy held the cron lock, and when it was stopped the other took over 25 seconds later.

A customer's identity provider could sign in as your administrator

Found testing enterprise SSO end to end against a mock identity provider. After matching on the IdP's subject, sign-in fell back to linking any existing account with the same email address, and never checked that the address belonged to one of the connection's domains. The customer controls their IdP, so the customer's IdP admin could assert admin@yourapp.com: reproduced, it signed in as the app's ADMIN. The same gap let it provision accounts at any domain.

A connection's email domains are now the only addresses its provider is trusted for. Linking by email and provisioning both refuse any other address, and so does an existing link, so an identity an attacker linked before this release stops working too. A connection with no domains can sign nobody in. If you ran SSO before this release, look through user_identities for links to accounts outside their connection's domains.

Leaving a directory group did not revoke its role

The docs promised that removing someone from a mapped group revokes the role on their next sign-in. Moving to another mapped group did; leaving every mapped group kept the old role. They now drop to the connection's default role, or USER.

Six more

• IdP-initiated SAML sign-in could not be turned off. GORM named the column allow_id_p_initiated and the update wrote allow_idp_initiated, so switching it off returned a 500 and left it on. The column name is now pinned.
• Once it could be, it would have refused every login, including the ones that started here: responses were checked against no request ids at all. Each sign-in now remembers its request, and the response has to answer it.
• Two connections could claim one email domain, and discovery sent the address to whichever row came first. A domain now belongs to one connection.
• A transient SAML NameID was used as the identity, so every sign-in linked another one. Transient ids are now passed over for the email.
• A partial update of a connection wiped the fields it did not send, the metadata URL among them, which took a SAML connection offline over an unrelated edit.
• Every reload logged an error for each SAML connection, from the OIDC registry trying to build it.

grit upgrade carries all six to existing projects. Verified end to end against a mock OpenID Connect provider and a SimpleSAMLphp identity provider: provisioning, group mapping and revocation, an address renamed at the IdP, IdP- and SP-initiated SAML with IdP-initiated sign-in on and off, and the attempts to sign in as the administrator or outside the connection's domains, which are refused.

Who read a record: --audit-reads

Found building a patient-records app. The activity log recorded every write and skipped every read, so the first question an access review asks, who looked at this patient's chart, had no answer.

A resource generated with --audit-reads now records every read in the same tamper-evident chain as the writes. A list records the ids on the page it returned, a read by id and its PDF record that id, and an export records its row count. The query string is kept as a digest, because a name typed into a search box is personal data too, and only successful reads count. Writes now record the id of the record they changed, so the admin audit page's new Record id filter lists everyone who read or changed a record. Also in a YAML definition as audit_reads: true, and inherited by line items.

Off by default, since reads are most of all traffic. Refused with --public, whose reads are anonymous, and with --tree, whose endpoints return the whole hierarchy at once. A project from before this release is told to run grit upgrade first rather than getting handlers whose reads nothing would record. Verified on a live project: an ordinary account's list, search, record read, PDF and export each landed in the log with who, which rows and when, the search term was stored nowhere, a search by record id found the reads and the edit, and the chain still verified.

The activity log never verified on Postgres or MySQL

Found while adding read auditing to a patient-records app: the integrity check reported the chain broken at its very first entry, on two projects whose logs nobody had touched. The hash covers each entry's timestamp. The writer stamped it in nanoseconds and Postgres stores microseconds, so the row read back never hashes the way it was written. Proven by taking a stored row and finding the 400 nanoseconds that reproduce its stored hash exactly. MySQL keeps milliseconds and failed the same way; SQLite keeps what it is given, which is why no test ever saw it.

Entries are now stamped by the writer itself, at millisecond precision and strictly after the entry before, so verification walks them in the order they were written. Each batch also takes a database lock and reads the latest hash from the database. Before, every process kept the latest hash in memory, so two API replicas would each have chained off their own and forked the log.

Security events were written outside the chain

LogSecurityEvent inserted rows with no hash at all. Nothing in a stock project calls it yet, but the first call would have broken verification, and the unique index on the hash column would have refused every event after it. It now writes through the chain like everything else.

Logs written before this release

grit upgrade installs the new writer. Entries written before it can never verify, through no one's tampering, so the admin audit page now offers a reseal from the first bad entry. You type the entry's id to confirm; the reseal recomputes the chain from there and records itself in it, with who did it and a digest of every hash it replaced. A reseal trusts the rows as they stand, so it is never automatic. Verified on both projects: each chain failed at its first entry after the upgrade, verified after a reseal, and still verified after 50 concurrent writes.

Owned resources checked the owner on four doors out of eight

Found building a patient-records app. A resource generated with --owned-by scoped its list and checked ownership on read, update and delete. Everything else that reaches a row did not. Reproduced with two ordinary accounts: the second printed the first one's clinical note through the PDF endpoint and rewrote it with PATCH. Export had no scope, Bulk had none for a role allowed to reach it, a workflow transition moved anyone's row, and the CSV importer took the owner from a column, so a file could put records under somebody else's name.

All of them now check. PDF and PATCH answer 404 on somebody else's row, as read does; export and bulk only see the caller's rows; a transition checks the owner; imported rows belong to whoever imports them, and only an ADMIN may name another owner. --tree with --owned-by is refused, because the tree endpoints have no notion of an owner and would have handed the hierarchy to everyone.

Every CSV export was empty

The same session showed an export returning a 200 with no body, for every resource. GORM's FindInBatches hands its callback a fresh session with no query on it, and the handler re-read each batch through it, found nothing, and threw the error away. Export now reads each batch from the slice FindInBatches fills, writes the header even when nothing matches, and reports a failure instead of discarding it. It also stopped sorting ahead of the key it pages by, which would have repeated rows past the first thousand.

The importer created an account for every email it did not know

A belongs_to:User column was resolved by email, and an unknown one created a user with that email and nothing else. Any signed-in account could mint accounts around registration that way. A user must now exist, or the row fails with a message saying which one was not found.

owned_by in a --from file was thrown away

A resource defined in YAML with owned_by: user was generated with no owner scoping at all, and its create endpoint demanded a user_id in the body. The command-line flags were assigned over the file, so an unset --owned-by erased it, and tree, public, append_only and tenant_owned went the same way. Flags are now merged into the file: they can add, never remove.

A resource with a workflow did not compile

Its transition routes were injected into routes.go against a handler variable that only projects from before per-resource route files declare, so the API stopped building the moment the resource was generated. They now live in the resource's own route file, behind its role guard when it has one. Generating the resource again removes the broken lines from routes.go.

The next steps left out the migration

The API does not migrate on start, and the steps printed after grit generate resource said to build and restart, which leads straight to a 500 about a missing table. They now say to run grit migrate in between.

Existing projects

Upgrade does not regenerate resource code, so grit upgrade patches the export and ownership fixes into generated handlers, importers and workflow services wherever the generated text is still recognisable, and names anything too changed to patch. Verified on the project where this was found: after the upgrade, all 13 checks passed across two ordinary accounts, and a resource freshly generated from YAML with an owner and a workflow passed its own.

Erasing a user left the records they owned

Found building a patient-records app. Right-to-erasure deleted rows from a fixed list of nine framework tables and anonymized the user. A provider's notes, generated with --owned-by user, stayed exactly where they were, while the deletion journal recorded the erasure as complete.

What erasure deletes is now a registry. The framework's own tables register from one file, and every resource generated with --owned-by registers from its model file, so the rows a person owns go with them. Append-only resources are not registered: their rows cannot be deleted, and which of retention or erasure wins is left to the project rather than decided quietly. Verified on a live project: two notes owned by the erased user went, and another user's note stayed.

Restoring a backup brought erased people back

A backup taken before someone was erased still holds them, and restoring it put them back. Worse, it replaced the deletion journal with the archive's older copy, so the entry proving the erasure had happened disappeared too.

Restore now reads the journal before clearing anything, puts back the entries the archive is missing exactly as they were, and erases those people again. Verified by erasing a user and then restoring a backup taken while they were present: the restore reported one erasure re-applied, the user stayed anonymized with their records gone, and the journal still verified with its original hash. The journal lives in the same database, so a restore into an empty one has nothing to consult; the compliance page covers exporting it.

grit upgrade carries both to existing projects.

A note on v3.211.0. It was tagged in error on the v3.210.0 commit and published before that could be stopped. Its contents are exactly those of v3.210.0; everything described below arrives in this release.

Encrypted columns were stored in plaintext after the first edit

Found on a patient-records app. Creating a patient stored the notes as enc:v1: ciphertext. The next PUT stored PUT: diabetic in the column as plain text, and the next PATCH did the same. Nothing showed it: reads came back right, because a value without the prefix is passed straight through, and search even started finding the rows, which it only could because they were no longer encrypted.

Generated update, PATCH and bulk handlers write a map of plain strings, and GORM only runs a column type's encoder when the value already has that type. crypto.Install, now called when the API connects, wraps any string headed for an EncryptedString column, and a test that ships with every project checks the raw column after a map update. grit upgrade adds the call to existing projects. Grit's own encrypted fields, the profile bio and the SSO secrets, were always converted by hand and were not affected.

Values written through an update before this release are still plaintext. They are re-encrypted the next time they are saved; to find them, look for rows whose column does not start with enc:v1:.

An :encrypted field modifier

The security page said to adopt encryption by changing a field's type to crypto.EncryptedString, "that's it". On a generated resource that broke the build twice, in the handler and in the CSV importer, since a plain string does not convert into the type by itself. notes:text:encrypted now makes the type the field's own in the model, both request structs and the importer, keeps the column as text because ciphertext outgrows a varchar(255), and leaves it out of search, sorting and filters, where ciphertext could only ever be noise. It refuses :unique, which non-deterministic ciphertext could never enforce, and works with grit generate field too.

Backups could not be restored

Two ways, found by restoring real projects. Every project with line items took backups it could not restore: the dump writes tables in the order the models are registered, the generator registers a child before its parent, and replaying the lines before their journal entries failed on the foreign key. And every project using --append-only, added in v3.207.0, refused the restore outright, because restore begins by truncating and those tables refuse to be truncated.

Restore now replays in foreign-key order, worked out from the models' own relationships, which also rescues archives already written, and lets itself past the append-only triggers for its own transaction only. Verified on both projects after grit upgrade, which now carries the backup package: the line-item project restored 45 rows with no orphaned lines, and the append-only one restored 62 rows with all four triggers enabled again and a raw UPDATE still refused.

grit upgrade wrecked TanStack projects

Upgrade never read which frontend a project uses. It built its options from the name, the style and the version, and an unset frontend defaults to Next.js, so every project was upgraded as though its apps were Next apps. On a TanStack project that wrote the Next admin and web apps, package.json included, over the Vite ones: both came out depending on next, with vite and the router gone and two apps' worth of files in each directory.

Upgrade now reads the frontend from grit.json, falling back to a vite.config.ts on disk for projects older than that field. The refresh it performs is written for the Next layout, so on a Vite app it now leaves the app exactly as it is and says so; a Vite equivalent is still to come. The API, shared packages and the security and passkey pages, which already knew how to write for Vite once told, are upgraded as before. Verified both ways: on a fresh TanStack project both apps kept vite and gained no Next files, and a Next project was refreshed as it always was.

The Vite apps' tests could not start

Every Vite admin and Vite web app shipped with pnpm test failing before a single test ran. The shared setup file imports @testing-library/jest-dom, the tests use @testing-library/user-event in a jsdom environment, and none of the three was declared. Under that, vitest walked up the tree for a PostCSS config and found one at the repository root, in Tailwind v3 style, which no app used and which named autoprefixer, never installed.

Both Vite apps now declare their test libraries, the vitest configs pin an empty PostCSS setup, and the root config is no longer scaffolded. On a fresh TanStack project the admin's suite now runs and passes. An existing project can delete its root postcss.config.mjs: nothing reads it.

The web navbar test could not pass

The navbar test shipped to every web app asserted a "Components" link, left over from the components page removed in v3.31.78, and the navbar it renders has no such link. pnpm test in apps/web had failed on every fresh Next project since. A check now fails the build if the test asks for a link it does not render.

Read-only and computed admin fields

A form field can now be readOnly, or carry compute: (values) => ... to derive its value from the rest of the form, recomputed as it changes. Both are shown the way the table shows the column, so a money field reads as money, and both are left out of what the form submits, across the standard form, the step-by-step form, its per-step saves and grouped editing.

That second half is the fix as much as the feature. The only way to show a value was a disabled input, which is still sent, and over a column the server computes and the PATCH allow-list names, saving the form wrote the displayed figure back over the server's. Found on a ledger, where the journal form now shows debits minus credits as the lines are typed. See read-only and computed fields.

Two projects on one machine were sharing a Redis

v3.205.0 moved the host ports into .env so a second project could start, and said the service addresses would follow. Only Postgres did: its URL is built from POSTGRES_*. REDIS_URL and MINIO_ENDPOINT were written into .env with the default ports baked in, so a project that moved REDIS_PORT kept dialling 6380. With another Grit project running, that is the other project's Redis, and nothing fails, because it answers.

Found on a ledger whose API had been using a storefront's Redis and MinIO while its own containers sat idle. The two shared a cache, a bucket host, and a job queue whose queue names are the same in every project, so either project's worker could pick up the other's tasks.

Both addresses are now built from REDIS_PORT and MINIO_PORT unless you set them, and new projects leave them unset. An explicit localhost URL that disagrees with its port is named in a warning at startup. grit upgrade reads an existing .env and prints the exact line to set, without rewriting the file. If you moved either port on v3.205.0 or later, run grit upgrade or check those two lines by hand. Verified on a fresh project with every port moved: its own Redis went from empty to holding the worker's keys at startup.

grit generate job

The cron page said new scheduled tasks are added "when you use grit add cron". That command did not exist. A custom job was five hand edits across two framework files, and the worker's handler list had no marker to anchor on, so the step most likely to be missed was the one that made the job run.

grit generate job ReconcileLedger --cron "30 23 * * *" writes the job with its payload, a typed enqueue method and the handler, registers the handler with the worker, and schedules it where the admin's Cron page lists it. It never overwrites a job you have written, and on a project from before the marker it registers the handler anyway and leaves the marker behind.

Load-tested on the ledger as an end-of-day reconciliation: 1,000 tasks fanned out one per account, then the same 1,000 queued again. The second thousand were refused as duplicates by their idempotency keys, every account was reconciled exactly once, the queue drained in under nine seconds, and nothing was left retrying or archived. The jobs page now covers batches like this.

Converting between currencies

The money package had no conversion, and the improvised one is wrong twice. MulFloat keeps the currency's decimals, so 10.00 USD at 148.2 relabelled as yen is 148,200 yen, a hundred times too much. And a float cannot hold most rates: 1.005 is 1.00499999999999989 in binary, so a dollar at that rate comes out as 100 cents instead of 101.

money.Convert(to, rate) takes the rate as a decimal string, parses it as an exact fraction, moves the decimal point for each currency's minor unit, and rounds once, half away from zero. Its tests ship with every project.

grit generate field reaches the API

grit generate field Account notes:text added the column to the model, the Zod schemas, the TypeScript type and the admin, and stopped there. Generated handlers do not bind into the model: they bind into CreateAccountRequest and UpdateAccountRequest and copy fields across one by one, and PATCH writes only what an allow-list names. So the admin showed the new field and sent it, and the API threw it away:

with the column sitting empty in Postgres. The field now goes everywhere the generator would have put it: both request structs, the create literal, the update map, the PATCH and bulk-edit allow-lists, the list's sort and filter whitelists, and the CSV importer and its template. The rest of each file is left as you had it, and the command is safe to run twice. The rules are copies of the generator's, pinned to it by a test that fails the day either changes. Verified against Postgres: create, update, patch and a CSV import each stored the new value.

A date field broke the build

The same command put *jsontime.Date into a model that did not import jsontime, so adding a date or datetime field stopped the project building with undefined: jsontime. Both types were listed as supported. The import is added with the field now.

v3.205.0 pointed you the wrong way

When a regenerate refuses because you have edited a resource's files, the message said to add the field to the model by hand and run grit sync. That has the same hole: sync updates the types, the schemas and the admin, and never the handler, so the field was shown, submitted and dropped. The message and the generated-files page now send you to grit generate field, and say why the hand-edited route is not enough on its own.

Append-only records, and a ledger nobody can rewrite from a web page

Found building a double-entry ledger. The generator gave a journal entry PUT, PATCH, DELETE, bulk and import routes, a soft-delete column and an admin with Edit and Delete: the right shape for a CRUD resource and the wrong one for a posted accounting record. Hand-rolling the fix took a package of GORM callbacks and an edit to main.go the framework offered no place for.

And it still lost. The callbacks stopped the API, the importer and GORM Studio's row editor. Then UPDATE journal_lines SET debit_amount = 1, typed into the Studio SQL editor, returned 200 and unbalanced the books. That editor sends statements to db.Exec, and a raw statement never passes a GORM callback.

grit generate resource X --append-only now does all of it: read and create routes only, a GORM guard that answers 422 with the reason, a trigger on the table installed by grit migrate for everything that is not GORM, and an admin that offers create and view. An --items child is append-only with its parent. Against Postgres, the API, the Studio row editor, the Studio SQL editor and psql were each refused, and the row was unchanged.

New projects make the two calls that install the guard. grit upgrade adds them to older ones, and the generator does too the first time the flag is used, or stops and names the call if it cannot find where it goes. A model registering with a guard nobody installs would look protected and not be. See Append-only records.

GORM Studio's write switches are reachable

gorm-studio has always had ReadOnly and DisableSQL, and nothing in a Grit project could set them. They are GORM_STUDIO_READ_ONLY and GORM_STUDIO_DISABLE_SQL now, and the production environment template turns the SQL editor off.

The admin detail page ignored table.actions

The list page asks whether a resource allows edit and delete before offering them. The detail page never did, so a resource that removed both from its table still showed the buttons one click further in. It asks the same question now.

A rule your model enforces now reaches the caller

Every generated handler bound the error from a write and never used it:

if err := h.scoped(c).Create(&item).Error; err != nil { c.JSON(500, ... "Failed to create invoice") }

So a rule enforced in a GORM hook, which is where a rule has to live if GORM Studio and the CSV importer are to respect it as well as your service layer, reached neither the client nor the log. Found building a double-entry ledger, where USD does not balance: debits 100.00 USD, credits 99.99 USD arrived as Failed to create journalentry with status 500.

Errors from a write are mostly not for the caller: a driver failure or a constraint violation carries schema details and sometimes SQL, so the handler cannot simply echo what it gets. respond.Rule is how your code marks the ones that are. Return it from a hook, a callback or a service method and the caller gets 422 with that sentence. A missing row gives 404. Anything unmarked keeps the same opaque 500 it had before, and is now logged on the way, which it was not.

Documented under Invariants, and telling the caller why.

--items generated a handler that did not compile

The inline Items request struct is built from the child's fields and written into the parent's handler, so a money field on the child puts money.Money in that file. The import scan walked only the parent's fields, so nothing added the import and the project failed to build with undefined: money. The same hole covered jsontime, datatypes and time. The scan now covers both.

--items silently dropped the child's belongs_to

The builder skipped every belongs_to on the child, on the grounds that the foreign key back to the parent is set by the association and clients never send it per row. True of the parent's key. Not true of one pointing anywhere else, and those are exactly the ones the client has to send: the account a journal line posts to, the product an invoice line bills.

So the request had no way to say which account, the create loop set nothing, and every line was inserted with an empty account_id while the model declared the column required. No error, just wrong rows. Only the parent's own key is skipped now.

grit upgrade left a project unable to build

Upgrade does not regenerate API code in general, deliberately. But the generator writes calls into internal/respond, so a project carrying an older copy got freshly generated handlers referring to a helper it did not have. Upgrade reported "Updated 268 files" and success, and the build failed on five undefined references with nothing connecting them to the command that claimed to have handled it.

internal/respond now upgrades alongside internal/money, for the same reason: these are the packages the generator emits calls into. Both are manifest-guarded, so a project that edited them is reported as a conflict rather than overwritten.

A promised sidebar entry that was never written

A triple project always closed a generate with "the admin panel will show Widgets in the sidebar", including when there was no apps/admin/resources to write to. The resource definition and both screens were skipped, nothing said so, and the run still ended with a green tick. Found by renaming apps/admin to see how the CLI copes; the same path is reached by a bad merge or a partial checkout.

The message now says what was skipped and what was not. Everything else about that case was already fine: the API, the shared types and the web hooks are generated, and both grit sync and the Go build work with an app folder missing or renamed.

Re-running a generate destroyed hand-written code

Adding a field by re-running grit generate resource with one more entry in --fields is the obvious thing to do: you already know the command. It rewrote the model, the service and the handler from scratch, printed a green tick for each, and everything hand-written in them was gone. No prompt, no backup, and nothing in the output to say a file had been replaced rather than created. --force was not required; a plain re-run did it.

Which is the opposite of what this site promised. The generated-files page called apps/api/internal/services/<name>.go the place "your custom business logic goes here" and said of regeneration that it "never touches" it. So the file a newcomer was told was safe was the file that lost their work, and the reassurance that made re-running the command feel safe was in writing.

Grit already records who wrote every generated file and a hash of what it wrote. It now compares before regenerating: if you have edited any of a resource's files, the command stops, names them, and points at the non-destructive route, which is to add the field to the Go model and let grit sync carry it through the types, the Zod schemas and the admin columns and form. --force still overwrites, deliberately. The .custom.tsx overlay is exempt: editing it is what it is for, and generation never rewrote it.

A resource you have not customised regenerates exactly as before. The documentation now describes what the command does rather than what it was hoped to do.

grit migrate failed on Postgres

The documented default database, on the documented quick-start path:

Migration failed: migrating *models.Passkey: ERROR: type "blob" does not exist (SQLSTATE 42704)

Three []byte columns on the passkey model carried gorm:"type:blob", which is SQLite spelling. Nothing needed the override: GORM already maps []byte to bytea on Postgres and BLOB on SQLite, so removing it makes the model portable rather than changing it. The desktop sync store keeps blob, correctly, because its database is always local SQLite. Verified by migrating and seeding a fresh project against Postgres, where the column is now bytea.

A second project could not start

Every Grit project bound the same host ports, so docker compose up -d on the second one failed with Bind for 127.0.0.1:6380 failed: port is already allocated — at step two of the quick start, which anyone evaluating the framework reaches by the end of the first afternoon.

.env said above these values "single source of truth: edit ONLY the POSTGRES_* values below", and that was not true of the host port: compose hardcoded it, so editing .env moved what the API dialled and left the container bound where it was. Compose reads .env from the project directory on its own, and now does, for Postgres, Redis, Mailhog and MinIO. Defaults are unchanged, so nothing moves for an existing project.

The generator named a file it had not written

Resource definitions moved to a folder each, so a new project gets apps/admin/resources/posts/posts.ts. The success output still announced apps/admin/resources/posts.ts, which is the first thing anyone opens after a generate and the first thing that does not open. grit sync printed the same stale path in two more places.

The same block also wrote posts.custom.tsx, the overlay that is never regenerated and therefore the only safe place to customise, and said nothing about it at all. So the one file worth knowing about was hidden and the one it pointed at was not there. Both now report the path on disk, and the overlay is announced the first time it is created.

The production images did not build on a fresh project

Found by building an invoicing app and following the VPS guide as far as it goes without a server: scaffold, then docker compose -f docker-compose.prod.yml build. The API image was fine. Both Next images failed, for two reasons.

The Dockerfile did COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./, and grit new does not write a lockfile: pnpm does, on the first install. So the build stopped at the first COPY with "/pnpm-lock.yaml: not found". The lockfile is now a glob, and --frozen-lockfile is used only when there is one to freeze to, so a repo that commits its lock keeps reproducible installs and a fresh project still builds.

Past that, pnpm stopped with ERR_PNPM_WORKSPACE_PKG_NOT_FOUND. The image copied two workspace manifests by name, and both apps depend on @repo/upload as well as @repo/shared. A list of workspace members maintained by hand in a Dockerfile goes stale the first time one is added, and had. It copies packages/ now, so whatever the workspace gains is in the image the day it lands.

Verified by building all three production images from a project that had never run pnpm install.

Line items were typed as plain text

An inline --items child had its own switch over field types, covering five and falling through to text for the rest. Money, toggles, selects, textareas and rich text all rendered as text inputs.

On an invoicing app the field it got wrong was unit_rate: type: "money" in the standalone InvoiceItem resource and type: "text" inline, in the same generation run. A currency amount in a plain text box, on the line the whole invoice multiplies. Line items now use FormFieldType(), the mapping the rest of the generator uses, and selects carry their options.

You can write a plugin now

The authoring page described a plugin as a plugin.Plugin value and ended by pointing at internal/plugin/multitenant.go, which is inside the CLI. So a reader who followed it had nowhere to put what they had written: the registry was compiled in, writing a plugin meant forking Grit and rebuilding the binary, and the page never said so.

grit plugin add ./plugins/product-reviews

A plugin directory holds a plugin.json manifest and the files it installs. It is the same shape as a built-in, so nothing about installing or removing changes: the same lockfile records what was written and grit plugin remove replays it backwards either way. {{MODULE}}, {{PROJECT}} and {{API_ROOT}} are substituted, so a plugin does not need to know the module path of the project installing it. A when clause limits a file or an injection by architecture and frontend.

Paths that climb out of the project are refused when the manifest loads, because a plugin is somebody else's code and "to": "../../.ssh/authorized_keys" is a file write rather than an install. Only an explicit path is read as a directory, so a folder cannot shadow a built-in by sharing its name.

Proven by writing one: a product-reviews plugin with two files and five injections, installed into a storefront, exercised end to end (public reads with an average, held writes, duplicate refused, admin approval, public read after approval), then removed, leaving only the lockfile behind.

The marker list on that page was also three releases stale. grit:imports, grit:middleware:protected, grit:nav:system and the two icon markers all exist and were added because plugins needed them.

The AI handlers were throwing the error away

Both took the error from the ai package and returned "Failed to generate completion". Not logged, not categorised, not returned. A rejected key, a rate limit, a model that does not exist and a DNS failure all looked identical, and the server log said nothing at all.

Met while testing product-description generation: Grit said "Failed to generate completion" while the gateway had said "Free tier users do not have access to this model". That second sentence is the entire answer. Failures now come back as AI_UNAUTHORIZED, AI_RATE_LIMITED, AI_MODEL_NOT_FOUND or AI_FORBIDDEN, and the gateway's own words go to the log rather than to the caller, since it is somebody else's error text and may quote the request back.

.env.example now says that the default model needs paid credits, which is the specific thing a free-tier key meets first.

The offline sync engine has tests now

It is the least testable-by-hand and most consequential part of the desktop app: it decides what happens to a change made on a plane, and what happens when the server moved underneath it. It shipped with no tests, so every one of those decisions had only ever been checked by using the app.

Five tests ship with every desktop project, running against an httptest server standing in for /api/sync: a local write is readable before it is pushed, a successful push clears the queue and records the server's version, a version conflict parks the change with the server's copy attached and the local edit intact, a conflicted row is not retried behind the user's back, and resolving one replays it at the version the user actually saw.

The engine passed all five on the first run. That is the useful result: the behaviour was already right, and now it stays right.

The desktop app did not build on a fresh project

apps/desktop is a second Go module, so tidying apps/api during grit new never reached it. go build ./... inside it failed on four missing go.sum entries, including the SQLite driver the offline engine is built on. grit new-desktop had always tidied the standalone project; the combinable --desktop path had not. It does now, and a failure there warns and prints the command rather than losing the whole scaffold.

grit sync says which screens it could not update

Found by running the multi-client project on an Android emulator: a column added to a Go model mid-project was in the API response and in the shared type, and the mobile create form still showed the original three fields. Nothing anywhere said so.

grit sync keeps three things current: the shared TypeScript type, the Zod schema, and the admin resource definition, which is patched through markers so customised entries survive. The mobile forms and screens and the desktop columns have no equivalent and are only written when the resource is generated. Neither does grit generate field, which updates the model, the schemas, the type and the admin, and stops there.

Sync now names the files and the fields they never saw, and is honest that the only way to rebuild them is regenerating the resource with its full field list, which discards edits to those screens. It does not report framework-owned columns like version and archived_at, which no screen shows, or resources the generator did not write, whose screens are hand-written and where a regeneration would be actively wrong advice.

This reports the drift rather than fixing it. Marker-based regeneration for the mobile and desktop screens, matching what the admin already has, is the actual fix and is filed separately.

Every client now uses the shared types

v3.199.0 fixed web and admin. Expo declared its own copy of the resource type, which went stale the moment the Go model changed, and desktop declared Record<string, unknown> & { id: string }, which is not drift but an absent type: task.titel typechecked.

Both import from @repo/shared/types now, so a column added to a Go model reaches all four clients on the next grit sync with nothing else to remember. Verified on a five-target project: added a field, ran sync, and web, admin, Expo and desktop all typecheck against it.

The desktop table rejected every real type

Typing the desktop client surfaced this. DataTable was constrained to T extends Record<string, unknown> & { id }, which reads as "any object" and is not: TypeScript gives implicit index signatures to type aliases and not to interfaces, so no declared interface satisfied it. It went unnoticed while the desktop resource types were themselves open records.

The constraint is { id } now, and the one thing the table needs beyond that, reading a column by a caller-supplied key, is a single field(row, key) helper rather than a cast at each of eight read sites.

Wired by alias, not by dependency

Worth recording, because the first attempt was wrong. Adding "@repo/shared": "workspace:*" to the desktop app works and also moves pnpm's hoisting: the app ended up with its own nested copy of vite, two vite type packages disagreed about Plugin, and vite.config.ts stopped typechecking in a project that had been clean.

The desktop app never needed the dependency. Its vite.config.ts already aliased @repo/shared and its tsconfig already mapped the path; only the generated hook was not using them. Expo now gets the same treatment, a Metro extraNodeModules alias plus tsconfig paths, so neither app adds an entry to the dependency graph.

Generated hooks redeclared the type instead of sharing it

Found by doing what the multi-client tutorial describes: add a column to a Go model mid-project, run grit sync, and see it reach the clients.

It reached one of them. The generated hook declared its own copy of the resource type, so grit sync rewrote packages/shared and could not reach the duplicate. The new field existed in the shared type and nowhere else. Nothing errored, because each file stayed internally consistent, and the web app simply did not know the field was there.

The scaffold's own hand-written apps/web/hooks/use-blogs.ts has always imported its type from @repo/shared/types. The generator wrote the same file a different way, which is how the two drifted. It now matches, so a schema change reaches the client on the next grit sync with nothing else to remember.

--tenant-owned

grit generate resource Contact --fields "name:string,email:string" --tenant-owned

Embeds tenant.Owned and imports the package, so a generated resource is scoped to the active organization: queries are filtered by it and OrgID is stamped on insert. The multitenant plugin asked you to do this by hand on every generated model, and again after any --force regeneration.

Off by default even with the plugin installed, for the same reason --owned-by is: a country list, a currency table and a plan catalogue are shared on purpose, and scoping one by accident makes it invisible to every query with no error to explain it.

The flag only helps someone who knows it exists, so when the plugin is installed and it was not passed, the generator now says so once: "multitenant is installed and Country is shared: every organization will see every row. Pass --tenant-owned to scope it." A note, not a refusal.

Found by building a multi-tenant CRM on the docs, following them exactly.

The multitenant plugin never turned its own scoping on

It installed a correct tenant package and a correct middleware, and wired neither. tenant.RegisterScoping(db) was never called, so the GORM callbacks that add the organization filter and stamp OrgID on insert were never installed. middleware.Tenant(db) was never mounted, so nothing put the active organization on the request context for them to read.

Following the documented steps produced a multi-tenant application with no isolation at all. Two organizations, one contact: the second organization listed it, and org_id came back empty on every insert. The plugin's own middleware comment reads "the whole isolation model rests on this check", and nothing called it.

Generated handlers never passed the request context to GORM

Every generated handler queried h.DB directly, so GORM saw context.Background() and nothing a middleware put on the request could reach a callback. That made the plugin unusable with generated resources even once wired: unscoped it returned every tenant's rows, and scoped every query failed closed with a 500.

Handlers now go through h.scoped(c). The swap is applied to the assembled handler source rather than at each of the dozen places that build a query, because the create call, the reload, the many-to-many association writes and the line-items writer are all computed separately and the next one would have been missed. This is worth having without tenancy: a cancelled request now cancels its query instead of holding a connection to build a response nobody will read.

Generating a resource could silently delete the audit log

grit generate resource Activity reported success and overwrote internal/services/activity.go, taking LogActivity, LogCreate, LogUpdate, LogDelete, DiffSummary and seven more with it. The build then failed in access_review.go and event_subscribers.go, two files the developer had never opened, with nothing connecting the error to the command.

The reserved-name list covers built-in models. This was a built-in file, and they are not the same set: the audit log's models are ActivityLog and UserActivity, both reserved, while the helpers that write to them live in a file Activity claims. Names like Chart, Blog, Recovery, Security, Sync and Jobs were in the same position.

The generator now asks the manifest, which already records every file the scaffold wrote, so whatever the scaffold gains next is protected on the day it lands rather than after someone loses a morning to it. It names the files, suggests a free name, and --force still overrides.

Also

• // grit:middleware:protected and // grit:imports in routes.go: there was no way for a plugin to mount request middleware or add an import.
• A failing grit generate resource no longer prints the flag list underneath the error, which buried the sentence saying what to do instead.
• The multitenant docs now say that a generated resource is shared until you embed tenant.Owned in it yourself, and that nothing warns you.

Realtime works with more than one API replica

The Hub was an in-process registry, so a second replica silently halved realtime: a user connected to replica A never received an event published on replica B. The push succeeded, into a registry that did not contain them, and nothing errored or logged. Invisible in development, invisible on one instance, and first met as "messages sometimes do not arrive" during a rolling deploy where two versions overlap.

routes.Setup now wires a backplane whenever the project has Redis, which it already runs for cache and background jobs:

realtimeHub := realtime.NewHub(realtime.WithRedis(cfg.RedisURL, ""))

WithRedis is a no-op on an empty URL, so a project without Redis keeps exactly the behaviour it had rather than failing to start.

Every send takes both paths: this node's own clients first and unconditionally, then one publish for the others however large the audience. Local delivery never waits on Redis and still works while Redis is down, so an outage degrades realtime to a single replica instead of breaking it. A node ignores its own messages coming back, or every user would see their own events twice.

Revocation crosses the backplane too. Closing sockets is how "sign out of all devices" became true in v3.193.0, and a kick that stayed local would have signed out only the devices sharing a replica with the request while the UI reported success. Verified against two live replicas: a revoke issued on B closes a socket held on A.

Delivery between nodes is best effort and says so. A realtime event is a hint that something changed, not the record of it, and every client resyncs on its next REST call. A publish queued behind a backplane that has stopped answering is dropped rather than blocking the request that made it, which matters because SendToUser is reachable straight from a handler and not only through the async event bus.

Backplane is an interface, so Redis is the shipped implementation and not the only possible one. Six tests ship with every project, wiring two hubs through an in-memory backplane, so cross-node delivery, the origin check, broadcast, revocation and the non-blocking publish are all covered without needing Redis to run them.

The device-pairing plugin

grit plugin add device-pairing adds the WhatsApp Web flow: a browser shows a QR code, a device that is already signed in scans it and approves, and the browser is signed in. It is how Telegram Web, Discord, Steam and most TV apps onboard a second screen, and it needed about two hundred lines over pieces Grit already had.

Five endpoints, a /link page in the web app, and a System → Link a device screen in the admin. There is no Device model: approval creates an ordinary session and sets the same cookies a password login does, so a paired browser appears under Account → Security and is signed out from there. A parallel device table would be a second list of the same thing, drifting from the first.

The parts that look like extra work are the ones that matter, because a pairing code is a bearer credential for a whole account:

• Approval is two steps. The approving device fetches the browser and IP behind the code and shows them before it asks. Approving an opaque code is not consent, and it is the difference between a QR somebody photographed across a room being useless and being a silent takeover. Deny sits next to it, because "that wasn't me" has to be one tap.
• Single use is enforced by the database. The claim is a conditional UPDATE, not a read then a write, so two polls arriving together cannot both walk away with a token pair. The generated tests race eight approvals and assert exactly one wins.
• Two minutes, and rate limited. Codes are 32 bytes from crypto/rand. The start endpoint is anonymous, so one address may hold five in flight.

An injection could be silently dropped

Found while building the plugin. injectBefore decided an injection was already applied by asking whether its code appeared anywhere in the target file, which is a different question and gets it wrong two ways.

A plugin legitimately injecting the same snippet at two markers loses the second, which is exactly what an icon needs: an import at the top and a map entry lower down. And a snippet that occurs naturally somewhere else in the file blocks the injection entirely. Both fail silently. The device-pairing sidebar entry rendered getIcon's FileText fallback because of it, with nothing anywhere reporting a problem.

The check now compares the lines directly above the marker being injected at, which answers the actual question and is still a no-op when you install twice.

The admin icon map takes injections

// grit:icons:import and // grit:icons:map in apps/admin/lib/icons.ts. A plugin adding a sidebar entry needs an icon and had no way to add one, and getIcon falls back to a document icon for a key it does not know rather than failing, so the wrong icon was the quiet outcome.

The rest of what building a chat app on a stock scaffold turned up. v3.193.0 closed the leaks; this closes the gaps that made them easy to hit and hard to fix.

--owned-by: per-user resources, generated

A generated resource was shared by default and had no option to be anything else. Its routes sit on the authenticated group, so any signed-in account could list, read, edit and delete every row. authz.MustOwn existed for exactly this and nothing in the generator ever called it.

grit generate resource Invoice --fields "number:string,total:money" --owned-by user

All four access paths are wired, because guarding three of them is the same as guarding none: the list is scoped to the caller, read, update and delete check ownership by id and answer 404 rather than 403 so a wrong guess cannot be told from a right one, and create stamps the owner from the session. The owner field is kept out of the request body entirely, so a caller cannot hand a row to somebody else. An ADMIN is exempt from all four, because the admin panel calls the same endpoints. The flag adds the belongs_to:User field when it is not already there.

Resources generated without the flag are untouched, which is right for a product catalogue and is why this is opt-in rather than a default that would have made every existing shared resource invisible.

A realtime client, in every frontend

The hub has shipped for a long time and nothing consumed it: a scaffolded project contained no WebSocket code at all. The docs offered a six-line snippet, which proves the endpoint answers and is not enough to ship.

It also could not be written in the app Grit generates. It reads the JWT out of storage, and the web app keeps its JWT in the HttpOnly grit_access cookie so that scripts cannot read it. The handshake now accepts that cookie, which is what makes a browser client possible; Expo and service clients still pass ?token=.

lib/realtime.ts and a useRealtime hook now ship in web, admin and Expo: one connection for the whole app rather than one per mounted component, reconnection with exponential backoff and jitter, and useLiveResource("invoices", ["invoices"]) to keep a React Query list in step with created, updated and deleted without polling.

Custom routes can reach the hub

Mount carried the DB, the config, the service bundle and the router groups, and neither the realtime hub nor the auth service. The hub is the one thing a route cannot work around: realtime.NewHub() returns a different registry holding no connections, so a handler that builds its own pushes into nothing and fails silently. Reaching the real one meant editing routes.go, which is the file the per-resource split exists to keep people out of. Both are on Mount now.

grit plugin list was showing a third of the catalogue

Five CLI plugins were listed. Ten more packages exist at grit-plugins and only webhooks overlaps by name, so the command read as a complete catalogue while omitting websockets, search, notifications, Stripe, OAuth, i18n, video, export and conference. They install with go get rather than grit plugin add, so they are listed under their own heading with the command that installs them.

An un-preloaded relation is now absent, not blank

belongs_to generated a value-typed association with no omitempty, so every response carried a complete zero-value object for any relation that had not been preloaded. message.sender.first_name was "" rather than undefined, and sender.active was false, which is a specific and wrong claim rather than "unknown". On a chat app's highest-volume endpoint most of the payload was that padding, and it rode the websocket push too. Now a pointer with omitempty, and the generated TypeScript says sender?: User, which is the truth. A client reading the blank object will need updating.

UPLOAD_ALLOWED_MIME

Adding the audio types last release meant editing framework code inside a scaffolded project, which the manifest guard may hold back on upgrade. Set UPLOAD_ALLOWED_MIME=audio/flac,image/avif to extend the allowlist without touching it.

Found by building a chat app on a stock scaffold and watching what the wire actually carried. Three of these are security fixes and all three were reproduced against a clean project before being changed.

Resource events were broadcast to every connected user

The realtime subscriber listened on "*" and called hub.Broadcast, so every create, update and delete of every resource went to every open socket in the process. The payload carries the row's label, which is its human-readable title.

Two accounts and one websocket were enough to show it. A user with no relationship to the record received {"type":"conversations.created","label":"Chemo results - family only"}, along with the actor's id and the timestamp. In a multi-tenant app that is every tenant's record titles, live, to everyone signed in, whatever the REST layer permits. There is no per-row authorization in the event bus for it to have leaned on.

Events now go to services.RealtimeAudience(e), which defaults to the actor alone: your own devices stay in sync and nobody learns about a row they may not be allowed to read. Widen it deliberately when the app knows who is entitled to look, for example a chat sending to a conversation's participants. Returning nil drops the event.

A WebSocket outlived the token that authorised it

The JWT is checked once, at the handshake, and never again. Nothing bounded the connection after that, so a socket opened with a 15 minute token kept delivering events indefinitely.

realtime.Client now carries the token's expiry and writePump closes the connection when it passes, which is the same bound REST already operates under.

"Sign out of all devices" did not sign out of all devices

Revoking a session marked a database row and stopped there. Verified before the fix: after a successful revoke-all from a second session, the revoked device's access token still returned 200 on REST, and its open websocket kept receiving message bodies. Combined with the broadcast above, a signed-out device kept a live feed of activity across the whole system.

Hub.DisconnectUser closes every connection a user holds, and both RevokeSession and RevokeAllUserSessions now call it through a services.OnSessionsRevoked hook that routes.Setup wires to the hub. The socket closes within seconds rather than never.

No audio file could be uploaded

AllowedMimeTypes had images, video, documents and archives, and no audio/* entry of any kind. Every voice note came back INVALID_FILE_TYPE.

The admin has had an audio accept group listing five audio types for a long time, and the storage dashboard already buckets uploads by mime_type LIKE 'audio/%', so a field declared accepts:"audio" offered an audio picker and then failed every file it produced. That is the same trap the archive types were added to close. The audio types are now in the fallback list.

The defenders' handbook claimed an ownership check that is not there

It said grit generate resource wires authz.MustOwn into the generated handler, and that "IDOR is closed by the generator, not by the developer remembering". Nothing outside the authz package calls MustOwn. Generated routes sit on the authenticated group, so any signed-in user can read and write every row of every generated resource.

The helper is good and the page now says what it actually is: something you call, with a warning about what the default is until you do. The generator cannot guess which resources are per-user and which are shared reference data, so this is a page correction rather than a code change.

A generated resource could not find its own definition

Reported against a Vite project: Cannot find module '@/resources/posts/posts' on both routes of every resource generated by grit generate resource.

The definition writer and the route writers disagreed about where the definition lives. The writer put it at src/resources/posts.ts, flat; both routes imported @/resources/posts/posts, the folder form. The folder form is the one that is right: it is what the Next generator writes, what the built-in blogs and users resources use, and what the .custom.tsx overlay needs so it can sit beside the definition it overlays.

The reporter suggested changing the import instead, which would work and would leave the TanStack admin as the only place in Grit using a different layout from everything around it. The routes now ask where the definition actually is rather than assuming, so a project still holding a flat file from before this keeps working instead of trading one broken import for another.

pnpm typecheck was red on a fresh Vite project

Found while confirming the fix. A freshly scaffolded TanStack admin reported 24 errors from its own typecheck script, none of which stopped a build, so nothing had ever surfaced them.

Ten were import.meta.env untyped: the admin was the only Vite app in the scaffold without a vite-env.d.ts. Five were process undeclared, needing @types/node, which the Next admin already had. The remaining nineteen were imports and locals nothing used, dead in both admins and quiet in the Next one only because its tsconfig does not set noUnusedLocals.

All fixed: pnpm typecheck now exits clean on a fresh Vite project with a generated resource, and both admins still build.

One thing worth knowing rather than reporting as a bug: run pnpm typecheck before ever starting the app and TanStack Router has not generated routeTree.gen.ts yet, so every createFileRoute call is a type error. One dev or build run generates it and they go.

--single and --double grew an admin directory they do not have

Found by sweeping the architectures that had gone untested after the TanStack bugs in v3.190.0. The account security writers put five files into apps/admin/ in every architecture, including the two that have no admin app: no package.json, no layout, nothing that builds. An orphan tree reads as something half-finished, which is worse than the feature simply not being there.

Both writers now skip when the project has no admin, which is what every other admin writer already did. The guard is inside the functions rather than at their six call sites, so a seventh cannot miss it. The API endpoints are unaffected and still exist in every architecture.

The sweep itself

Every architecture and frontend combination was scaffolded and checked: imports resolved against each app's own tsconfig alias, Go built, and each frontend built. --single, --double, --triple, --mobile, --desktop and --full, times Next and Vite where both apply. Plugins were installed on the architectures that have an admin and confirmed to install only their API halves on the ones that do not.

Two things that look like bugs and are not, recorded so the next sweep does not chase them: the desktop app's Go build fails until its frontend has been built, because Wails embeds frontend/dist and that is the documented build order; and the docs app imports @/.source/server, which fumadocs-mdx generates before every dev and build run.

The TanStack admin was missing files, a whole feature, and every plugin

Reported by somebody whose grit new --vite project would not start: Failed to resolve import "@/components/tables/table-tabs". Vite reports these one at a time, so that was the first of four.

All of it is one mistake repeated: writers that hardcode the Next.js admin layout. The Next admin keeps components, hooks and lib at the app root; the TanStack admin puts them under src/ and routes through src/routes/. Anything written to the Next shape in a TanStack project lands where the @/ alias does not point.

Four components were never registered for TanStack: table-tabs, bulk-action-bar, bulk-edit-modal and use-resource-detail-controller. That one is a build error, so it at least announced itself.

The account security page did not exist at all. Passkeys, recovery contacts, the WebAuthn helpers and the page itself were written to the Next paths, so a TanStack project got five files nothing imports and no security screen. No error, because unimported files are not a build failure.

Four of the five plugins could not be installed. command-palette, impersonate and saved-views wrote into the Next layout, their injections missed targets that live under src/, and the install reported success anyway. Worse, the stray file then counted as "already exists", so a second attempt refused outright. Only multitenant, which touches no admin files, worked.

Every writer now asks the project which layout it has, and plugin components go through the same Next-to-TanStack converter the scaffold uses, so a rule added there reaches plugins without being added twice. Verified by installing all five plugins into both a Next and a Vite project and building each: Go, admin and web.

Four tests now assert it, because none of these were build failures and the next one will not be either: no plugin may write outside the project's admin layout, in either direction; a page shipped under src/pages/ must have a route pointing at it; and no file written for TanStack may still carry "use client" or next/navigation. That last one caught a fifth bug while it was being written.

Upgrade could half-migrate an app to Tailwind v4

The v3 to v4 move spans three files that only work as a set: package.json names the engine, postcss.config.js names the plugin, and globals.css uses either the v3 @tailwind directives or the v4 @import. Upgrade writes all three, and the manifest guard holds back whichever ones you have edited, one at a time. Nobody edits all three or none of them.

So the reachable state was a v4 plugin parsing a v3 stylesheet, and it does not degrade: the first utility built from tailwind.config.ts becomes Cannot apply unknown utility and the app stops building. The upgrade did list the held-back files, but nothing connected "your package.json was left alone" to "your web app no longer compiles". Found on a real project upgrading from v3.176.0.

The PostCSS config now follows the stylesheet: an app still on the v3 directives keeps the v3 plugin, and the file it gets says how to migrate when you want to. A consistent v3 app keeps working, and the migration becomes something you do deliberately rather than something an upgrade does to two files out of three. New projects are unaffected and still scaffold fully on v4.

If you hit this already, the smallest fix is the one in that comment: move package.json to tailwindcss ^4 plus @tailwindcss/postcss, and replace the three @tailwind lines with @import "tailwindcss"; and @config "../tailwind.config.ts";. The @config line keeps your existing theme file working, so nothing has to move into an @theme block on day one.

grit.json reported the version you scaffolded with

The version field was written once by grit new and never touched again, so a project upgraded four times still named the version it was created with. That is the field people open to answer "what version am I on", and it was the wrong answer every time after the first upgrade.

grit upgrade stamps it now. Only that key changes: the file is decoded and re-encoded rather than rewritten from the template, so architecture, frontend, apps and anything you added yourself survive. The authoritative record was already correct in .grit/manifest.json; this is the human-facing copy of the same fact, and the two disagreeing was worse than either.

A tutorial for writing your own endpoints

Custom API endpoints, end to end: build a shop with three resources, see every endpoint Grit already generated, then write four of your own and call them from Next.js and TanStack Start. Handlers and services explained for someone who has used neither, a GORM cheat sheet, seeding, adding a column to a resource that already exists, and what a relationship actually changes.

It was written by building the project first and reading the files, which is how the four fixes below were found. Every command and response on the page came out of a running API.

PATCH silently ignored many-to-many

PATCH /campaigns/:id {"title": "Renamed", "product_ids": [...]} renamed the campaign, dropped the product ids on the floor, and answered 200. Nothing said no. Sending only product_ids was worse: no scalar survived the whitelist, so it came back 422 "No writable fields in request body" about a field PUT accepts.

PATCH now applies the association the way POST and PUT do. An empty list still means "empty it", because presence in the body is the instruction, not the length of the list.

Seeders wrote to columns the framework owns

grit generate seeder reads the model back and takes every field it recognises, which included archived_at, and for a --tree resource also path, depth and position. The tree columns are computed in BeforeCreate, so a literal there describes a hierarchy that does not exist. archived_at was worse: every seeded row would have been archived, and the admin's default list hides those, so the seeder looks like it did nothing.

It never got that far, because archived_at is a *time.Time and the seeder emitted time.Now(), so the generated file did not compile. That is the only reason this was noticed.

A generated service could not run its own search

The service's List built its WHERE from every field whose Go type is string, and a belongs_to qualifies, because the foreign key is a UUID string. So a --tree resource got LOWER(parent) LIKE ?: parent is the relation, the column is parent_id, and the query fails at the database. Latent rather than fatal, because nothing calls the generated service until you write the first line of business logic in it.

New fields landed above the primary key

grit generate field Category is_featured:toggle injected directly after the struct opening, so the new column appeared above ID and ahead of every field the resource was generated with. It compiled, and it read as though something had gone wrong. New fields now go where a person would have written them: after the declared fields, before the framework's block.

Cursor pagination, which had never worked

The keyset code was all there and unreachable: cursor mode was a compile-time Config field no generated handler set, and no query parameter turned it on. Every list endpoint was offset-only, which walks 100,000 rows to throw them away and shifts the window under anyone paging while rows arrive.

?mode=cursor asks for it, and sending a ?cursor=implies it, so a client following meta.next_cursor never says so twice. Offset stays the default because the admin table needs page numbers and a total.

Being unreachable is why it was broken. The cursor encodes the last row's sort value as text and handed it to the WHERE clause as text, so a timestamp column compared against '2026-09-02T09:18:39.7195481+03:00' matched every row in SQLite and page two came back identical to page one, forever. Values are bound at their own type now. Sorting on a money field was broken separately: the column is price_amount and there is no PriceAmount field to reflect on, so the cursor encoded nothing and the walk restarted from the top. Seven tests ship with every project.

A transactional outbox

"Save the row and tell the world" has no correct ordering. Publish then commit, and a failed commit leaves a webhook announcing an order that does not exist. Commit then publish, and a process killed in between leaves the order with nobody told, and nothing logged, because from the process's point of view nothing failed.

outbox.Enqueue(tx, topic, payload) writes the message in the same transaction as the data, and a relay delivers what committed. It refuses the root *gorm.DB outright: enqueueing outside a transaction is the bug it exists to prevent, and it is one that fails in production and never in a test. Claims, backoff, a dead-relay timeout so nothing is stranded, and Prune that will not delete a failed message, because that is a bug nobody has looked at yet.

Webhook deduplication was decoration

The model's comment described a unique index on (provider, external_id). The handler treated a duplicate-key error as "already processed" and returned 200. The index itself lived in an Indexes() method that nothing called, so the column had a plain index, the second INSERT succeeded, and every retried delivery ran the handler again. A Stripe retry is not an edge case; it is how Stripe works.

The constraint is now declared on the fields, so the migration creates it, and external_id is nullable so events from providers that send no id stay distinct rather than colliding on the empty string. Migrations convert existing empty strings to NULL first, because no database will build a unique index over repeated empty strings. Four tests, one of which asserts the index exists in the database rather than in a comment.

Taking stock without overselling

stock.Take(tx, model, id, "stock", qty) is one conditional UPDATE: SET stock = stock - ? WHERE id = ? AND stock >= ?. The read-modify-write it replaces lets two orders for the last item both read 1, both find it sufficient, and both write 0: one unit, two sales, and a row that looks fine afterwards. TakeMany sorts by id before locking, which is not tidiness: two orders touching the same two products in opposite order deadlock under exactly the load that makes it expensive. Eleven tests, including twenty goroutines racing for ten units.

Framework-owned files travel on upgrade

Each of the fixes above needed the same thing: a change to framework code reaching projects that already exist. The webhook model, its receiver and the dispatch package read the same columns and only work as a set, and they were split across the scaffold-only and upgraded sets, so half a fix landed and the project stopped compiling. They travel together now, alongside the packages generated code imports.

Base UI, for new primitives only

Recorded as a decision rather than shipped as a dependency. The admin has no primitive library at all: every component is hand-written against the design tokens. That is right for anything that is a styled element, and wrong the moment a component needs a focus trap, roving focus or listbox semantics, which is where hand-rolled components fail silently for keyboard users.

So: new primitives that need real interaction behaviour use Base UI, not Radix. Existing ones are not rewritten, and the dependency arrives with the first component that needs it rather than in every scaffold ahead of time.

Every resource owns its routes file

routes.go was the worst file in a generated project. Each resource edited it in four places, hundreds of lines apart: the handler construction, the protected block, the admin block and sometimes the public one. It passed a thousand lines with a handful of resources, so adding a route by hand meant working out which of four blocks it belonged in, and the generator had four chances to inject into the wrong one.

Each resource now gets internal/routes/<resource>_routes.go holding its handler and every path that reaches it. The file registers itself from an init(), so creating one mounts a resource and deleting one unmounts it. Three resources generated back to back grew routes.go by two lines total, and both were model names in a list rather than routes.

Nothing moves in an existing project. Routes already inline stay inline and keep working, because relocating them would silently drop any edit made to those lines. grit upgrade adds the registry, and resources generated after that get their own files alongside.

The auth handler, split by concern

handlers/auth.go was the second largest file at a thousand lines, covering sessions, password reset, email verification, OAuth and account lockout at once, and it is a file people customise. Changing the reset email meant scrolling past OAuth. It is 587 lines now, holding the session core, with auth_password_reset.go, auth_email_verification.go, auth_oauth.go and auth_lockout.go beside it. New projects only; an upgrade leaves an existing auth.go alone.

Everything else that grows with your resources adds a line or two to a file under thirty, so nothing else was worth splitting. The remaining large files are fixed-size framework code that does not grow as you build.

A new project failed its own test suite six times in ten

go test ./... straight after grit new failed on TestAuthHandler_Login_Success more often than it passed, with a 401 that reads as broken login. Every connection to SQLite's :memory: gets its own empty database, and the pool opened a second one as soon as two queries overlapped, which they did because registering writes its activity row on a goroutine. The login that followed landed on an empty database and found no user. The test helper pins the pool to one connection. Eight runs in a row now pass where five used to give three failures.

Existing projects can apply the same three lines to newTestDB in internal/handlers/auth_test.go: sqlDB, _ := db.DB() then sqlDB.SetMaxOpenConns(1).

Removing a resource left the project uncompilable

The API reference moved out of routes.go into apidocs.go in v3.154.0 and took its markers with it. The generator learned the new home; grit remove resource never did, so it left every docs.Route chain and the model entry behind and the project stopped compiling on undefined: models.X. It follows the same fallback the generator uses.

A money field type

price:money stores an integer count of a currency's smallest unit alongside its ISO 4217 code, in two columns: price_amount BIGINT and price_currency VARCHAR(3). The amount stays exact, the currency travels with it, and SUM(price_amount) GROUP BY price_currency is a query the database can answer.

It generates the Go type with the arithmetic that goes with it (currency-checked add and subtract, an Allocate that splits 10.00 three ways without evaporating a cent), the shared TypeScript type and formatting helpers, an admin form field with a currency picker, and a right-aligned table cell that formats in the row's own currency. Zero-decimal currencies work: UGX 50,000 is 50000, not 5000000, and it renders as 50,000 rather than 500.

Worth recording how the first version was wrong. The type implemented driver.Valuer and sql.Scanner, which seemed tidy. GORM treats anything with those as a scalar, so it ignored the embedded tag and made a single price INTEGER column: the amount survived and the currency was silently discarded. Nothing failed. It only showed up in PRAGMA table_info, and the fix was to delete the two methods, which is now a test.

The storefront blog used to say floats were fine at that scale. That advice is gone. See Money, which includes the migration for an existing float price column.

Upgrade stopped shipping half a project

grit upgrade refreshed seed.go but not the API key seeder it calls, nor the model, service, middleware and handler that seeder depends on. Every upgraded project failed to compile with undefined: SeedAPIKeys, and fixing that one file only moved the error to the next one along.

The underlying split was wrong. Upgrade deliberately does not regenerate API code, which is right for anything a person might have edited and wrong for a package that exists purely to be imported by code the generator writes tomorrow. Those packages, paginate, events, export, ids and pdf, now travel on upgrade, so a freshly generated handler is never compiled against a paginate.Config six versions older than itself. Files you have actually edited are still reported as conflicts rather than overwritten.

The money field's own frontend half gets the same treatment: the shared type, the admin cell and the form field are injected into existing projects rather than only appearing in new ones, which is the mistake media, recovery contacts and passkeys each shipped with.

Tailwind v4 everywhere on the web

The Next.js admin and web app were still on Tailwind v3 while the rest of the ecosystem, shadcn included, had moved to v4. Both are on v4 now, along with the TanStack and single-binary frontends.

The v4 port of Grit's design tokens already existed, but only in the TanStack admin, applied by string-replacing the v3 directives out of the shared stylesheet. It lives in that shared stylesheet now, so every frontend is v4 from one source and there is nothing left to patch.

The load-bearing detail is regular @theme, not @theme inline. The utilities compile to var(--color-*), whose values are var(--bg-*) indirections that re-resolve per element, which is what makes [data-theme] switching repaint at runtime. With @theme inline the values bake at build time and the theme switcher silently stops working.

tailwind.config.ts is no longer written: v4 does not read one unless a stylesheet asks with @config, and shipping an unread config is a file people edit expecting an effect. autoprefixer is gone too, since v4 prefixes for itself and re-processing its output can mangle its @property rules.

Expo and the Wails desktop client stay on v3 deliberately. NativeWind targets Tailwind 3.4, so moving it would break the mobile app rather than modernise it. Both remain internally consistent.

The admin would not load for some people

#77: Turbopack's Google-fonts loader fails to resolve its own @vercel/turbopack-next/internal/font/google/font module, and the app never renders. The scaffolded dev scripts pass --webpack until Turbopack ships the fix.

Worth being straight about: it does not reproduce here. A project on the exact reported version, 16.3.3, ran all day with the same font imports. So this is a machine-dependent upstream bug, the flag is a workaround rather than a correction, and it carries a comment saying so and when to remove it.

The toggle was a button with no name and no state

Finishing the form accessibility work from v3.180.0. The toggle rendered a bare <button>: no role, no aria-checked, no accessible name. A screen reader announced "button" and nothing else, so there was no way to know what it controlled or whether it was on.

It is a role="switch" now, with aria-checked that flips and aria-labelledby pointing at its label. The checkbox group gained role="group" so its boxes are announced as one labelled set rather than a run of unrelated checkboxes. The radio field already had radiogroup and needed nothing.

Two docs pages that did not exist

Passkeys covers what a passkey actually is, the two ceremonies, why sign-in is usernameless, why the challenge lives in a table rather than in memory, why a backwards sign counter is logged instead of blocked, and how to test it against a virtual authenticator. Including the three things it deliberately does not do.

Account Security covers the page and the recovery flow behind it: why every write takes the account password, why the address comes back masked even to the person reading it, the two addresses that are refused, and why phone recovery is a seam rather than a bundled provider.

grit sync warned on every run

The scaffold's own blog resource shipped without the grit:cols:auto and grit:fields:auto markers, so every sync in every new project printed a warning about a file the reader had never touched. The markers are in the scaffold now. An existing project still gets the warning, correctly: that file is yours to edit, so upgrade will not overwrite it, and the message says exactly what to do.

Passkeys

WebAuthn sign-in with a fingerprint, face or device PIN. The private key never leaves the authenticator and the server stores only the public half, so there is nothing here for a breach to leak and nothing for a phishing page to collect.

Pure Go, via go-webauthn, so the API still cross-compiles to a single static binary. That was the constraint the whole design was checked against before a line was written.

POST /api/v1/auth/passkeys/register/begin    add one to the account you are in
POST /api/v1/auth/passkeys/register/finish
POST /api/v1/auth/passkeys/login/begin       public: usernameless sign-in
POST /api/v1/auth/passkeys/login/finish
GET  /api/v1/auth/passkeys                   list, rename, remove

Sign-in is usernameless, because that is the point of a passkey: the authenticator knows which account it holds, so asking for an email first buys nothing. It issues the same tokens a password sign-in does and records the same session, so the device appears in Active Sessions and can be revoked like any other.

Ceremonies are stored in a table rather than in memory, for the same reason refresh sessions are: the moment there are two API instances, an in-memory challenge is a coin flip on whether sign-in works. Single use, five-minute life, and deleted on read. The sign counter is kept and a counter that goes backwards is logged, because that is the signature of a cloned credential.

A card on /account/security manages them, and hides itself when the browser has no platform authenticator rather than offering a button that opens a dialog and fails.

Verified against a real authenticator, not a mock: Chrome's virtual authenticator over CDP, registering a passkey through the actual UI, confirming the credential exists on the device as a resident key, that the server verified the attestation and stored it, and that removal takes it away.

Form labels were not attached to their inputs

Twelve of the thirteen admin form fields rendered a bare <label> and an input with no id. The two were never connected, so clicking a label did not focus its field and a screen reader announced an unlabelled box. On every form, in every generated project.

Fixed for the single-control fields: text, textarea, number, select and date now pair htmlFor with a useId. The group fields, radio, checkbox-group and toggle, want role="group" with aria-labelledby rather than htmlFor, and are next.

The many-to-many picker is a real combobox

Tags on an article, categories on a product. The trigger was a <div onClick>: Tab could not reach it, a keyboard could not open it, there was no way to move through the options without a mouse, and a screen reader saw a pile of unlabelled buttons.

It is now role="combobox" over a role="listbox" with aria-multiselectable, options that report aria-selected, and aria-activedescendant so movement is announced without focus leaving the search box. Arrows move, Enter toggles, Escape closes and returns focus to the trigger, Home and End jump, and Backspace on an empty box removes the last chip. Every remove button has a name: "Remove React", not a bare X. Enter on a search with no matches opens the inline create dialog, because that is what somebody typing a tag that does not exist is trying to do.

Worth stating because it was asked: the relationship is optional. An article saves with no tags and gets them later, which is how a catalogue actually gets built. Verified in a browser.

one_to_one

A belongs_to whose foreign key is unique, declared on the side that holds the key: a passport declares its user, not the other way round, because that is the only side the constraint can live on.

grit g resource Passport --fields "user:one_to_one:User,number:string"

uniqueIndex is the entire difference. The column, the eager loading, the searchable picker, the CSV import are all identical to belongs_to, deliberately: it is the same relationship with a constraint, so it reuses the machinery rather than duplicating it. Verified against a real database, where the second row for one parent is refused.

The docs said a command did not exist

Code Generation claimed there is no add field command and told you to edit the Go model by hand. grit generate field has existed for some time and does the whole job: the column, both Zod schemas, the TypeScript type, and the admin table and form. The page now leads with it, and keeps the manual path for the four types the command declines.

grit g resource Profile produced a project that did not compile

Found while testing the above. It collides with the built-in UpdateProfileRequest in the users handler. Profile is reserved now, so the generator refuses it and suggests a name.

An account security page, and recovery contacts

Two-factor and active sessions already existed, on a page called "profile", next to a bio and an avatar. That is a page somebody opens to change their job title. Security decisions now have their own screen at /account/security, reachable from the user menu.

Note this is not /system/security, which is the operator's threat dashboard: blocked addresses, recent attacks, the state of the perimeter. That page is about other people. This one is about you, and merging them would put a password box next to a list of intrusion attempts.

Recovery email, and a seam for SMS

A verified second address that can get somebody back in when the primary is gone. Six-digit code, fifteen-minute expiry, hash-only storage, single use, and guesses capped at five, because a million possibilities with unlimited attempts is a formality rather than a secret.

Every write takes the account password. That is the whole security model: a recovery address is a second way in, so somebody holding a live session from a borrowed laptop could otherwise attach their own address and keep the account. Adding and removing both require it, and the overview returns the address masked, because whoever is reading that screen might be the problem.

Phone recovery ships as an interface rather than a provider. internal/sms defines the seam; nothing is registered by default, because the right provider depends on where your users are and baking one in would make everybody carry a dependency most cannot use. The page asks the server whether one exists and leaves the card out entirely when it does not.

Two things this release does not claim

Passkeys are still not implemented. There is no WebAuthn anywhere in Grit, and the page does not pretend otherwise. That is its own feature: credential storage, registration and authentication ceremonies, challenge state, and a client flow. The page is now the place to hold it.

Recovery contacts live in their own table rather than as columns on User. That was a correction: as user columns, an upgraded project got the handler that reads them and a model without them, which does not compile. grit upgrade does not rewrite the User model, and a half-delivered feature is worse than an undelivered one.

Two bugs reported by Mukisa Mark Cole (#75, #73), both reproduced exactly as described.

Every date field failed to save

A date field generated a Go *time.Time, whoseUnmarshalJSON accepts RFC3339 and nothing else. The admin's date picker sends "2001-08-06", deliberately: it builds the string from year, month and day numbers rather than from a Date object, because that is how a birthday ends up a day earlier for anyone west of Greenwich.

So the two halves of the scaffold disagreed about the wire format and every date field was unsaveable out of the box:

parsing time "2001-08-06" as "2006-01-02T15:04:05Z07:00": cannot parse "" as "T"

datetime was broken the same way and the report said so: datetime-local sends "2026-03-15T14:30", which has neither seconds nor a zone and is not RFC3339 either.

Fixed on the server, which is the side that was wrong. A new internal/jsontime package provides Date and DateTime, which accept what browsers actually send. A Date parses in UTC and truncates to the day, so it cannot drift with the server's zone, and marshals back as "2001-08-06", so a value survives a round trip unchanged. Nine tests ship into your project.

grit sync broke the login page

Sync rewrote each schema file with only the create and update pair, while the scaffold's schemas/index.ts re-exports <Name>Schema for every resource it ships. The barrel was left importing a member that no longer existed.

That is a TS2305 inside @repo/shared, so the admin and the web app both failed to type-check, including the login page. Nothing in the project imported the missing schema at all: the stale re-export was the entire fault, which is what made it so confusing to hit.

Sync now emits the entity schema alongside the pair. It is the useful one anyway: create and update describe what goes in, and this describes what comes back, id and timestamps included, which is what you validate a response against.

Uploads were blocked in production, and nothing said so

Found by running a real project end to end rather than by reading the templates. The frontend Content-Security-Policy builds its connect-src from NEXT_PUBLIC_STORAGE_URL, and the scaffolder never wrote that variable. It fell back to the default MinIO port, which is right for exactly one configuration: a local project that has not moved anything.

Move MinIO, or deploy to R2 or S3, and every presigned upload is refused by the browser. There is no server log, no failed request in the network tab worth noticing, and no error in the UI. The only trace is a CSP violation in the console.

The seeder now writes both origins into each frontend's .env.local, derived from the project's own storage config rather than assumed, with a comment saying what they are for.

Stored files are named by what they actually are

A JPEG optimised to WebP was stored as photo.jpg. The Content-Type was correct so browsers rendered it, but a key whose extension contradicts its bytes confuses everything that reads keys instead: CDN rules, lifecycle policies, and whoever is looking through the bucket later.

Verified end to end

A fresh project, real MinIO, real browser, no manual configuration: a 3.70 MB photograph reached storage as 50.6 KB across two objects, 75x smaller, both genuinely WebP by their magic bytes, and zero multipart uploads reached the API.

@repo/upload is already wired into the admin and web apps, so a plain pnpm install links it. Nothing to install, nothing to configure.

A dropzone in the package itself

@gritframework/upload was logic only, which meant every project rewrote the same drag handling, progress rows and object-URL cleanup, and most of them got the last one wrong. It now ships a component:

import { Dropzone } from "@gritframework/upload/ui";
import "@gritframework/upload/styles.css"; // optional

<Dropzone uploader={uploader} profile="product-image" onChange={setFiles} />

It ships unstyled, with stable class names under a grit-dz namespace and a classNames prop that replaces any of them, so it sits inside an existing design system without a fight. The stylesheet is optional and themed through custom properties, because a package that forces its own CSS on you is a package you fight.

Per-file progress rather than one bar for the batch, the saving shown as it happens, and a failed file that stays in the list with the reason instead of vanishing. The drop target is a label around a real file input, so keyboard activation and the native mobile picker come for free.

Using Tailwind and want a version to own rather than configure? The Grit UI block is the same idea with the styling baked in: npx shadcn@latest add https://ui.gritframework.dev/r/application-ui-file-upload-optimizing-dropzone.json

Eight component tests cover the parts that are easy to break: the real input behind a label, the saving appearing, a failed file staying put, the profile reaching the uploader, maxFiles disabling the input, removal releasing its object URL, and the progressbar exposing aria-valuenow. They stay in the library rather than being vendored into projects, because they need jsdom and a second copy of react-dom that pnpm cannot reconcile, and no project should inherit that to test a component it did not write.

Every upload in the admin now optimises itself

The dropzone, the avatar picker and every generated file field go through @repo/upload. Measured in the browser against a running API: a 2.53 MB photo dropped on a form asks to upload 64 KB plus a 3.5 KB thumbnail, both WebP, and the presign asks for exactly the byte count it then sends.

The public signature of uploadFile() is unchanged, so nothing that called it needed touching. What changed is that progress now covers the thumbnail too, and the returned ref carries the renditions.

The package is on npm

@gritframework/upload works in any React, Next.js or Expo app, with no dependency on Grit. It needs three endpoints from your API, and the README documents the shapes.

npm install @gritframework/upload

Inside a Grit monorepo nothing changes: it stays a workspace dependency resolved from disk, so there is no install and no registry in the loop.

One source, not two

The library moved out of Go string templates into packages/upload in the Grit repository, which the scaffolder embeds with go:embed. That directory is simultaneously the published npm package and the source written into every generated project, because the alternative is a package and a template that agree right up until somebody edits one of them.

Image optimisation moved to the client, and got better

Uploads go browser to storage through a presigned URL and never touch the API, so optimising on the server was always working on the wrong side of the wire. @repo/upload does it before the bytes leave the device. Measured in real Chromium on a 5 MB photograph:

pure-Go server backend      149.9 KB
libvips server backend       33.9 KB   (needs cgo)
browser, client-side         35.0 KB   <- 147x smaller, no server involved

The browser matches libvips because it has a lossy WebP encoder built in. That is precisely the thing pure Go could not do without cgo, and it was on the client the whole time. No server CPU, no server bandwidth, and on a phone the 5 MB never leaves the handset.

One package, three platforms. The optimiser is injected rather than imported, so nothing has to resolve a platform at build time:

import { createUploader, createAxiosTransport } from "@repo/upload";
import { optimizeImage } from "@repo/upload/web";   // or @repo/upload/expo

export const uploader = createUploader({
  transport: createAxiosTransport(apiClient),
  optimize: optimizeImage,
});

Expo uses expo-image-manipulator, since React Native has no canvas. React gets useUpload with per-file progress and describeSaving() for the "6.1 MB to 41 KB" label. Profiles are served from GET /api/v1/media/profiles so the client uses the server's numbers instead of a second copy that drifts.

The server now constrains and verifies instead

A presigned URL is a capability handed to a browser, so once the client does the optimising the server cannot guarantee what landed. Two holes closed.

The exact byte count is signed into the presigned URL. The client optimises first and therefore knows its size before asking, so S3 rejects a PUT of any other length. Previously the URL was an unbounded write capability: ask for two megabytes, send five gigabytes, and nothing on this side ever saw it.

Completion re-reads the object from storage rather than believing the reported size, which was a claim about bytes that never came through the API. Anything over the limit is deleted rather than recorded.

The server pipeline from v3.171.0 stays as the fallback for anything that does reach it, and for non-browser clients.

A decompression bomb could exhaust the API's memory

Shipped in v3.171.0 and closed here. A solid-colour PNG compresses to almost nothing whatever its dimensions, so an upload that passes every file-size check on the way in can still be enormous once decoded. Measured: a 165 KB file at 12000x12000 allocated 224 MB, and ten concurrent uploads of it would have been 2.2 GB. Dimensions are now read from the header before any pixels are allocated, and anything over MaxPixels (50 megapixels by default) is refused. A 48 MP professional camera frame still passes.

libvips, as an opt-in backend

The pipeline now has a swappable backend. The default is unchanged and needs no system libraries. Build with -tags vips and it uses libvips, which can write lossy WebP and AVIF. Measured on the same 6.08 MB photograph in the same container:

pure Go (default)      libvips (-tags vips)
default profile     149.9 KB JPEG 1001ms   33.9 KB lossy WebP 1853ms
JPEG, forced        141.0 KB       950ms  123.7 KB            1366ms
AVIF                downgrades to JPEG     79.9 KB            7544ms

About 4x smaller, and not faster. libvips is slower here on both the default path and a like-for-like JPEG comparison. The widely quoted 4-8x speedup is libvips against ImageMagick rather than against Go's native image package, and it did not reproduce. The reason to want it is bandwidth, not latency. AVIF costs 7.5 seconds for one image and on this photograph came out larger than lossy WebP, so it is opt-in per profile and not viable on a synchronous upload.

Opt in where the environment is controlled, because cgo cannot cross-compile and grit deploy builds for linux/amd64 from your machine with CGO_ENABLED=0:

docker build --build-arg IMAGE_BACKEND=vips -f Dockerfile.api .

The same profiles drive both. What changes is what Auto resolves to. A profile asking for AVIF on the pure-Go backend is downgraded rather than refused, so one binary still serves a project whose profiles assume libvips, and format on the ref records what was really produced. The active backend is named in the upload log line.

Image optimisation, on by default

Upload a 6 MB photograph and 147 KB gets stored: resized to fit 1600x1600, encoded at quality 0.82, EXIF oriented and then stripped, with a 400x400 thumbnail alongside and the original kept privately for reprocessing. No configuration required. See Image Optimisation.

The output format is decided per image rather than configured, because the answer is in the pixels: anything with real transparency becomes lossless WebP, everything else becomes JPEG. That makes the usual mistake, a transparent logo saved as JPEG and quietly gaining a black box, unrepresentable.

Define a profile when one field wants something else, in internal/media/profiles.go, which is written once and never regenerated:

media.Define("product-image", media.Profile{
    Max:     media.Fit(1000, 1000),
    Quality: 0.8,
    Renditions: map[string]media.Size{"thumb": media.Fill(300, 300)},
})

// POST /api/v1/uploads?profile=product-image

No lossy WebP and no AVIF, deliberately. Neither has a pure-Go encoder, and adding one means cgo, which costs the static cross-compiled binary. On a photograph the pure-Go lossless WebP encoder produced 778 KB where JPEG produced 35 KB, so it earns its place as a PNG replacement and nothing more.

Every thumbnail was being orphaned

The upload handler stored the original, queued a thumbnail job, and returned a file reference whose thumbnail field was still empty because the worker had not run yet. That reference is what got written into the record, and the worker wrote its result onto the separate uploads row, which nothing read back. Every thumbnail generated for a resource file field was produced, paid for, and referenced by nothing. Transforming inline fixes it: the record is only ever written with final URLs.

The WAF was blocking every upload over 1 MB

Sentinel's exclusion list named /api/uploads, /api/blogs and the rest, while the router mounts /api/ + APIVersion. Not one entry ever matched. Two things were broken by that and neither announced itself: an upload larger than the WAF's inspection cap was rejected with a 413 before the handler saw it, and richtext bodies were never actually stepped aside, so in production a blog post containing ordinary markup could be refused as an XSS payload. The list is built from APIVersion now, so a version bump cannot quietly disable all of it again.

Also

• FileRef carries format, optimised, renditions and the original's key and size. The format is recorded rather than inferred from the URL, so a client never guesses what it received.
• The admin dropzone shows the work: 5.3 MB -> 147 KB JPEG instead of just a filename.
• grit upgrade now delivers the media package and the storage code it hooks into, so existing projects get this without rescaffolding.
• GIF is left alone on purpose: decoding one keeps the first frame only, so optimising an animation would silently throw it away.

Variants also have a page of their own now: Product Variants covers the five tables, the three decisions behind them, why a price is resolved rather than stored, and every endpoint the command mounts.

Columns of your own on the variant matrix

A variant already stores its own photographs, and the matrix had no way to show them and no way for you to add one. It takes a columns prop now, keyed the way a resource definition's own column overrides are keyed: a built-in key patches that column, any other key adds one.

<VariantMatrix
  {...props}
  columns={{
    images: {                              // add
      label: "Photo",
      after: "sku",
      cell: (variant) => <Thumb src={variant.images?.[0]?.url} />,
    },
    sku: { label: "Barcode" },             // rename a built-in
    override: { hidden: true },            // drop one you do not use
  }}
/>

A cell renderer is handed the variant, its unsaved draft, a patch that feeds the same Save button the built-in cells feed, and the resolved price. So a column of your own is editable without being a second way to write: one click still sends one PATCH per row.

images is on the variant type now, too. The server was already sending it.

The detail page had no vertical rhythm

The Details card and anything below it sat flush against each other. The container had no spacing at all: the header carried its own bottom margin, the related tables carried their own top margin, and the Details card and any DetailAside carried nothing, so a custom slot touched the card above it. The spacing moved to the container, because a slot component is somebody else's and should not have to know this page's margins to sit correctly in it.

Adding an option value looked like a duplicate row

The add-value field on an option card used Black as its placeholder, and Black is also the first chip sitting directly above it. The row read as a copy of a value already there rather than an empty field waiting for input, and the submit button stays disabled until you type, so the whole thing looked inert. The fields are labelled now, and the placeholder is plainly an example of something not in the list.

Two 400s per dashboard load, per inline child

An inline --items child is hidden from the sidebar and has no page of its own, but the dashboard still built it a Total and a Latest widget. The server answers those from a whitelist the generator writes only for top-level resources, so every load asked twice for stats on a table nobody browses and got two 400s back. Hidden resources are now skipped by the dashboard and by the widget catalogue.

Every form with a richtext field logged a Tiptap SSR warning.

Tiptap Error: SSR has been detected, please set `immediatelyRender`
explicitly to `false` to avoid hydration mismatches.
  (components/forms/fields/rich-text-field.tsx:31:27)

Tiptap builds its document on the server, React builds a different one on the client, and the two do not match. The warning is the polite half; the impolite half is a hydration mismatch that shows up as an editor dropping the first keystroke somebody types into it.

immediatelyRender: false defers the editor to an effect on the client, which is the documented fix and the one the blog editor already had. The form field did not, so every generated resource with a richtext column carried it. Both admin flavours share the source, so Next and TanStack are covered by the one change.

New projects get it from grit new. Existing ones get it from grit upgrade, verified on a project that had the old version: the field is rewritten, the warning goes, and typing into the editor keeps the first character.

A correction in the Command Explorer

The grit upgrade entry shipped yesterday described --diff as a preview, ending its sample output with "Run without --diff to apply". That is wrong, and wrong in the direction that costs you something.

--diff is not a dry run. It performs the upgrade exactly as it would without the flag, and additionally prints the diff for the files it skipped because you had edited them. There is no preview-only mode. The entry now says so, carries the real output, and the note tells you to commit first.

grit remove resource left the public handler behind. Regenerating the resource with different fields then failed to compile on a column the model no longer had, because that file is written only when absent and the stale allowlist survived. It now goes with everything else, along with the variant files when grit add variants had been run against the resource.

Hierarchies, documented properly

Relationships & Trees gains a section on --tree: the four columns, why a materialized path rather than a recursive CTE, and the question the docs did not answer before, which is how to render level-2 categories on a level-1 page.

A category page asks two things that look like one. "Which categories sit under this one" is answered by children from the tree endpoint, and it is what you render as tiles. "Which products belong here" is answered by descendant_ids from the detail endpoint, because the products are filed under Cameras and not under Electronics. Reaching for the wrong one fails quietly: render descendant_ids and you get a row of UUIDs.

The easy answer to both is one request. GET /api/v1/public/categories/tree returns the whole published hierarchy already nested, assembled server-side in a single query, and it is cached. The roots are your category index; each root's children are the tiles on that root's page. There is no per-node children endpoint and adding one would not help: a shop renders a nav menu on every page, so the tree is already in the cache before anybody clicks.

One trap gets its own paragraph, because it has the most annoying shape a bug can have. A leaf's children is null and not [], since Go marshals an empty slice that way, so node.children.map(...) works on Electronics and throws on Cameras. The helper in the docs guards it once.

The storefront guide gets the same recipe built against a real catalogue, in Step 4e: the tree hook, the depth-first lookup, and a category page that renders sub-category tiles and subtree products together.

Every response shape in both was captured from a running project with a real two-level tree, not written from the handler source.

A new Command Explorer: every CLI command, with a simulated run and the exact files it touches.

Press run on a command and it types itself and streams its real output. Underneath is the part a CLI reference usually leaves out: the list of files that command creates, modifies or deletes. grit generate resource writes thirteen files and edits twelve more, and knowing which twelve before you run it on a project you care about is the difference between a reference and a list of names.

None of it is written from memory. Every output block and every file list was captured from a real run against a freshly scaffolded project, with the file effects read out of git status rather than recalled. A reference that says a command touches nineteen files and then names eighteen is worse than none, because you meet the missing one at the worst moment.

Search covers the command, its summary, its use cases and its file paths, so "which command writes routes.go" is a query rather than a grep. It answers with six. Category filters narrow to Scaffold, Generate, Add, Run, Data, Ship or Meta, every command deep-links by hash, and / focuses the search box.

Commands that write nothing say so plainly rather than showing an empty panel. Twelve of the thirty-seven only read, run or report.

grit generate field and grit generate seeder could not find any resource whose name is more than one word.

grit generate field OrderItem variant_id:string

resource "OrderItem" not found (generate it first): no model found
for "OrderItem": generate the resource first (looked in
apps/api/internal/models and internal/models)

The model was sitting in that exact directory. Every generator in Grit writes a model to models/<snake>.go, so OrderItem lands in order_item.go, and these two commands looked it up as <lower>.go instead. For a one-word resource those are the same string, which is why Product worked and nothing looked wrong; for BlogPost, OrderItem, AccessReview or anything else with two words in it, the command reported a file that was plainly on disk as missing. Both now resolve the snake-cased name, and fall back to the flat one for a model somebody wrote by hand.

Variants in the storefront guide

Build a storefront with Grit gains a step for them, between the category pages and the cart. It covers why the schema is five tables rather than a colour column and a size column, the three decisions inside it that each have an obvious worse alternative, and why a variant's price is resolved rather than stored.

Then the parts you write: a hook on the public payload, the two functions that match a selection to a variant (both of which have a wrong version that sells the wrong thing), a picker that greys out the colour you cannot have in the size you picked, and what changes in the cart and the checkout. The cart line stops being about a product and starts being about a combination, and keying it on the product id alone merges the black shirt into the navy one.

The guide previously ended by suggesting you build all of that yourself, which was true when it was written and stopped being true in v3.167.0.

Blog headings are anchors now

A cross-reference written inside a post scrolled nowhere, because the markdown renderer emitted headings with no id. The invoice guide had carried a dead one since it was published. Headings now take the same slug the docs table of contents uses, so the same heading gets the same id whichever surface renders it.

Variants shipped with five tables, a price resolver, and no way to touch any of it. v3.166.0 installed the schema and the endpoints; there was no screen in the admin, nothing for a storefront to read, and no seed data, so the only way to see a variant was to write the SQL yourself. This release finishes the feature.

The matrix, on the product page

grit add variants now writes an editor into the admin and hangs it off the record's own detail page, because variants are a fact about one product and that is where a shop owner looks for them. Pick which axes the product offers, generate the combinations, then edit SKU, stock, price and active state inline. Edits collect into one Save.

The price column is the part worth reading twice. A variant's price is resolved and not stored, so the table shows what each combination costs and the override box's placeholder shows what it would cost with no override. Clearing that box is never a guess about what the price becomes: the number is already on screen. Typing a value back to what it already was is deliberately not a change, so a save never bumps the version of every row somebody clicked into.

The option library is shop-wide, so it is a sidebar entry rather than a panel on a product: Colour is Colour whether it is on a shirt or a phone case. Options can now be deleted, which they could not before, and the server refuses while anything is built on them.

A payload a storefront can render

GET /api/v1/public/products/:key/variants

{ "options": [ { "name": "Colour", "kind": "swatch", "values": [...] } ],
  "variants": [ { "sku": "...", "price": 356.98, "in_stock": true,
                  "option_value_ids": [...] } ],
  "price_range": { "low": 354.48, "high": 356.98, "single": false } }

One endpoint, because a picker needs one payload: the options to draw, the combinations to match a selection against, and the range a listing card needs for "from 49". It follows the same rules as the rest of the public surface. Stock goes out as a boolean and never as a count, inactive combinations do not go out at all, and a per-value price delta is zeroed unless its option declares that the axis affects price, so a picker can never label a swatch "+ 20" and then resolve to the base price.

A product with no variants gets empty lists and a range of its own price, which is what lets a storefront render one component whether or not variants were ever set up.

Seed data, so there is something to look at

grit seed now writes a Colour and Size library and a real matrix across the first few products, deterministically: Size affects price and XL costs 2.50 more, Colour does not, and one combination in seven is out of stock. That last one is on purpose. The disabled swatch is most of the work on a product page and the hardest state to remember to build, so the seed puts it on screen unasked.

Three bugs from v3.166.0

The tables were never migrated. The model registration looked for its marker in routes.go, where that marker does not live, so Option, OptionValue and both join tables were never added to AutoMigrate. Every variant request then failed on a relation that does not exist, which reads as a bug in Grit rather than as a migration nobody ran.

Changing a product's options left the old matrix behind. The handler said the existing combinations went with it and then deleted only the links, leaving variants describing choices the product no longer offered. It now clears them for real, tells you how many went, and does nothing at all when the option set has not actually changed. The soft deletes are unscoped, too: a soft-deleted link still occupies the unique index, so re-adding the same option used to fail on a row nobody could see.

A second resource with variants took the API down. Running the command twice mounted the shared /options routes twice, and gin panics at boot on two handlers for one method and path. The shared half is now mounted once, and the per-variant update moved from /variants/:id to /product-variants/:id so two resources cannot collide. Existing projects are migrated to the new layout by re-running the command.

Verified end to end on a fresh project: scaffold, generate a public Product, add variants, migrate, seed, then drive the admin in a browser through choosing options, generating a matrix, editing a row, setting an override and clearing it back to the resolved price.

Installing a Grit UI block into a scaffolded app started an interactive setup instead of installing anything.

cd apps/web
npx shadcn@latest add https://ui.gritframework.dev/r/ecommerce-product-grids-grid-with-ratings.json

? You need to create a components.json file to add components. Proceed?
? Select a component library >  Base UI (Recommended) / React Aria / Radix UI

The shadcn CLI will not install into a project without a components.json, and no scaffolded frontend had one. So the first thing anybody does with Grit UI is answer four questions about a project that already has every answer, and one of those questions offers a component library that is wrong here: Grit is built on Radix through shadcn/ui, and picking the recommended Base UI produces components importing packages the project does not have.

Every frontend now ships one, with values read from the project rather than guessed: the tailwind config and css paths the scaffold actually wrote, the cn() in lib/utils.ts, and lucide as the icon library because it is already a dependency. Next.js apps declare rsc: true, Vite apps declare false and point at src/globals.css.

Existing projects get one from grit upgrade, created only when missing. That runs as its own step because there is no upgrade path for apps/web at all, and a config file is safe to create in a way that rewriting a page never is.

Verified end to end on a fresh project: scaffold, install a block with no prompts, typecheck, start the server, and render it in a browser.

Grit UI in the storefront guide

Three blocks are now covered, each wired to the real public endpoints and clicked in a browser before being written down: the product grid, the product detail page with its gallery and variant pickers, and the circular category rail.

With one warning that took a browser to notice. Every prop on these blocks has a sample default, and a prop you do not pass keeps it. Leave out rating and your page states 4.8 from 246 reviews about a product nobody has reviewed. Leave out colours and it offers a Midnight Blue that does not exist. Nothing errors and nothing looks broken, which is exactly why it is worth saying out loud: a block is furnished by default, and furnishing is not data.

The storefront guide’s cart file: wrong package, wrong type, and printed after the component that imports it.

Three problems in one file, all reported by readers following the guide in order.

A package that does not exist

import type { Product } from "@shopfront/shared";   // no such package

The workspace package a scaffolded project actually has is @repo/shared. It appeared twice, in the cart and in the add-to-cart button.

A type the storefront never holds

addToCart took the full Product from the shared package. A storefront only ever has the narrower struct the public endpoint publishes, and passing one to the other is:

TS2739: Type 'CatalogueProduct' is missing the following properties
from type 'Product': stock, category_id, active, created_at, updated_at

Which is the allowlist working exactly as designed, and the guide typing against the wrong side of it. Both the cart and the button take CatalogueProduct now.

Printed after it was used

lib/cart.ts lived in Step 5, and Step 4c’s ProductCard imports it. Anybody building in order hit a missing module and a red editor. The file now appears where it is first needed, and Step 5 keeps what it was actually there to teach: why a client-side cart, why Simple Store rather than Context, why the store starts empty on the server, and why derived values are plain functions.

Verified by extracting the guide’s cart file verbatim into a real project, typechecking it against the guide’s own ProductCard, and clicking Add to cart in a browser: the badge went 0 to 1 and the line persisted with its name, price and image.

A second tree resource in one project did not compile, and a self-referential type broke tsc for the whole workspace.

Generated helpers collided

Four helpers introduced with --tree were emitted at package level, once per resource, into packages every resource shares. One tree resource was fine. Two gave you:

internal/services/department_tree.go:27:6: parentOf redeclared in this block
	internal/services/category_tree.go:27:6: other declaration of parentOf

parentOf, derefID, publicParentOf and optionalID are all named after their resource now, so any number of tree resources coexist.

The generated type imported itself

A self-referential relation emitted an import for its own model, which in that model’s own file is a self-import:

// packages/shared/types/category.ts
import type { Category } from "./category";

export interface Category { ... }

TS2440, “import declaration conflicts with local declaration”, which fails tsc for the whole workspace rather than just that file. The import is skipped for a self-reference now, and parent_id is typed string | null to match the nullable column.

Relationship fields had no label

Carried over from v3.163.0 and worth repeating because the blast radius is wide: RelationshipSelectField never rendered one, so every generated form with a belongs_to had one control floating under the previous field’s label. Both relationship fields are labelled now.

The storefront guide now shows the code it uses

A reader pointed out that the guide called get() and rendered <ProductGridSkeleton /> without ever showing either. An audit of every code block in the guide found eight such references. All eight are written out now: get, formatMoney, ProductGridSkeleton, ProductCard, EmptyCart, StatusBadge, CancelledNotice, and the missing Order type import.

Every one of them was written into a real project and typechecked before it went into the guide, and the catalogue page was loaded in a browser to confirm the card renders and prices format.

The tree view looks like something now, shows its levels, and can add a child to any row.

Rows are cards

The drag handle and the row actions were opacity-0 until hover, so at rest a node had no affordance at all and the panel read as an unstyled list of names. Every row is a card now: a border, a background, a hover state, and a handle you can see before you reach for it.

Each row carries the record’s own image where the resource has one, falling back to an initials tile, so the leading block is a fixed width and labels line up down the whole tree. Under the name sits the slug, or a trimmed description. A node with children shows how many are beneath it, counting the whole subtree rather than one level.

Levels you can see

Indentation alone reads as “further right”. Three things make the hierarchy explicit: a guide line down each level, an elbow joining every card to its parent’s line, and an L1 / L2 chip on the row itself. On a wide screen a third-level row sits a long way from its parent, and counting pixels is not reading.

The panel header states the shape as well: how many top-level rows there are and how deep the tree goes, with Expand all and Collapse all beside it.

Add a child, honestly

There was deliberately no “add a child here” button, because the controller’s create() takes no starting values: the new row would have been born at the root with the parent silently dropped.

So the controller gained createWith(defaults). The form components already accepted a defaults prop for exactly this; nothing carried the values to them. Now a plus button on any row opens the create form with that row already chosen as the parent, and every other resource gains a way to open a form pre-scoped to a parent.

And a label that was missing everywhere

Building this surfaced an older bug with a much wider blast radius: RelationshipSelectField never rendered a label. Every generated form with a belongs_to had one control with nothing above it, sitting under the previous field’s label. Both the single and multi relationship fields are labelled now.

Found by loading the form in a browser, which is also where onAddChild is not defined turned up: the prop reached the row markup without reaching the row’s props, and Go compiling the template that contains it proves nothing about the TypeScript inside.

A tree could not be seeded or created on Postgres, and the tests said it could.

ERROR: insert or update on table "categories" violates foreign key
constraint "fk_categories_children" (SQLSTATE 23503)

A root has no parent, and --tree wrote that as an empty string. GORM creates a real foreign key constraint for the self association, and no constraint accepts "" as a reference: it is neither a key nor NULL. Every seeded category failed, and so did creating one by hand in the admin.

Products then failed too, for the same reason one step removed: with no categories to point at, the products seeder wrote category_id = "" and hit the identical error.

Why the tests passed

The generated tree tests run on SQLite, which does not enforce foreign keys unless asked. Postgres always does. Nine tests covering paths, moves, cycles and rebuilds all passed against a database that was quietly accepting a reference to a row that did not exist.

Those tests now open with:

db.Exec("PRAGMA foreign_keys = ON")

which caught two more writers of the same bad value the moment it was added: Reorder normalised NULL to "" on every root it touched, and RebuildPaths did the same. Both now normalise the other way.

What changed

A self-referential foreign key is a nullable *string, and NULL is the one value that means “no parent” everywhere: in the model, the tree service, the move endpoint, the importer and the public payload. An empty string arriving from a form select is converted at the edge by a generated optionalID helper, because an empty select is exactly how an admin creates a root.

The seeder changed in two ways. A self-reference is no longer given a parent at all, so seeded rows are roots you arrange by dragging, rather than a random hierarchy nobody asked for that can put a row above itself. And a required foreign key with no rows to point at now says so:

cannot seed product: no category rows exist yet. Seed Category first
(generate it with --faker, or add rows in the admin), then run grit seed again

which is the sentence somebody needed, in place of SQLSTATE 23503.

Verified end to end against a real Postgres database this time, not SQLite: 6 categories and 40 products seeded with no warnings, roots created from the admin form, a drag to root, a reorder, a rebuild, and zero rows left holding an empty parent.

Upgrading a project that already has a tree

Run grit update, regenerate the resource, then grit migrate to make the column nullable. If you generated with --public, delete internal/handlers/<resource>_public.go first and let it be rewritten: that file is never overwritten on purpose, and it compares the parent column as a string, which no longer compiles.

Moving a category could add one to the depth of every row in the table.

A subtree move rewrites descendants with a prefix match on the path:

WHERE path LIKE '<old path>%' AND id <> '<moved id>'

When the moved row has no path, that prefix is empty, and LIKE '%' matches every row in the table. The depth increment that follows then lands on all of them.

A row with no path is not exotic. It is exactly what --tree leaves behind when added to a table that already has rows, so this fired the first time somebody dragged one of those rows in the admin, which is the most likely first thing to do. Nothing looked wrong: the tree redrew correctly, and the damage was only visible by reading the rows.

A move now leaves the subtree rewrite alone when there is no old path, because a row without one has no descendants by path anyway. The moved row still gets a correct path, and Rebuild paths on the tree repairs anything already affected. Both the fix and the repair were verified against a database with the damage in it.

Found by reading the rows after driving the admin tree in a browser, and now pinned down by a generated test that moves a pathless node and asserts every other row is untouched. That suite ships into your project and is up to nine tests.

The storefront guide

The Category resource is generated once, with --tree --public in Step 1, rather than being generated plain and regenerated with --public four steps later.

Step 4e is new: multi-level categories end to end. What the path column is for, dragging in the admin, why seeded categories come out flat, and the piece that makes a tree worth having on a storefront, which is showing everything under Electronics rather than only what is filed directly in it.

A drag-and-drop tree in the admin, and a broken page that could not be fixed.

Fix this first

The API keys page has shipped since v3.156.0 with a literal newline inside a TypeScript string, so the admin app failed to compile in every scaffolded project. Run grit upgrade.

Worse than the typo was the reason it stayed: the page was in the scaffold’s file list and not in grit upgrade’s, so the fix had nowhere to go. Those two lists had drifted by 59 files, every one of them unfixable in an existing project. They are now one list, built once and shared, with the files a person is expected to edit excluded by name and the manifest guard still refusing to touch anything with local changes.

The tree view

A resource generated with --tree now gets a Table / Tree toggle on its list page. The tree opens by default, because somebody who asked for a hierarchy is looking for the hierarchy, and the table keeps every filter, tab and bulk action it had.

Drag a row onto another to nest it. Drag it between two rows to reorder. Drag it to the bar at the very top to promote it back to a root. Those three targets are the whole interaction, and a tree with fewer of them is a tree you cannot rearrange: without the sibling bars there is no way to reorder within a parent and no way to get a node back out to the top level.

Native HTML5 drag and drop, no library. dnd-kit would be nicer to write against and would put a dependency in every scaffolded admin for one screen, and a tree is the case the native API handles: one item, no sorting animation, no multi-select.

Dropping a node inside its own subtree is refused twice. The row shows a no-drop cursor and dims before you release, and the server refuses the move with 422 if a stale client tries anyway. A toast after a failed request is a worse answer than a cursor that says no.

There is deliberately no “add a child here” button. The obvious version calls the page’s create form, which takes no starting values, so the new record would be born at the root with the parent silently dropped.

Rows that predate the tree

Adding --tree to a table that already has rows leaves every one of them with a NULL parent_id, because that is what AutoMigrate fills a new column with. Any query spelling “is a root” as parent_id = '' matches none of them.

That bit twice. Roots returned nothing, which was at least visible. Reorder updated zero rows and answered 200, which is the worse kind: the tree redrew in the old order and nothing said why. Both treat NULL as no parent now, reorder normalises it on the way past, and the generated tests cover the migrated-rows case explicitly. There is a Rebuild paths button on the tree for the same situation.

Also: GripVertical is exported from the admin’s icon module. An icon in the map is not automatically a named export, and the drag handle is the first thing to need this one.

Category trees: --tree, and the reason a self-referential relation never worked before.

Electronics above Cameras above Lenses is the shape every shop needs, and Grit could not express it. A self-referential belongs_to did not compile:

invalid recursive type: Category refers to itself

Go rejects a struct that contains itself by value, so the association has to be a pointer. And the foreign key was marked binding:"required" in the model, the request struct, the Zod schema and the admin form, which meant that even once it compiled there was no way to create a root: every one of those four refused the empty parent the top of a tree has. All four are now optional for a self-reference and unchanged for an ordinary relation.

Materialized paths, and why not a recursive CTE

--tree adds parent_id, path, depth and position. The path is /id/id/id/, delimited on both sides so a prefix cannot half-match an id.

grit g resource Category --fields "name:string,slug:slug:name" --tree

name         parent_id  path         depth
Electronics  ""         /1/          0
Cameras      1          /1/2/        1
Lenses       2          /1/2/3/      2

# everything under Electronics, one indexed comparison
WHERE path LIKE '/1/%'

A recursive CTE reads better and is the wrong choice here: Grit supports Postgres, MySQL and SQLite, and CTE support, syntax and performance differ across all three. A generator emitting one query per dialect is a generator with three bugs. Nested sets give one range query and rewrite half the table on every insert, which is miserable for a tree somebody reorders in the admin. A materialized path is identical everywhere, and a move rewrites only the subtree that moved.

depth is stored rather than counted from the path, because counting separators in SQL is three different expressions across three dialects for something a move keeps correct with a single delta.

What gets generated

A tree service with the queries a hierarchy actually needs, each one a single round trip: Tree (the whole thing in one query, assembled in Go, no N+1), Roots, Children, Descendants, DescendantIDs, Breadcrumbs (ids read from the stored path, one IN query however deep), Move, Reorder and RebuildPaths. Plus five endpoints, and eight tests that ship into the project so they run against the dialect it actually uses.

Move is a transaction because three things have to happen together: the node takes its new parent, every descendant’s path is rewritten with REPLACE (one UPDATE, present on all three dialects, and it cannot race the way read-modify-write can), and every descendant’s depth shifts by the same delta.

It refuses a move that would put a node inside its own subtree, which is one string comparison because the parent’s path already contains every id above it. Without that check the subtree is detached from the tree and no query ever finds it again.

The generated tests earned their place before shipping: they caught RebuildPaths rewriting every row on every pass and leaving the table worse than it found it. That function is now deliberately not SQL, for the same dialect reasons as everything else here.

The storefront half

A public tree resource answers two more questions. Its detail response carries descendant_ids, and public foreign-key filters now accept a list, so “products in Electronics” means Electronics and everything under it in one request:

GET /public/categories/electronics   -> { ..., "descendant_ids": [1,2,3] }
GET /public/products?category_id=1,2,3

GET /public/categories/tree          -> the nested menu, one query

Splitting on commas is safe for ids and wrong for anything a person types, since “Smith, John” is one value, so InFilterable is opt-in per column and never inferred from the value. It is one more reason the filter lists are declared rather than guessed.

Adding --tree to a resource that already has rows leaves them with a NULL path, so the root queries treat NULL as no parent, and POST /<plural>/rebuild-tree reconstructs every path from parent_id alone.

A public endpoint you can actually filter, and a similar-items strip.

A category page needs three things a read-only list did not offer: products narrowed to one category, a price window, and a sort order. The first version of --public shipped with no filters at all, which was the safe default and not a usable one.

Filters, derived from the allowlist

A generated public handler now declares its filterable columns, and the rule for which ones is the whole design: the published ones. A column safe to show is safe to filter on. A column held back from the response stays unreachable from the query string, because otherwise ?cost_price=12 leaks by comparison exactly what the allowlist refused to leak directly.

# published, so filterable
GET /public/products?name=Kettle
GET /public/products?price_min=400&price_max=800
GET /public/products?category_id=<id>&sort_by=price&sort_order=asc

# held back, so ignored rather than applied
GET /public/products?stock=0          -> all 24 rows
GET /public/products?cost_price=0     -> all 24 rows
GET /public/products?archived_at=x    -> all 24 rows

Foreign keys are the one addition: a category page cannot exist without ?category_id=, and filtering by an id is not publishing the relation. The id identifies a row the endpoint was already willing to return.

Text and richtext are left out, because equality on a description is never the question, and search already covers them.

Price windows

paginate.Config gains RangeFilterable, a separate whitelist from Filterable because the two answer different questions: equality on a price is almost never what a caller means, and a range on a status is meaningless. Numeric published columns get both. A bound that does not parse widens the window instead of failing the request, since ?price_min=cheap is a typo and an error page is a worse answer than results.

Similar items

--public on a resource with a belongs_to also mounts GET /public/products/:key/related: others sharing this one’s category, newest first, itself excluded, capped at 24 however large ?limit= asks. A resource with no parent gets no endpoint rather than one returning an arbitrary set.

Which relation defines similarity is the generator’s choice and not the caller’s. That keeps it one bounded query and stops the endpoint becoming a back door to filtering on something unpublished.

And the upgrade path, which is where this nearly went wrong

A handler declaring RangeFilterable does not compile against a paginate.go written before that field existed, so regenerating in an older project would have reported success and left a broken build. grit generate resource --public now brings paginate forward first, and only when the manifest proves nobody has edited it; a modified copy is left alone with a warning naming the one field to add.

Same for the route: a project that already had the two public routes gets just the related one added, rather than the generator seeing “already wired” and leaving a handler nothing ever calls.

Four bugs a browser found that a compiler could not.

Every endpoint in the new public API surface was verified with curl, and every one of these survived that. They came out of loading a storefront in a real browser instead.

The CSP blocked the API

A CSP source expression matches paths exactly unless it ends in a slash, so connect-src http://localhost:8080/api/v1 allows that one path and blocks every route under it. The Next.js and Vite configs put NEXT_PUBLIC_API_URL straight into the policy, so a value carrying a path silently broke every request in the app. Both configs now reduce it to an origin.

Silently is the operative word: there is no HTTP status, no server log, just a console violation and a fetch that never happened.

next/image threw on your own uploads

next/image refuses any remote host it was not told about, and it throws instead of falling back to a plain <img>, so a single product photo took the whole page down with “hostname is not configured”. Stored files live on the storage origin, never the app’s own, so this hit anybody who rendered an upload. The scaffolded config now declares that host, derived from the same NEXT_PUBLIC_STORAGE_URL the CSP uses, plus picsum.photos in development because that is where --faker points its placeholder images.

Regenerating a resource could stop the build

Adding a file field to an existing resource and regenerating declared the handler twice, and the API stopped compiling with no new variables on left side of :=. The injection guard compared the whole block it was about to write, and the new block carried Storage: svc.Storage, so it did not match the one already there.

productHandler := &handlers.ProductHandler{
	DB: db,
}
productHandler := &handlers.ProductHandler{   // the generator wrote this second one
	DB: db,
	Storage: svc.Storage,
}

The guard is now the declaration rather than the body, and a handler already declared is left as it is, because those lines are somewhere a person may reasonably have added a field. With one exception: a resource that has just gained its first file field gets Storage wired into the existing block, since without it the create and update flows skip the S3 cleanup on replace and never mark uploads claimed.

A Postgres-only query on every health check

The health endpoint counted tables with information_schema.tables WHERE table_schema = current_schema(), which is Postgres. On SQLite that logged a red SQL error on every poll of the System Health page, and on MySQL it returned nothing, because current_schema() does not exist there either. Now three dialects get three questions, with the logger silenced on failure: a missing tooltip figure is not worth a stack of alarming log lines on a healthy server.

Per-key rate limits, and an admin that teaches the difference between the two kinds of key.

A limit per key

A key can now carry its own requests-per-minute figure. Sentinel already limits by IP, and these answer different questions: an IP limit protects the server from a flood, a key limit protects you from one client. A partner integration polling every second, or a storefront with a render loop, throttled without touching the limit that applies to everybody else.

curl -X POST .../api/api-keys -d '{"name":"storefront","kind":"publishable","rate_limit":3}'

# then, against a limit of 3
1 -> 200   X-RateLimit-Remaining: 2
2 -> 200   X-RateLimit-Remaining: 1
3 -> 200   X-RateLimit-Remaining: 0
4 -> 429   Retry-After: 60

A fixed window in Redis: one INCR against a key carrying the current minute, with a two minute expiry so the bucket cleans itself up. A sliding window would be fairer at the boundary and costs a sorted set per key; a fixed window is one round trip, which is the right trade for throttling a misbehaving client rather than metering billing.

Two deliberate choices worth naming. No Redis means no per-key limiting, rather than falling back to an in-process counter: an in-memory count is per instance, so the effective limit would silently multiply by however many API containers happen to be running. And a Redis error fails open, because refusing every request when a counter is unreachable turns a cache outage into an outage, and the IP limit still applies.

The admin page

Creating a key now starts with choosing its kind, as two cards that say what each one is for, because that choice decides everything else.

A publishable key is shown in full in the table, with a copy button. A secret key shows only its prefix. That difference is the whole design made visible: the publishable one is already in every copy of your app, so hiding it here would protect nothing and cost you the ability to read it when setting up a new environment. The secret one exists only as a hash.

For the same reason, creating a publishable key does not open the “copy this now or lose it” panel. Putting it behind that panel would teach exactly the wrong lesson about what it is.

Endpoints and origins get a textarea each, with the guidance next to the field rather than in documentation somebody has to find: a trailing * matches a prefix, and origins should be left empty for a mobile app, because native clients send no Origin header and an allowlist would reject every request they make.

Each row shows its kind, its limit, and how many endpoint and origin restrictions it carries, with the full lists on hover.

CORS from settings, and the preflight header that made every storefront request fail in a browser.

The second one first, because it is the bug. X-API-Key was missing from Access-Control-Allow-Headers. A storefront calls the public endpoints with that header, cross-origin, and a header absent from that list is stripped by the browser during preflight. So every public request failed in every browser and worked perfectly under curl, which is the worst shape a bug can have. Found by sending a real OPTIONS request rather than by reading the middleware.

CORS origins now come from a cors.origins setting, resolved per request:

# before whitelisting
curl -X OPTIONS .../api/v1/public/products -H "Origin: https://myshop.com"
  (no Access-Control-Allow-Origin)

# whitelist it in the admin, no restart
curl -X PUT .../api/v1/settings -d '{"values":{"cors.origins":"https://myshop.com"}}'

# immediately
  Access-Control-Allow-Origin: https://myshop.com

Per request rather than captured at boot, because the point of putting origins in settings is that somebody adds a domain at 9pm and it works. A setting that existed and did nothing until the next deploy would be worse than not offering one. The cost is a comparison against a single-digit list, on a store already cached in memory.

CORS_ORIGINS still applies when the setting is empty, which is the default, so nothing changes for an existing project until somebody types a domain into the admin.

Public responses are cached now

CacheResponse has been in internal/middleware/cache.go for a long time and was mounted on nothing at all. It is now on the public group, and only there.

Only there for a specific reason. The cache key is the URL and nothing else. On a public endpoint that is exactly right: every caller gets the same answer, so one copy serves all of them and a catalogue page stops hitting Postgres on every visit. On a protected endpoint the same key would serve one user's data to another.

The TTL is a cache.public_ttl_seconds setting, default 60, read once at boot. Unlike the origins, a cache lifetime is not something anybody changes at 9pm, and re-reading it on the hot path of a cached response would cost more than it saves. The docs say it needs a restart rather than implying otherwise.

Verified: two identical public requests return X-Cache: MISS then X-Cache: HIT, and a protected endpoint returns no X-Cache header at all.

Four bugs found by building the storefront guide instead of reading it.

I followed the ecommerce guide command by command in a fresh project. Everything below is something that walkthrough hit, and three of the four would have stopped a beginner cold.

A public handler that did not compile

--public, shipped yesterday, emitted models.FileRefs for a files field. The real type is files.FileRefs from internal/files. So any resource with an image on it produced a public handler that failed to build, which is most of the resources anyone would want public. The type map now returns what the model actually declares, and the import block is computed from the fields rather than guessed, so a resource of plain strings does not get an unused import instead.

Faker colliding on unique columns

sku:string:unique plus --faker --count 40 logged a constraint failure and seeded 39 rows. gofakeit.Word() draws from a finite word list, so forty rows on a unique column collide, and the seeder had no notion of unique at all. A unique string column now gets a readable prefix plus entropy, so a SKU seeds as SKU-APEJ0818. Forty of forty, forty distinct.

Seeded products with no category

The seeder does link a belongs_to properly: it plucks the parent ids once and picks one per row. But if no parent rows exist the foreign key is silently left empty, and generating Category without --faker means there are none. Forty products, zero categories, no error anywhere.

That one is a documentation bug rather than a code bug, and it is fixed in the guide: generate the parent with its own seed data first. Worth knowing as a rule, because it applies to every relation you seed.

The docs reference moved out of routes.go

141 route overrides and 28KB of descriptions sat in the middle of the file you open to find out how the application is wired: 38% of routes.go, none of it about routing. They now live in internal/routes/apidocs.go, and routes.go went from 1482 lines to 897.

The generator injects into the new file and falls back to routes.go for projects that predate the split, so an older project keeps documenting its endpoints rather than silently stopping.

Also

Every scaffolded home page linked to grit-vert.vercel.app/docs, a preview deployment rather than the docs site. Six links across two templates now point at gritframework.dev.

Publishable API keys, and --public on the generator.

Generated CRUD sits behind auth, which is right for an admin resource and wrong for anything a customer reads. A storefront has no logged-in user, so calling the generated list endpoint returns a 401. That is the first wall anyone building a public-facing app walks into, and until now Grit had no answer for it.

grit generate resource Product --fields "name:string,slug:slug:name,price:float,cost_price:float,stock:int" --public

  ✓ apps/api/internal/handlers/product_public.go (3 field(s) published)
    Held back: cost_price, stock
    Add any of those to the publicProduct struct in that file to publish them.
  ✓ GET /api/v1/public/products and /api/v1/public/products/:key (API key required)

Note what it held back without being asked. cost_price because a name containing cost, margin, profit, internal, supplier or wholesale is never published whatever its type. stock because a raw count is a business fact your competitors enjoy and a page almost always wants “in stock” instead. Relations are held back too: publishing one would publish a whole related record nobody vetted.

The response is an allowlist struct, never the model, which is the opposite default to the admin surface and the right one when the audience is the internet. A column you add next month is private until somebody adds it to that struct. The file is written once and never overwritten on a regenerate, because the allowlist in it is yours.

Two kinds of API key

A key your storefront holds is not a secret. It ships inside your JavaScript bundle or your mobile binary, where anyone can read it, and an APK is a zip file. Calling it a secret and hoping is how an admin credential ends up in a JavaScript file.

So a key now declares what it is. grit_pk_... is publishable: safe in a browser or a phone, and structurally incapable of reaching a route that was not marked public. Not because it lacks a permission, but because the middleware for protected routes refuses the kind outright, before permissions are consulted. No combination of scopes talks its way past that, and a publishable key never inherits its owner's permissions at all.

grit_sk_... is secret: server side only, reaches whatever its owner can. It is hashed and shown exactly once. A publishable key is stored in clear and readable from the admin forever, because it was never a secret and pretending otherwise costs the one thing that makes it pleasant, which is reading it again when you set up a new environment.

Keys also carry two new restrictions, which are different axes rather than alternatives. endpoints narrows a key to specific routes as method plus path with an optional trailing wildcard. origins restricts browser use to named sites. Worth having and worth not overestimating: an origin check stops another site's page using your key from a customer's browser, and stops nothing that is not a browser. Leave it empty for a mobile app, which sends no Origin header at all.

Two keys in every new project

The seeder now issues a publishable and a secret key, prints both, and writes the publishable one into apps/web/.env.local so a fresh storefront can call the API without anyone copying anything. Idempotent by name: seeding twice does not mint a second pair you cannot tell apart.

Verified against a fresh project. A publishable key on a public endpoint returns 200; the same key on a protected endpoint returns 403 with a message naming the fix; a secret key on that protected endpoint returns 200; and the public response contained exactly id, name, price and slug, with cost_price, stock, internal_note and active all absent.

Backward compatible: keys issued before kinds existed have no pk or sk segment and are still read as secret keys, exactly as they were.

A settings registry, so configuration is not a choice between a deploy and a code change.

Every application needs values that are configuration but not environment variables: company name, invoice prefix, default currency, whether to email on a new order. Those had three homes in Grit and all of them were bad. In .env, which needs a deploy to change and which no admin can touch. Hardcoded. Or a hand-rolled settings table with a hand-rolled admin page, written again in every project.

Declare it next to the code that reads it:

settings.Define(settings.Setting{
    Key:      "invoice.prefix",
    Type:     settings.TypeString,
    Default:  "INV-",
    Label:    "Invoice number prefix",
    Help:     "Appears before the sequential number on every invoice.",
    Group:    "Billing",
    Validate: settings.MaxLen(8),
})

and read it, typed, anywhere:

prefix := settings.String(ctx, "invoice.prefix")
notify := settings.Bool(ctx, "notifications.email_enabled")

From the declaration you get the admin page, grouped and with the right control per type, validation at write time, a cache, and a resolution order that is stated rather than assumed: user override, then tenant override, then the stored global, then the environment, then the declared default. That order is what lets a per-user timezone and a per-tenant currency work without either knowing the other exists, and it is why this is quietly load-bearing for the billing and entitlements work later.

A setting declared global refuses a per-user override rather than storing a row nothing will ever read. Silently accepting it would be worse: the change appears to save and then does nothing, and there is no way to find out why.

A batch save validates everything before writing anything, because a half-applied save leaves the page showing a mix of stored and rejected values with no way to tell which is which. Changes go through the event bus, so they land in the activity feed: a settings change alters behaviour everywhere and otherwise leaves no trace.

Where the environment sits took a correction during testing. The store resolved stored-over-env while the handler refused to write whenever an env var existed, which made app.name permanently read-only in every scaffolded project, because the scaffold sets APP_NAME. Two precedences in one feature. The store's is the right one: the admin page is the point, and a value somebody sets there has to take effect. The environment supplies what the application boots with. Something that genuinely must not be changeable belongs in config, not here.

TypeSecret is a string the API never returns once set. An SMTP password belongs there: an admin can replace it and cannot read it, which is what people expect and rarely get.

Verified against a fresh project across 24 checks, run twice to prove the suite is not depending on a clean database.

Workflows: a status field can be a process, not just a column.

A select field accepts every one of its options on every record. draft can jump straight to shipped, a shipped order can go back to draft, and a support agent can mark an invoice collected. Any rule about which of those is allowed lived in the author's head, or in a check they had to remember to write in every place the field was touched.

A workflow: block on the field states the rules once:

- name: status
  type: select
  options: [draft, submitted, approved, shipped, cancelled]
  workflow:
    initial: draft
    terminal: [shipped, cancelled]
    transitions:
      - action: submit
        from: [draft]
        to: submitted
      - action: approve
        from: [submitted]
        to: approved
        permission: orders.approve
      - action: cancel
        from: [draft, submitted, approved]
        to: cancelled
        confirm: true

The states come from the field's own options rather than being repeated under workflow:. Two lists of the same thing drift, and the drift is silent: a transition to a state the dropdown never offers.

From that, grit generate resource writes a definition in internal/workflow/, a guarded transition service, and POST /api/orders/:id/transitions/:action. An illegal move is a 422 that names the state the record is in and lists what is allowed from there, rather than a successful write leaving a record somewhere the business rules say cannot exist.

The guard is in the service, not the handler, because a handler is one caller. A job, a CLI command, an importer and an offline sync push all reach the service, and a rule enforced at one entrance is not enforced. The write is also conditioned on the current state, so two people pressing Approve at the same moment do not both succeed: the second affects no rows and gets the same 422.

Every transition emits its own event rather than a generic updated. A subscriber that cares about orders shipping should not have to diff two versions of a record to work out that is what happened, and the activity feed reads “Ship: approved to shipped” against the order's reference. This is the first thing built on the event bus from v3.150.0, and it is why that came first: without it a workflow engine would have grown its own hook mechanism and become a fifth disconnected system.

Validation runs when the definition is parsed, so a broken machine is a CLI error rather than a panic at boot. The check worth having is the one for a state nothing can leave: it is invisible until a record lands there in production and cannot be moved, and the message says both ways to fix it.

Verified against a live server: an order starts in its declared initial state, a legal move works, draft to shipped is refused with the allowed actions named, an unknown action is refused, a terminal state has no way out, and the full path submit to approve to ship works with each step in the activity feed under its own label.

Domain events: webhooks and realtime now actually fire.

Grit shipped four systems that want to know when something happens: the activity log, outbound webhooks, realtime websockets and background jobs. A generated handler told exactly one of them. I checked a scaffolded project and no handler anywhere called DispatchWebhook, and none broadcast a resource change. Both features were complete, documented, and fired by nothing.

Making them work meant hand-writing the call in every handler, for every operation, on every resource. Forgetting one produced no error: just a webhook subscription that never heard anything.

There is one bus now. A handler says what happened, once:

events.Emitted(c, "invoices", "Invoice", "created", item.ID, item.Number, "", nil, item)

and the audit log, realtime and webhooks are subscribers. The generator emits that line in place of the services.LogCreate it used to write, so every resource has created, updated, deleted and bulk events from the moment it is generated, with no per-resource wiring.

Two delivery modes, and which one a subscriber gets is a real decision rather than a setting. Audit is synchronous: the activity row exists before the caller is told the write succeeded, and it is the one subscriber that legitimately needs the request context, because the feed records IP and user agent. Everything with a network call is asynchronous: a webhook endpoint that takes four seconds must not make the API take four seconds.

The async copy of an event carries a nil request context, on purpose. A gin context is cancelled and recycled once the handler returns, so an async subscriber reading it would be looking at somebody else's request. Nil turns a subtle data race into an obvious nil pointer the first time anyone tries.

The queue is bounded at 1024 and drops when full rather than growing. An unbounded queue turns a slow subscriber into memory exhaustion, which fails later and worse. Drops are counted and reported on /api/health alongside the subscriber count and queue depth, because “did my webhook fire” deserves a better answer than reading logs. A subscriber that panics is logged and the others still run: a webhook formatter falling over is not a reason to fail a write that already happened.

Verified by running it. The activity feed is unchanged and the row exists with no sleep in the test, which is the assertion that proves audit is genuinely synchronous. And a ledgers.created event reached a connected websocket client, which had never happened in a generated Grit project.

This is the substrate the next few features sit on. Workflows emit transitions rather than inventing their own hooks, notifications subscribe rather than needing their own trigger, and automation rules become a subscriber with a condition attached.

Offline behaviour is declared, enforced and diagnosable.

Yesterday's release gave every client a sync engine. It mirrored every registered model, asked a human about every conflict, kept nothing off the wire and had no age limit. Those are reasonable defaults and nobody chose them, which is the difference between a feature and magic. A developer shipping a point-of-sale app had no way to state what they needed and no way to find out what they had.

A sync: block in the resource definition now states it: mode, conflict strategy, which fields cross the wire, which never leave the device, and how stale the mirror may get before the app should say so.

Three conflict strategies. manual parks the change with both versions attached and a human decides, which is what every project had and stays the default, because silently discarding somebody's work should be opt-in. server_wins discards the client's change and hands back the server row, for records a back office owns. client_wins overwrites, for records with a single author where the version check protects nothing.

Enforced on the server, not the client. A rule an old build can ignore is not a rule, so the decision is made where a request cannot argue with it, and GET /api/sync/policy publishes the declaration so clients render the right UI rather than keeping their own copy to drift. local_only is stripped on both sides, which is what makes it a promise rather than a convention.

max_offline_age is advisory by necessity, because a client that has not synced is by definition not talking to the server. What it buys is a client that can say so: stale is its own badge state, ranked above offline, because “you are offline” and “this data is too old to act on” are different messages and only one of them should stop somebody shipping against a three-day-old stock level.

grit sync doctor exists because every mistake here is silent. A field allowlist naming a column that does not exist errors nowhere: it excludes the real column, and every client mirrors rows with the value missing. A model with no Version field cannot detect a conflict at all, so it takes whichever write landed last and nobody is told. It also catches a policy that is declared but not enforced, which is the worst state of the three.

useSyncHealth covers the same ground inside the app. An outbox that stopped draining three days ago looks exactly like an outbox with nothing in it, and the only difference visible from inside is the pending count, the age of the oldest queued change, and the time since the last successful sync.

On encryption: SQLiteAdapter takes an already-open database, so an SQLCipher connection keyed from the OS keystore encrypts the mirror on mobile and desktop with no change on our side. The browser gets nothing, deliberately. There is no keystore, so any key the page holds sits in JavaScript beside the data it protects, and an encrypted-IndexedDB option would defend against a threat nobody has while implying it defends against the one people picture.

Verified by running it. Twenty-four checks against a live server: the policy is published, local_only never reaches the database, pull sends only the allowlisted columns plus the bookkeeping ones a client cannot work without, server_wins comes back as its own code with the server row attached, and a model with no declared policy still parks conflicts for a human. Then twenty-three more against the client: it reads the policy, falls back to defaults when the server is unreachable rather than refusing to open, strips local-only fields before sending, applies a server_wins override without prompting, skips online_only models entirely, and reports stale.

Two upgrade-path bugs fixed along the way. Everything policy-related lives in a new internal/sync/policy.go rather than as an edit to registry.go, so grit generate resource can add it to a project generated before policies existed. And the model discovery behind grit add offline matched only Register, so the one resource with a deliberately declared offline policy was the one left out of the mirror.

Offline sync is a property of a resource, not of the desktop app.

The API has served /api/sync/pull and /api/sync/push since v3.60, and every generated resource registers itself with the sync registry. The server side was already complete. What was missing was a client anywhere except apps/desktop, where the engine is written in Go and cannot be imported by a browser or a phone.

grit add offline installs packages/sync: the same mirror, the same outbox with the same squash rules, and the same version-checked conflict handling, in TypeScript, over a storage interface. Three adapters ship: IndexedDB for web and PWA, expo-sqlite for mobile, and an in-memory one for tests and server rendering. It wires itself into whichever of apps/web, apps/admin and apps/expo your project has, and mirrors every model the API registered, read out of routes.go rather than from a list that can go stale.

useOfflineResource("products") is the whole interface. It returns rows from the mirror and writes through the outbox, and the screen calling it does not branch on connectivity anywhere. useSyncStatus gives you the badge, useSyncConflicts gives you both sides of a conflict and the two ways to end it.

The parts worth knowing about are the ones where doing the obvious thing loses data. A conflicted change is parked rather than retried, because replaying it would overwrite exactly the state the user is being asked about. Concurrent syncs share one run, because two of them draining the same outbox send every change twice and the second copy conflicts with the first. Creating a row and then deleting it while offline cancels both ends instead of sending a delete for something the server has never seen. A pull follows full pages, because stopping after one would leave the mirror quietly behind after any bulk change.

Verified by running it: 45 checks against a mock server covering the squash rules, tombstones, cursor pagination, conflict parking, resolve, revert, retry after a transient error, and concurrent syncs. Typechecking proves a file is well-formed and says nothing about whether an offline app loses your work.

Also in this release, three documentation corrections. Email verification and API keys have shipped for a while and the docs never mentioned either, which is why an outside review filed both as missing features. They are now in Authentication, with the endpoints, the key format, and why the secret is hashed with SHA-256 rather than bcrypt. MySQL is named in the README stack table. And the mobile offline page no longer says that offline writes are a desktop-only feature.

grit upgrade stops overwriting the files you have edited.

It used to overwrite all of them, every time. The function that wrote them took a force parameter and never read it, so the flag was decoration and every upgrade was a forced one. If you had changed a framework component, the upgrade took it back and told you it had updated 87 files.

Grit now records what it writes. Every generated file gets an entry in .grit/manifest.json: which generator wrote it, at which version, and the hash of what it wrote. An upgrade compares that against what is on disk, so it can tell a file nobody has opened from one you have customised. Untouched files are replaced. Edited ones are named and left exactly as they are.

grit upgrade --diff prints a unified diff of your version against the new one, so you can take the parts you want by hand. grit upgrade --force does what upgrade always did.

The check sits at the single function every generated byte passes through, not at the callers. Upgrade regenerates the web app, the admin, the docs and the root config through four different paths that fan out to dozens of template functions, and one check at the one choke point is both smaller and harder to leave a hole in.

Two details that are not cosmetic. Hashes are taken with line endings normalised, because git on Windows checks files out with CRLF while the generator writes LF, and hashing raw bytes would report every file in a fresh clone as edited: an upgrade trusting that would refuse to update anything. And injection re-records rather than invalidates, so adding a route to routes.go does not make it read as hand-edited from then on.

A project created before this release has no manifest, so nothing can be said about what has been edited in it, and its first upgrade behaves exactly as it always did. That upgrade writes the manifest. Every one after it is protected. Commit .grit/manifest.json so the whole team gets it.

Also: grit generate resource records its files under the resource that owns them, which is what grit upgrade --resource will read next.

MySQL is a supported database.

Point DATABASE_URL at mysql://user:pass@tcp(host:3306)/db and the API connects. The scheme is stripped rather than parsed, because the driver wants its own DSN format and not a URL, and parseTime=true&loc=UTC is appended when absent: without it MySQL returns DATETIME columns as raw bytes and every time.Time field on every model fails to scan.

Three things had to change behind that. The two type:jsonb column tags are gone, since datatypes.JSON already picks jsonb on Postgres and json on MySQL by itself, and naming a Postgres type explicitly failed AutoMigrate on a database that has no such type.

The second was the dangerous one. Generated handlers skip the reload after a write when the generator can see the write is a single statement, on the strength of RETURNING filling the struct. MySQL has no RETURNING, and it does not say so: the write succeeds, the clause is dropped, and the record comes back with id, created_at and version all at zero. A create would have answered 201 with a half-empty body and no error anywhere. The optimisation is now decided at build time and applied at run time, through database.Write and database.SupportsReturning in the new internal/database/dialect.go. On Postgres and SQLite this costs one boolean.

The third: ?active=true arrives as a string. Postgres reads it as a boolean; MySQL stores the column as tinyint(1), coerces a non-numeric string to 0, and quietly matches nothing. Query filters now read the model schema and convert boolean columns only, because "true" is a legitimate thing for a varchar to contain.

grit generate resource writes internal/database/dialect.go if your project predates it, so a resource generated in an older project still builds.

Verified against MySQL 8.4: 33 tables migrated, both JSON columns landed as native json, create returns a complete record, and ?active=true returns rows where it previously returned none.

The detail page is customisable the same way the list page is.

Every customisation so far applied to the list view. The record page was a monolith with all its state inline, which is exactly the shape ResourcePage was in before its controller was extracted, so it got the same treatment. useResourceDetailController(resource, id) returns the record, the visible columns, the inline line-item fields, the related resources resolved out of the registry, and the edit, delete, print and PDF actions with their dialogs. The stock page is markup and nothing else now, which is the proof the hook is complete enough to build your own on.

Four slots. DetailPage replaces the whole thing, for a record that is not a field list: an order with a fulfilment timeline, a ticket with a thread. DetailHeader, DetailFields and DetailAside each take one part and leave the rest.

The three part slots receive the controller as a prop instead of calling the hook, and that was a bug before it was a design. Built as they first were, each slot made its own controller, so pressing Edit in a custom header opened a sheet the page around it never read and nothing happened. Caught by clicking the button. They share one controller now, which is what lets a part drive the page it sits in, and it matches how the list slots already worked.

form on the detail controller carries the record as well as the flag, mirroring the list controller. Without it every caller reaches for c.record and meets the difference between undefined, meaning still loading, and null, meaning creating, which the stock form distinguishes and a query result does not.

Filter presets as tabs, and query filters that actually filter.

A tab is a named set of query parameters. "Unpaid" is not a different page, it is this page with status=pending, and a tab says that more plainly than a dropdown somebody has to open to discover:

// apps/admin/resources/orders/orders.ts
table: {
  tabs: [
    { key: "all",     label: "All",     count: true },
    { key: "unpaid",  label: "Unpaid",  filters: { status: "pending" }, count: true },
    { key: "shipped", label: "Shipped", filters: { status: "shipped" }, count: true },
  ],
}

A real tablist, so arrow keys move between tabs and Tab leaves the group. Without roving focus a keyboard user walks through every filter on the way to the table, which with six tabs is six stops before reaching the thing being filtered. The table carries the matching tabpanel role and is labelled by the active tab, so a reader hearing a tablist also learns what it controls.

Counts are opt-in per tab, because each one is a request. The badge appears when its number arrives rather than showing a zero first: a tab that says 0 and then says 47 is worse than a tab that said nothing for a moment.

The filters they depend on were never wired up. Building this turned up that paginate.Bind never collected column filters from the query string. The code that applies them was there, with a comment promising ?status=active&building_id=..., and nothing ever populated it, so the admin's existing filter dropdowns sent parameters the API discarded. It went unnoticed because generated resources ship with an empty filters: [].

Query parameters that are not reserved pagination keys are collected now, and applied only where the handler whitelists them:

// apps/api/internal/handlers/shipment.go, generated
paginate.Config{
  Searchable: []string{"reference", "carrier"},
  Sortable:   map[string]bool{"id": true, "created_at": true, ...},
  Filterable: map[string]bool{"id": true, "reference": true, "status": true, ...},
}

The whitelist is not optional: the column name is interpolated into the WHERE clause, so an unfiltered version of this would let a caller write the query. Values were always parameterised. An unknown column is ignored rather than rejected, so a stray parameter is never an error. Verified against a running server: the three status tabs return 4, 1 and 5 of 10 rows, an unknown column changes nothing, and a quoted injection in the value matches zero rows because it is treated as a value.

grit upgrade does not touch API code, so an existing project needs grit generate resource to pick up the whitelist, and its tabs render unfiltered until it does.

One folder per resource.

Adding the .custom.tsx overlay doubled the number of files in resources/, and the flat layout stopped scaling: with twenty resources it is forty files in one directory, and the two halves of a single resource sort apart from each other whenever another name falls between them.

resources/
  index.ts
  products/
    products.ts          generated, rewritten freely
    products.custom.tsx  yours, written once
  users/
    users.ts
    users.custom.tsx

The overlay import inside the definition is unchanged. It was always ./products.custom and the two files are still siblings. What changed is the registry, which now imports ./products/products, and the route pages, which import @/resources/products/products.

Existing projects are moved for you. grit upgrade gives each resource its folder, carries the overlay across with it, and rewrites both the registry imports and the alias imports in the route pages. It runs before anything is written, because dropping a new users/users.ts into a project still holding a flat users.ts would leave two definitions and a registry pointing at the stale one.

Nothing is deleted, only moved, and the whole thing is safe to run repeatedly: the import patterns refuse a path that is already nested, so a second pass cannot produce products/products/products. There are tests for exactly that, and for the registry surviving untouched, since index.ts is not a resource and moving it would break every import at once.

generate, sync, grit g field and remove resource all read both layouts, so a project that has not upgraded yet keeps working. Writes always use folders.

Two fixes to yesterday's bulk actions. The bar is fixed to the bottom of the viewport now rather than sitting at the foot of the table. The original reasoning, that a floating bar covers the rows it acts on, only holds for a table that fits on screen: with twenty rows you tick something near the top and the bar appears below the fold, so as far as the operator can tell nothing happened. It is a centred pill rather than a full-width bar, and the page reserves space underneath while it is shown, so the last rows can still be scrolled clear of it.

And the bulk hook falls back to one request per row when POST /<resource>/bulk returns 404. That is the normal state of an upgraded project: grit upgrade replaces the admin but never regenerates API handlers, so the browser gets the new code while the server keeps the old routes, and without the fallback every existing install would 404 the moment somebody ticked a row. The fallback is genuinely worse, N requests and a partial result if one fails, so run grit generate resource for the real endpoint. Resources with no declared bulkActions now default to edit, export and delete rather than delete alone, since those three work against any API.

Bulk actions: edit, archive, restore, export and delete.

Tick some rows and a bar appears at the foot of the table. Until now the only thing you could do with a selection was delete it, and that was two buttons squeezed into the toolbar between the search box and the column picker, which put a Delete one gap away from a text field.

Archive is a real state, not a status field you have to invent. Every generated model gains archived_at, and it is deliberately not deleted_at: a soft-deleted row is gone as far as the app is concerned, while an archived one is still listable, still exportable and restorable in one click. The list endpoint hides archived rows unless ?archived=true asks for them, and the resource page grows Published and Archived tabs. Archive and Restore never appear together, because offering both is how an operator archives what they meant to bring back.

One request, one transaction. Bulk delete used to fire one DELETE per row from the browser: N transactions, N audit entries, and a half-applied result when the eleventh failed, with the operator told it failed while ten rows were already gone. There is a real endpoint now:

POST /api/v1/products/bulk
{ "action": "archive", "ids": ["...", "..."] }

{ "data": { "affected": 9, "requested": 12 },
  "message": "9 products archived" }

It reports what it actually did rather than what was asked. Archiving twelve rows of which three were already archived says nine, and the toast says so too. The patch action reuses the same whitelist PATCH does, so a client sending id or created_at has them dropped rather than honoured, and the id list is capped at 500 because an unbounded IN clause is a way to lock a table by accident.

Bulk edit is one field, on purpose. Editing every field at once means deciding what an empty input means, and there is no good answer: clearing destroys data nobody looked at, ignoring makes it impossible to clear anything. One field sidesteps it and is the actual job nine times in ten. Unique columns are left out of the list, because writing one SKU to forty rows is either a constraint violation or, worse, not one.

All of it is customisable. Pick the built-ins per resource with table.bulkActions, and add your own from the overlay file, where they can hold functions:

// resources/shipments.custom.tsx
bulkActions: [
  {
    key: "mark-delivered",
    label: "Mark delivered",
    icon: "CheckCircle",
    confirm: "Mark every selected shipment delivered?",
    visible: (rows) => rows.every((r) => r.status !== "delivered"),
    onSelect: async (ids, rows, { refresh, clearSelection, announce }) => {
      await markDelivered(ids)
      refresh()
      clearSelection()
      announce(rows.length + " marked delivered.")
    },
  },
]

The action gets the ids and the rows, so acting on what the operator ticked needs no second round trip for data already on screen. Replace the bar outright with the BulkBar component slot if the shape is wrong for you.

The bar sits in the flow at the foot of the table rather than floating over it: a floating bar covers the rows it acts on, and on a short table it covers the last two entirely. It is a labelled region, so it appears in a landmark list, and its arrival is announced, because ticking a checkbox does not move focus and a bar that silently appears is a bar a keyboard user never learns about. Delete is the only red control in it.

One pagination bug fixed on the way. Meta.Total, Page and Pages carried omitempty, so an empty result set came back as {"page":1,"page_size":20} with no total at all. Zero is an answer: every client reading meta.total got undefined, which renders as a blank stat card rather than a nought and turns arithmetic into NaN. It is the reason an empty resource showed a dash where a 0 belonged.

Seven fixes found by building an app with the customisation feature instead of reading it.

The three releases before this one shipped a way to replace a resource's table, form, empty state or whole page from a resources/<name>.custom.tsx file. Everything compiled and every test passed. Then we built a small admin with it: a product list with custom cells, a deal pipeline as a kanban board, an enquiry inbox with its own list and composer, and found this.

Tailwind never looked at your overlay. The admin's content globs covered app/, components/ and lib/, not resources/, which is the one directory the feature invites you to write markup in. Every class in an overlay was dropped from the stylesheet. The component was right, the DOM was right, and the screen showed a white status pill on a white background. Nothing but a browser could have caught it. Fixed in the scaffold and in grit upgrade.

You could not wrap the component you were replacing. The docs said a slot receives the stock component's own props, so (props) => <Card><DataTable {...props} /></Card> would work. It did not: DataTable and the form components took Record<string, unknown> while a typed overlay hands them Product, which has no index signature. DataTable, FormSheet, FormModal and FormModalSteps are generic over the row now, so wrapping works and so does passing controller.form.item to the stock form from inside a custom page.

grit upgrade was updating 31 files nothing imported. Its path list still used the PascalCase component names from before the kebab-case rename, so every upgrade wrote components/tables/DataTable.tsx next to the real data-table.tsx and left it there. The symptom was the opposite of an error: it reported dozens of files updated while the components your app actually renders were never touched, meaning no component fix shipped in an upgrade had arrived since the rename. Paths corrected, the duplicates are cleaned up on the next upgrade, and form-sheet, form-modal-steps, update-groups, resource-detail-page and use-resource-controller are now refreshed too.

grit generate resource Ticket deleted the support desk. It overwrote internal/models/ticket.go, taking TicketReply with it, reported success, and the build then failed with an undefined symbol in a different file. Thirty-odd built-in model names are reserved now, with an error that says which feature owns the name and suggests one that is free. --force is there if you mean it. A test scaffolds a project and compares the list against what is actually emitted, so a new built-in model cannot quietly go unprotected.

grit remove resource left the overlay behind. It imports a type the shared package no longer exports, so removing a resource stopped the admin from type-checking. An untouched stub is deleted; one you have written in is renamed to .custom.tsx.bak, which keeps it out of the TypeScript build without throwing your work away.

--faker seeded choice fields with dictionary words. A status:select:active|draft|archived column came back full of "moreover" and "ouch": values the form's own dropdown cannot offer, the API's validation would reject, and the generated TypeScript union says are impossible. Choice fields are now seeded from their own options.

The admin ships type-clean. The scaffold was writing an i18n layer: language-switcher.tsx, i18n/request.ts and four more files, without the next-intl dependency that makes them compile, so every new Next.js admin started life with three type errors. Worse, grit add i18n skips files that already exist, so the broken copies blocked the command that would have fixed them. They are gone from the scaffold and pruned on upgrade when next-intl is absent. A fresh admin now reports zero errors from tsc --noEmit.

Typed rows in resource customisations.

A cell renderer used to receive Record<string, unknown>, so every custom cell started with a cast and a renamed column failed at runtime in front of whoever opened the page. The customisation surface is now generic over the row, and the generated overlay wires it up for you:

import type { ResourceCustomisation } from "@/lib/resource";
import type { Product } from "@repo/shared/types";

const custom: ResourceCustomisation<Product> = {
  columns: {
    // row is a Product — price is a number, so toFixed exists
    price: { cell: (row) => <b>{"$" + row.price.toFixed(2)}</b> },
  },
};

export default custom;

Write row.prise instead and TypeScript stops you with Property 'prise' does not exist on type 'Product'. Did you mean 'price'? — which is the entire point of the change.

The row type comes from @repo/shared/types, the same interfaces grit sync already generates from your Go structs, so there is no second definition to keep in step. ColumnDefinition, ColumnClick, ResourceTableProps and ResourceComponents are all generic now; the registry stays untyped so it can still hold every resource in one array.

Existing projects are migrated for you. grit sync creates the overlay for any resource that predates it and threads the import into the definition, skipping anything already wired. Both operations are guarded, so running it twice does nothing the second time.

One bug fixed on the way: grit update refreshes resources/users.ts, which now imports its overlay — so an upgrade would have left the admin importing a file that did not exist. The upgrade creates it when missing and never overwrites one that is already there.

Custom tables, forms and pages, registered once and safe from the generator.

A resource has always been able to declare a custom cell renderer. Almost nobody could use it. resources/products.ts is a .ts file, so JSX will not compile in it, and grit generate rewrites that file whole — so anything you did put there was one command away from being deleted.

Resources are now two files. The generator owns one and never touches the other:

apps/admin/resources/
  products.ts          # generated — rewritten on every grit generate
  products.custom.tsx  # yours — created once, never touched again

The custom half holds components, and defineResource merges the two:

import type { ResourceCustomisation } from "@/lib/resource";

const custom: ResourceCustomisation = {
  columns: {
    status: { cell: (row) => <StatusPill value={String(row.status)} /> },
  },
  components: {
    Table: (props) => <TemplateTable rows={props.data} onSort={props.onSort} />,
  },
};

export default custom;

There are four slots — Table, Form, EmptyState and Page — and each receives exactly the props of the component it replaces. Because Table takes DataTable's own props, a replacement is a drop-in and you can also wrap the original rather than reimplement it: (props) => <Card><DataTable {...props} /></Card>. A Page slot replaces the whole list view and can call useResourceController for the data and behaviour.

Columns and fields are patched by key rather than replaced wholesale, which is what lets grit sync keep adding columns as the Go model grows without discarding your renderers.

Verified the way it needs to be: customise an overlay, regenerate the same resource with an extra field, and the config half picks up the new column while the custom half is left exactly as it was. Nothing changes for existing projects — a resource with no overlay behaves as it always did.

useResourceController() — the admin list page, minus the markup.

If you have bought an admin template and want to port its pages into Grit, the data was never the hard part. useResource, useCreateResource and friends have always been plain hooks that take an endpoint. The hard part was everything else the list page does: keeping search, sort, page and filters in the address bar so a refresh or a shared link rehydrates the same view; row selection; bulk delete behind a confirm; toasts; cache invalidation; and stat cards that follow the active date range instead of contradicting the table underneath them.

All of that lived inside ResourcePage, welded to Grit's DataTable. Swapping in your own table meant rebuilding it. Now it is a hook:

"use client";

import { useResourceController } from "@/hooks/use-resource-controller";
import { productsResource } from "@/resources/products";

export default function ProductsPage() {
  const c = useResourceController(productsResource);

  return (
    <TemplateShell title={c.pluralName} onAdd={c.create}>
      <TemplateTable
        rows={c.rows}
        columns={c.columns}
        loading={c.isLoading}
        sortKey={c.sortBy}
        sortDir={c.sortOrder}
        onSort={c.setSort}
        selected={c.selection}
        onSelect={c.setSelection}
        onRowClick={c.edit}
      />
      <TemplatePager
        page={c.page}
        pages={c.totalPages}
        total={c.total}
        onChange={c.setPage}
      />
    </TemplateShell>
  );
}

The controller hands back the data (rows, meta, isLoading), the query state and its setters — where setSort toggles direction and every setter that changes the query resets to page one — plus selection, visible columns, the create/edit/view/delete actions, dialog state for anyone rendering their own modals, and the same apiSearchParams the table queried with, so an export matches what is on screen.

Nothing changes for existing projects. ResourcePage was rewritten to consume the hook and render only markup, which is the point: if the stock page could not be rebuilt on the controller, the controller would be missing something. Every resource page keeps behaving exactly as it did.

Also fixed while in here: the Vite admin's next/navigation shim declared router.replace(to) with one parameter, so the { scroll: false } that Next.js callers pass was a type error in the TanStack admin and compiled fine in the Next.js one. The shim now accepts and ignores the options bag.

Grit UI blocks can now declare the shadcn primitives they use, and grit ui add tells you about them.

Every block in the registry so far has been self-contained markup: install it and it renders, with nothing else to add. That works for a hero section. It does not work for a login form, where the thing worth having is the field wiring — a label tied to its input, an error tied to it by aria-describedby, and aria-invalid that actually flips. Hand-rolling that per block is how you end up with forms that look right and report nothing.

So blocks can now declare registryDependencies, and the registry serves them. Installing one pulls its primitives in:

$ grit ui add application-ui-authentication-sign-in-card-with-oauth

  ✓ Sign in card with OAuth  components/grit-ui/authentication/sign-in-card-with-oauth.tsx

  Requires: @hookform/resolvers, react-hook-form, zod
  Install with: pnpm add @hookform/resolvers react-hook-form zod

  Uses shadcn primitives: button, form, input
  Add any you do not have: npx shadcn@latest add button form input

The primitives are named rather than installed, the same way npm packages already were: your package manager and workspace layout are your call. But naming them matters more here than it does for npm packages, because the failure mode is worse. A block that imports components/ui/button does not fail at install — it fails at your next build, in a file you did not write. That is the difference between a one-line fix and half an hour reading a module-not-found trace.

Marketing blocks are unchanged and stay dependency-free. A hero that drags four Radix packages into a project to render a heading and a link is a bad trade.

A generated write was sending seven statements to Postgres. It now sends one.

Turning on Postgres statement logging during a benchmark run showed what a single POST /products actually cost:

begin
INSERT INTO "products" (...)
commit
SELECT * FROM "products" WHERE id = $1
begin
INSERT INTO "user_activities" (...)
commit

Three separate problems, all fixed.

An audit row was written for requests with no authenticated user. The CRUD helpers record who changed what. With no actor there is no who, so the row answers nothing, and on a public endpoint every anonymous write became two inserts in two transactions, which is write amplification an attacker controls for free. LogCreate, LogUpdate and LogDelete now return early without an actor. Auth events are deliberately unchanged, because LogLoginFailed records an empty actor on purpose.

The handler re-read the row it had just written. That SELECT existed to pick up columns the database fills in. The generator now emits Clauses(clause.Returning{}), so the INSERT brings them back itself. Resources with relations keep the re-read, because RETURNING cannot populate a preloaded association.

GORM wrapped a single INSERT in a transaction. One statement is already atomic in Postgres, so BEGIN and COMMIT bought a guarantee that was already held and cost two round trips for it. Where the generator can see there are no children, no join rows and no sequence hook writing alongside, it now emits the write with SkipDefaultTransaction for that call only.

That last one is decided per resource, from the definition. The global DB_SKIP_DEFAULT_TRANSACTION stays off, because it cannot know whether your model has children and a half-written invoice is worse than a slow one.

GORM now caches prepared statements, and the implicit write transaction is finally something you can turn off.

Found by benchmarking Grit against Express: Express was winning on inserts, and the reason was not the framework. Every GORM write was BEGIN + INSERT + COMMIT — three round trips where one would do — with the statement re-planned by Postgres each time.

The Bun pair was re-run afterwards to measure it rather than assert it. Inserts went from 1,568 to 2,686 req/s on the same hardware, closing most of the gap to Bun without touching the default that keeps multi-row writes safe.

• PrepareStmt is on by default. A query that runs a thousand times is planned once per connection instead of a thousand times. Disable with DB_PREPARED_STATEMENTS=false if you run pgbouncer in transaction mode, where server-side prepared statements do not survive.
• DB_SKIP_DEFAULT_TRANSACTION=true drops GORM's implicit transaction around single writes — worth roughly a third of write throughput.

That second one is off by default, and that is deliberate. The resource generator emits models with relations, and saving a parent with children is several INSERTs. Without the wrapping transaction, a failure halfway leaves an invoice holding some of its line items and no error anyone notices until the numbers stop adding up. It would have made the benchmark look better; it is not worth that.

The full comparison — Grit against Bun, Encore.ts and Express, every framework on its own ORM, with the harness and raw results — is at /docs/benchmarks.

You can now actually run without Redis.

Setting REDIS_URL= in .env looked like it should disable Redis and silently did not. getEnv treats an empty value as unset and hands back the default, so the asynq worker and the cron scheduler started anyway, failed to dial, and retried in a tight loop — a process burning CPU on reconnects with nothing in the logs but a wall of dial errors. On a machine with no Redis, simply running the API cost real cycles.

The three cases are now distinguished properly:

• REDIS_URL unset — the local default, which is what most dev setups want
• REDIS_URL= — no Redis. Cache, background jobs, worker and cron all stay off, and the app says so once at boot rather than leaving you to wonder why your jobs never run.
• REDIS_URL=redis://… — use it

Found while benchmarking, where the retry storm was polluting the measurements. Verified on a scaffolded project: with REDIS_URL= the log contains zero dial errors and the API serves normally.

A connection-pool default was costing 3.4x on read throughput. Found by benchmarking, fixed here.

The scaffold shipped SetMaxIdleConns(10) next to SetMaxOpenConns(100). Past ten concurrent requests, every connection handed back to a full idle pool is closed — and the next request makes Postgres fork a fresh backend. Under load that is a connection storm, and it surfaces as database CPU, which is the last place you would look for an application bug.

Measured with k6 at 50 concurrent users, 4 CPUs per container, on a single-row read:

• idle=10 — ~810 req/s, Postgres pinned near 840% CPU while the API used 196%
• idle=100 — ~2,720 req/s, both containers around 300%
• Writes went from ~690 to ~1,310 req/s on the same change

Idle now defaults to Open, and both are tunable via DB_MAX_OPEN_CONNS and DB_MAX_IDLE_CONNS. Tunable rather than hard-coded because it is not a free win everywhere: on a query heavy enough to saturate the database — an unindexed COUNT over a large table on every request — a smaller pool acts as admission control and measured about 20% faster, since queueing in the app is cheaper than thrashing in Postgres. The default suits the common case; the knob is there for the other one.

Every endpoint at /docs now shows what it returns.

Most built-in operations rendered “No Body” — you could see the URL and nothing else. Measured against a live spec from a scaffolded project: 134 of 134 operations now carry a response schema, up from 29. Request bodies cover 117 of 134.

• The other 17 are right as they stand. Fourteen are bodyless action POSTs (logout, revoke-all, retry, unlock, close, reopen…), POST /uploads is multipart rather than JSON, POST /webhooks/:provider takes whatever the third party sends, and the SAML callback is form-encoded.
• Sixteen handlers that bound var req struct{…} inline now bind named exported types. gindocs reflects over a type, and routes.go is a different package — an anonymous or unexported struct gives it nothing to read. Sixteen already-named types were exported for the same reason.

Also fixed: a new project's own tests failed. newTestDB migrated only models.User, so registering could not write its session or activity row — and the duplicate-email case surfaced as a 500 instead of a 409. go test ./... is now green across all ten packages of a freshly scaffolded API.

Turn on two-factor from your phone or the desktop app, not just the admin panel.

v3.125.0 taught both clients to answer a 2FA challenge. Enrolling still meant opening the admin panel, which is an odd thing to require of someone holding the phone the authenticator lives on. Both clients now do the whole thing: setup, QR, verify, backup codes, regenerate and disable.

• Expo: a new two-factor screen, reached from Settings → Security.
• Desktop: a section on the profile page, between Password and Delete account.
• No QR encoder ships in either bundle. The API returns the QR as a PNG data URI, which <img> and React Native <Image> both render directly.
• Backup codes are shown once and the panel will not close until they are saved. On mobile that is Share rather than the clipboard — it is the affordance a phone actually has for getting text into a password manager, and it avoids adding expo-clipboard for one screen.

Also fixed: Expo apps crashed on the web target. expo-secure-store is the iOS keychain and the Android keystore, neither of which a browser has, so pnpm web died on the first render with getValueWithKeyAsync is not a function. A new lib/secure-store.ts wraps it: unchanged on native, localStorage on web. That is not equivalent storage, and the file says so — web is a preview and debugging target, and native builds keep real secure storage.

Verified by driving both running clients with live TOTP codes rather than by type-check alone.

grit swap input now restyles your forms, finishing what v3.127.0 started for buttons.

Forty form fields across thirteen files route their classes through inputClasses(). Swap in soft-filled and every field in a modal changes together, instead of one or two while the rest keep the old border.

• Field surfaces unify. Some inputs were on bg-bg-elevated, some on bg-bg-secondary, some on bg-bg-tertiary — accidents, not decisions. The slot owns the surface now, so the whole form matches.
• Checkboxes and radios deliberately stay out. The slot sets w-full, which is right for a text field and wrong for a 16px box. Fields carrying an explicit width stay out for the same reason — two width utilities would fight, and which one wins depends on Tailwind's internal ordering rather than the order you wrote them.
• The table's page-size <select> stays out too. It is toolbar chrome, not a form field, and w-full would stretch it across the row.
• The confirm-to-delete field now uses the slot's own invalid state rather than carrying focus:border-danger alongside the slot's focus:border-accent.

The import test from v3.127.0 now covers both slots, and a second budget test pins the count of hand-styled fields so it can only go down.

grit swap button now restyles the admin, not two stray components.

The button slot has shipped for a while, but almost nothing called it — admin pages hand-wrote bg-accent px-4 py-2 rounded-lg instead. So swapping in a variant changed two files and left every real page untouched. Forty-six call sites across the admin now route their classes through buttonClasses(), taking slot reach from 2 to 23 emitted files.

• Only the class string changed. The element, its handlers, spinner logic and children are untouched — buttonClasses() is exported by the slot for exactly this, and it is what keeps links and labels that look like buttons on the same style after a swap.
• Sizes are inferred from height, never width. A button that changes height shifts the row it sits in; a few pixels of horizontal padding go unnoticed.
• Themed auth pages deliberately do not follow the slot. They style buttons with var(--auth-primary) so atlas, aurora and pulse can restyle them — routing those through the slot would fight the theme system.
• Two new tests guard it. One catches a page that calls buttonClasses() without importing it, and the reverse — an import with no call, which is how a template file with several pages in it puts the import in the wrong one. The other pins the remaining inline count so it can only go down.

Verified visually rather than by type-check alone: under grit swap button glow-ring, the “New role” button on /system/roles goes from rounded-lg to a pill with no layout shift, on a page that had nothing to do with the slot before.