Summary
While diagnosing a production 500 caused by a >1 MB JSON file (PR #3), I hit three documentation gaps that turned what should have been a quick fix into an extended investigation. None of these are about features that don't exist — they're about features and constraints that exist but aren't documented.
Gaps
1. GitHub storage limits are nowhere in the docs
The GitHub Contents API only inlines the content field for files ≤ 1 MB. Above that it returns encoding: "none" and an empty content, which until PR #3 caused a misleading `GitHub response is not a single file with content.` error. Even with the Blobs API fallback merged, the 100 MB hard ceiling, write amplification, concurrency behavior, and "when to move off single-file array storage" are not discussed.
A user picking the `array` kind for an editorial list has no way to know that it doesn't scale to thousands of rows or megabytes of content. The first signal is a production outage.
Proposed: `docs/storage-limits.md` with a sizing table by row size, write-amplification explanation, and decision rules for moving off `array` mode.
2. No serverless / Cloudflare Pages deploy guide
On Cloudflare Pages, secrets are not on `process.env` at boot — they arrive per request on `event.context.cloudflare.env`. Worse, `useRuntimeConfig()` is deep-frozen in some serverless builds, so the obvious workaround ("mutate runtimeConfig in middleware") throws.
There is a working pattern: inject the token into the JSON resource registry from middleware, because `storage.token` is checked before `runtimeConfig` in the storage factory. But nothing in the docs tells you this. Every Cloudflare deployer will reinvent it.
Proposed: `docs/deploying-cloudflare-pages.md` documenting the failure mode and the per-request token-injection middleware pattern.
3. No error reference for the storage layer
Errors like `GitHub response is not a single file with content.` give no actionable signal. Diagnosis requires reading `server/utils/githubContents.ts` and `server/utils/jsonStorage/*` directly. Even after diagnosis it's not obvious which errors are transient (retry) vs. permanent (fix config) vs. user error (fix file).
Proposed: `docs/error-reference.md` listing every `createError` in the storage adapters with status, exact message, cause, and remediation.
Out of scope (flagged for follow-up)
These were also raised in an external audit but I haven't verified them carefully and they need separate work:
- No full `nuxt.config.ts` reference. The README and `json-admin.md` cover the most-used keys but no single page is exhaustive.
- No end-to-end auth integration guide. `autoadmin-roles.md` covers roles but not how to plug in your auth source.
- S3/object storage prose is minimal (env vars only, no setup walkthrough).
- No database setup/migration guide beyond mentioning `NUXT_DATABASE_URL`.
I'm opening a PR that addresses the three gaps tied directly to PR #3 (storage limits, Cloudflare deploy, error reference). Happy to take on the others in follow-ups if you're interested.
Audit notes
An external code audit also claimed `docs/json-admin.md`, `docs/autoadmin-roles.md`, and `docs/development.md` were truncated mid-sentence. I verified all three against the actual repo source — they are not truncated. Each ends cleanly. Flagging here in case the audit reaches you through other channels.
Summary
While diagnosing a production 500 caused by a >1 MB JSON file (PR #3), I hit three documentation gaps that turned what should have been a quick fix into an extended investigation. None of these are about features that don't exist — they're about features and constraints that exist but aren't documented.
Gaps
1. GitHub storage limits are nowhere in the docs
The GitHub Contents API only inlines the
contentfield for files ≤ 1 MB. Above that it returnsencoding: "none"and an emptycontent, which until PR #3 caused a misleading `GitHub response is not a single file with content.` error. Even with the Blobs API fallback merged, the 100 MB hard ceiling, write amplification, concurrency behavior, and "when to move off single-file array storage" are not discussed.A user picking the `array` kind for an editorial list has no way to know that it doesn't scale to thousands of rows or megabytes of content. The first signal is a production outage.
Proposed: `docs/storage-limits.md` with a sizing table by row size, write-amplification explanation, and decision rules for moving off `array` mode.
2. No serverless / Cloudflare Pages deploy guide
On Cloudflare Pages, secrets are not on `process.env` at boot — they arrive per request on `event.context.cloudflare.env`. Worse, `useRuntimeConfig()` is deep-frozen in some serverless builds, so the obvious workaround ("mutate runtimeConfig in middleware") throws.
There is a working pattern: inject the token into the JSON resource registry from middleware, because `storage.token` is checked before `runtimeConfig` in the storage factory. But nothing in the docs tells you this. Every Cloudflare deployer will reinvent it.
Proposed: `docs/deploying-cloudflare-pages.md` documenting the failure mode and the per-request token-injection middleware pattern.
3. No error reference for the storage layer
Errors like `GitHub response is not a single file with content.` give no actionable signal. Diagnosis requires reading `server/utils/githubContents.ts` and `server/utils/jsonStorage/*` directly. Even after diagnosis it's not obvious which errors are transient (retry) vs. permanent (fix config) vs. user error (fix file).
Proposed: `docs/error-reference.md` listing every `createError` in the storage adapters with status, exact message, cause, and remediation.
Out of scope (flagged for follow-up)
These were also raised in an external audit but I haven't verified them carefully and they need separate work:
I'm opening a PR that addresses the three gaps tied directly to PR #3 (storage limits, Cloudflare deploy, error reference). Happy to take on the others in follow-ups if you're interested.
Audit notes
An external code audit also claimed `docs/json-admin.md`, `docs/autoadmin-roles.md`, and `docs/development.md` were truncated mid-sentence. I verified all three against the actual repo source — they are not truncated. Each ends cleanly. Flagging here in case the audit reaches you through other channels.