Why
Maintainer-directed audit. We have never measured what actually happens to a
stranger who lands on ObjectStack for the first time and tries to follow the
path the README advertises, end to end, with no monorepo knowledge to fall back
on. Every gate we own tests the framework; none of them tests the onboarding
journey as a whole. The value of this card is the friction log, not a fix.
Deliverable
This is an audit card. pr: null is the expected terminal shape. Do not fix
anything you find — fixes get triaged into their own lanes as separate cards.
Deliver:
- Findings issues — one per distinct defect/friction point, filed
unassigned, labelled finding, in the repo where the fix would land
(objectstack-ai/objectstack, objectui, cloud, or objectos), each with
a back-link to this issue. Dedupe-search before each one (keyword, error
string, package name). - A walkthrough report posted as a comment on this issue — the stage-by-stage
friction log described below. - Incremental progress comments — post the log for each stage on this issue
as you finish that stage, not batched at the end. If the run dies at stage
3, stages 1–2 must already be on GitHub.
The two-hats discipline (this is the card)
The entire worth of this exercise is fresh eyes. Mixing the hats destroys it.
Newcomer hat — while walking a stage. You may consult only what a stranger
can reach: the README as rendered on GitHub, the docs site, published npm
packages, and whatever files the scaffolder writes into the generated project.
You may not read this monorepo's source, tests, or internal docs to unblock
yourself. When you get stuck, being stuck IS the result — record it before
doing anything else.
Auditor hat — after the friction is logged. Once a friction point is written
down verbatim, you may read monorepo source to root-cause it, name the landing
package, and decide the repo/lane for the finding. Then put the newcomer hat
back on and continue from where you were.
Work in a scratch directory outside this monorepo (e.g. /tmp/os-newcomer/)
so no workspace resolution, no local linking, and no warm build cache can rescue
you. Install from the public registry, as a stranger would.
For every friction point record, verbatim: what I expected · what
happened (exact command and exact output) · how long I was blocked ·
could a newcomer have self-unblocked, and from which sentence of which doc.
That last field is the one that turns a complaint into a fixable card.
The four stages
Stage 1 — Read the README, cold
Land on the repo README as a stranger. Read it as an evaluator, not an
implementer: do I understand what this is, who it's for, and what my first
command is? Then check every claim the README makes that is cheap to check —
the counts, the file paths, the commands, the links. Note anything that is
stale, unverifiable, or that a newcomer would read one way and the code means
another. Note also what is missing at the point you first wanted it
(prerequisites, node version, what os even is, where auth comes from).
Stage 2 — Learn to create an app
Follow the documented path to a running application. Use the docs site and the
README, in the order a newcomer would hit them. Scaffold a project from the
published package, install, boot it, and open the Console in a browser
(Chromium + Playwright are available; drive the real UI, do not assert from
curl alone). Record every prompt, warning, error, and dead end between "I
decided to try this" and "I am looking at my own running app". Note the wall
clock for that whole span — time-to-first-running-app is the headline number
this card produces.
Stage 3 — Build a business app with the AI skills bundle
This is the stage the product's whole pitch rests on. The scaffolder is supposed
to install the skills bundle and write an AGENTS.md so a coding agent starts
with the protocol's rules loaded. Verify that actually happened, then use it:
pick a realistic business app that is not one of our bundled examples and
not a support desk (the README already walks that one) — choose something with
genuine modelling pressure, e.g. an equipment-maintenance tracker, a grant
application review workflow, or a supplier-onboarding pipeline. Then, driving
only the skills and AGENTS.md that the scaffolder placed in the project,
build it: objects and fields with real relations, a permission posture, at least
one automation/flow, at least one action with a visibility condition, and a
list/board view plus a nav entry.
Judge specifically:
- Did the skills actually load and steer the work, or did generic priors take over?
- When the agent wrote something wrong, did a gate catch it, and was the
error message located and corrective enough to self-fix — or did it need
knowledge only this monorepo has? - Which parts of the vocabulary (permissions, flows, actions, views, i18n) were
discoverable from the skills alone, and which required guessing? - Count the correction rounds to a clean build. That number is the second
headline this card produces.
Stage 4 — Validate and verify
Run the project's own validation and test path as documented, then verify in the
browser that what you modelled is what actually renders and enforces: the object
is there, the view lists records, the action's visibility condition really
hides it, and the permission posture really denies what it claims to deny. Test
the generated REST surface, and the MCP surface if the docs claim it is on by
default. Distinguish sharply between "the gate passed" and "the behaviour
is correct" — a green gate that did not exercise the risk is itself a finding.
Report shape
Post the final report as a comment on this issue with: the two headline numbers
(time-to-first-running-app; correction rounds to a clean business app), a
stage-by-stage friction table, the list of findings filed with their numbers and
target repos, and a short "where a newcomer most likely gives up" section
ranking the friction by how many strangers it would lose. Rank by severity to a
newcomer, not by how easy it is for us to fix.
Prose in this issue and in every finding is English. Do not open a PR.
Why
Maintainer-directed audit. We have never measured what actually happens to a
stranger who lands on ObjectStack for the first time and tries to follow the
path the README advertises, end to end, with no monorepo knowledge to fall back
on. Every gate we own tests the framework; none of them tests the onboarding
journey as a whole. The value of this card is the friction log, not a fix.
Deliverable
This is an audit card.
pr: nullis the expected terminal shape. Do not fixanything you find — fixes get triaged into their own lanes as separate cards.
Deliver:
unassigned, labelled
finding, in the repo where the fix would land(
objectstack-ai/objectstack,objectui,cloud, orobjectos), each witha back-link to this issue. Dedupe-search before each one (keyword, error
string, package name).
friction log described below.
as you finish that stage, not batched at the end. If the run dies at stage
3, stages 1–2 must already be on GitHub.
The two-hats discipline (this is the card)
The entire worth of this exercise is fresh eyes. Mixing the hats destroys it.
Newcomer hat — while walking a stage. You may consult only what a stranger
can reach: the README as rendered on GitHub, the docs site, published npm
packages, and whatever files the scaffolder writes into the generated project.
You may not read this monorepo's source, tests, or internal docs to unblock
yourself. When you get stuck, being stuck IS the result — record it before
doing anything else.
Auditor hat — after the friction is logged. Once a friction point is written
down verbatim, you may read monorepo source to root-cause it, name the landing
package, and decide the repo/lane for the finding. Then put the newcomer hat
back on and continue from where you were.
Work in a scratch directory outside this monorepo (e.g.
/tmp/os-newcomer/)so no workspace resolution, no local linking, and no warm build cache can rescue
you. Install from the public registry, as a stranger would.
For every friction point record, verbatim: what I expected · what
happened (exact command and exact output) · how long I was blocked ·
could a newcomer have self-unblocked, and from which sentence of which doc.
That last field is the one that turns a complaint into a fixable card.
The four stages
Stage 1 — Read the README, cold
Land on the repo README as a stranger. Read it as an evaluator, not an
implementer: do I understand what this is, who it's for, and what my first
command is? Then check every claim the README makes that is cheap to check —
the counts, the file paths, the commands, the links. Note anything that is
stale, unverifiable, or that a newcomer would read one way and the code means
another. Note also what is missing at the point you first wanted it
(prerequisites, node version, what
oseven is, where auth comes from).Stage 2 — Learn to create an app
Follow the documented path to a running application. Use the docs site and the
README, in the order a newcomer would hit them. Scaffold a project from the
published package, install, boot it, and open the Console in a browser
(Chromium + Playwright are available; drive the real UI, do not assert from
curl alone). Record every prompt, warning, error, and dead end between "I
decided to try this" and "I am looking at my own running app". Note the wall
clock for that whole span — time-to-first-running-app is the headline number
this card produces.
Stage 3 — Build a business app with the AI skills bundle
This is the stage the product's whole pitch rests on. The scaffolder is supposed
to install the skills bundle and write an
AGENTS.mdso a coding agent startswith the protocol's rules loaded. Verify that actually happened, then use it:
pick a realistic business app that is not one of our bundled examples and
not a support desk (the README already walks that one) — choose something with
genuine modelling pressure, e.g. an equipment-maintenance tracker, a grant
application review workflow, or a supplier-onboarding pipeline. Then, driving
only the skills and
AGENTS.mdthat the scaffolder placed in the project,build it: objects and fields with real relations, a permission posture, at least
one automation/flow, at least one action with a visibility condition, and a
list/board view plus a nav entry.
Judge specifically:
error message located and corrective enough to self-fix — or did it need
knowledge only this monorepo has?
discoverable from the skills alone, and which required guessing?
headline this card produces.
Stage 4 — Validate and verify
Run the project's own validation and test path as documented, then verify in the
browser that what you modelled is what actually renders and enforces: the object
is there, the view lists records, the action's visibility condition really
hides it, and the permission posture really denies what it claims to deny. Test
the generated REST surface, and the MCP surface if the docs claim it is on by
default. Distinguish sharply between "the gate passed" and "the behaviour
is correct" — a green gate that did not exercise the risk is itself a finding.
Report shape
Post the final report as a comment on this issue with: the two headline numbers
(time-to-first-running-app; correction rounds to a clean business app), a
stage-by-stage friction table, the list of findings filed with their numbers and
target repos, and a short "where a newcomer most likely gives up" section
ranking the friction by how many strangers it would lose. Rank by severity to a
newcomer, not by how easy it is for us to fix.
Prose in this issue and in every finding is English. Do not open a PR.