Skip to content

docs(skill): start onboarding from the user's use case and end it with a completion check - #1420

Open
ragnorc wants to merge 2 commits into
ModernRelay:mainfrom
ragnorc:docs/onboarding-done-check
Open

ragnorc wants to merge 2 commits into
ModernRelay:mainfrom
ragnorc:docs/onboarding-done-check

Conversation

@ragnorc

@ragnorc ragnorc commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

The onboarding guide asked every user the same question, what the graph should hold, so someone who came to see what Omnigraph can do had to invent a use case before they had seen one. It also never said when setup was complete, and the CLAUDE.md it left behind listed paths without telling later sessions to use the graph, so the next session answered from memory and the graph fell behind.

Step 3 now forks. A use case already stated in the request or the project is taken as given; otherwise the agent asks whether the user has one. With one, it asks what the graph holds, who writes it and two or three questions, which become step 4's queries. Without one, it shows the eight cookbooks, each with what it holds and a question it answers, and offers to copy one's schema, queries and seed into a local graph to try before designing. Step 2 has the agent confirm it can see the exported skill and give an exact resume step if it must restart. Step 8 gives an AGENTS.md section, imported by a one-line CLAUDE.md, that makes the graph the canonical store: read the schema, query before answering, suggest recording new facts, write on a branch and merge only after the user approves. With consent, the same section can go in the user's global agent file. A completion check closes step 8. The guard is that every command in the template is one the guide has the agent run earlier. Next steps gain a Studio section: Studio opens only a served graph, so the agent declares a cluster.yaml, applies a served copy in ./served, loads the seed into it again, releases the lock each direct write keeps, starts omnigraph-server --unauthenticated on loopback, registers it as an anonymous target and runs omnigraph studio --graph.

With the 0.15.0 CLI I copied second-brain from omnigraph-cookbooks main into a new directory as step 3b says: lint passed on all 8 query files, init and a merge load wrote 349 entities across 12 node types and 36 edge types, and close_friends returned 4 rows. I then ran every command in the template on that graph: schema show, branch create, mutate add_task --branch, branch diff and branch merge --delete-branch. The omnigraph.dev docs importer accepts the guide from this branch, and its served /onboarding.md resolves every link. I ran the Studio section on the same graph with the 0.15.0 server: after the apply and the load each released its lock, the server reported one ready graph, a stored query ran through the anonymous target, and omnigraph studio opened Studio on the graph's main branch with its 16 people and every type's count. Without a cluster policy the server refuses to list graphs, which is why the step passes --graph.

For review: the sample questions in the cookbook table come from each README, paraphrased for company-brain, beads, industry-intel and vc-os, whose READMEs list none, so a README change can leave one stale. The trial path was run only for second-brain on 0.15.0; a cookbook pinned to another release may fail lint, which the guide tells the agent to report. The offer to edit the global agent file is the call most worth challenging, since it reaches beyond the project. In the Studio section, target add rewrites the operator file and drops its comments, which I saw on a real one, so the guide has the agent tell the user first; and the served copy is a second graph, which the guide says plainly but a user may still write to the wrong one.


Devin Review

@ragnorc
ragnorc requested a review from aaltshuler as a code owner November 16, 2026 01:33

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 3 potential issues.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

Devin Review

Comment on lines +115 to +117
questions like the one in the table. Afterwards ask whether to keep it as the
starting point, trimmed to what they need, or to start fresh in step 4 with
what they have learned. Either way, ask the 3a questions before step 4.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Fresh start blocked by trial graph

When a user starts fresh after a cookbook trial, init refuses the existing graph at ./graph.omni. Keeping and trimming the cookbook also leaves its new schema unapplied.

Learn more

The cookbook trial initializes graph.omni by following step 5. Step 4 then directs users to edit the same project's schema or start fresh, but init refuses an already initialized graph. Editing schema.pg alone also does not change the schema of that graph. Both choices therefore need an explicit transition before the guide repeats the create-and-load instructions.

Example: A user loads second-brain into my-graph/graph.omni, then chooses a fresh schema. The agent writes a new schema.pg and runs omnigraph init --schema schema.pg graph.omni; the CLI refuses because the trial graph still exists.

Recommended fix: Make the trial a separate directory or graph target. For a fresh start, create a new target; for a retained cookbook, explain whether to keep its existing schema or follow the supported schema plan/apply route before loading new data.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

```bash
mkdir my-graph && cd my-graph
git clone --depth 1 https://github.com/ModernRelay/omnigraph-cookbooks /tmp/omnigraph-cookbooks
cp -R /tmp/omnigraph-cookbooks/second-brain/{schema.pg,queries,seed.jsonl,seed.md} .

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Cookbook selection loads the wrong graph

When a user picks any cookbook except second-brain, cp still copies second-brain's files. The trial graph answers a different use case.

Learn more

The table presents eight different cookbook choices, but the copy command always selects second-brain. This makes the normal copy/paste route inconsistent with the user's selection; a non-second-brain selection builds an unrelated graph even if all commands succeed.

Example: The user picks beads to explore an agent work queue. Running the shown command copies second-brain/schema.pg and its notes and tasks instead of the beads files.

Recommended fix: Show a selection variable or a clear placeholder for the cookbook directory and use it in the copy command, while supplying second-brain only as an explicitly labeled example.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

- The exported skill is in a directory your agent loads skills from.
- `omnigraph lint --schema schema.pg --query <file>` passes for every query
file (`queries.gq`, or each file in a cookbook's `queries/`).
- Each query from step 4 returns rows from the graph.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Empty results block successful onboarding

When a valid question has no matching records, the completion check treats its zero-row result as failed setup. Users cannot finish onboarding without inventing data or changing their questions.

Suggested change
- Each query from step 4 returns rows from the graph.
- Each query from step 4 runs successfully against the graph; explain any valid empty results to the user.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

@ragnorc ragnorc left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review of #1420 at 9991fc06760d8f8083c6ec4467adeca55b577b52

Outcome: one blocking defect, with a small fix. The other findings are optional. The new step 3 is a clear improvement: users who have a use case are not shown a catalogue, and users who do not have one are not asked to invent one. The completion check and the canonical-store section close real gaps. But one of the two endings that step 3b offers, "keep it as the starting point, trimmed", fails at step 5 as written (B1).

Why, what, how, impact. Before this PR, the guide asked every user what the graph should hold, and it did not say when setup was complete. This PR changes only documentation: skills/omnigraph/references/onboarding.md (+126 -32), one row of the reference table in SKILL.md, and the changelog fragment. There is no code. The guide is embedded in the CLI through omnigraph-skill, so after release every agent that runs omnigraph skill show references/onboarding.md reads this text. The impact is on how well agents complete a setup, not on engine behavior.

Blocking

  • B1. A kept, trimmed cookbook cannot pass step 5. Step 3b loads the cookbook into graph.omni (:113-115). If the user keeps it, step 4 says "edit its files instead: drop the types their questions don't need" (:136-137). Then step 5 runs omnigraph init --schema schema.pg graph.omni (:187) in the same directory. I followed these steps with the 0.15.0 CLI on second-brain and dropped Habit and its three edges:

    • init refuses: "graph already initialized or initialization metadata exists at '…/graph.omni'". --force does not help, because a __manifest exists.
    • A new graph with the trimmed schema refuses the cookbook seed: load --mode merge returns "line 52: unknown node type 'Habit'".
    • The cookbook queries also break. lint --schema schema.pg gives 3 errors in queries/projects.gq and 4 errors in queries/mutations.gq.

    The violated invariant: a step that edits the schema must also say how the graph, the seed and the queries follow that edit. The guide says this nowhere. The completion check (:283) catches the broken queries, but only after step 5 has already failed. The fix is about two sentences at :115-117 or :136-137. When a user keeps a cookbook, trim schema.pg, queries/ and seed.jsonl together. The trial graph holds only the cookbook's seed, so remove graph.omni and run step 5 again on the trimmed files. I also checked the in-place option: schema plan and schema apply on the trial graph dropped the four types (4 drop_type steps). That option teaches schema migration during onboarding, so remove-and-recreate is the simpler path. The "start fresh" ending does not have this problem, because step 4 starts in a new project directory (:136). Devin's first finding is therefore correct only for the "keep" ending.

Optional

  • O1. The copy command always copies second-brain (:110), but the text says "copy the chosen one". An agent that copies commands exactly loads the wrong cookbook for the other seven choices. Use a variable, for example C=beads and then cp -R /tmp/omnigraph-cookbooks/$C/{…} ., or a <cookbook> placeholder. Devin found this too.
  • O2. "Each cookbook pins a CLI and server release, named at the top of its README" (:123-124) is not correct for the folder READMEs. The release is named only at the top of the cookbooks repository's root README ("Ready-to-run graph examples for OmniGraph 0.14.0", root README.md:3). Three folder READMEs (beads, dev-graph, industry-intel) mention v0.14.0 only in links far down the page. The other five mention no release. Main had "named at the top of their README", which could be read as the root README. The new singular "its README" sends the agent to the folder. Say "the cookbooks repository names its release at the top of its root README". Also, all 8 cookbooks lint, init and load on 0.15.0 (see Validation). The "borrow the schema and queries" advice at :127-129 therefore works today.
  • O3. Step 8 can overwrite a user's agent files. "Write AGENTS.md in the project … and … a CLAUDE.md whose only line is @AGENTS.md" (:238-239). Step 3 now also handles "the project you are in", which can be an existing repository. That repository can already have both files. Say: add the section to an existing AGENTS.md, or create one. If a CLAUDE.md exists, add the @AGENTS.md line and do not replace the file.
  • O4. "Each query from step 4 returns rows from the graph" (:285) can fail on a correct setup. Step 5 loads "a few real records". A correct question such as "what is overdue?" can return no rows. Then the agent cannot complete the setup unless it invents data. A smaller rule: each query runs without an error, and at least one returns rows. Tell the user about each empty result. Devin found this too.
  • O5. The cookbook table is a second copy of the cookbook descriptions. The cookbooks' root README already has a "Cookbook | Graph ID | Purpose" table (README.md:7-16). The new table adds the question column, and that column is the part users need. As you say in the PR description, four of the questions are paraphrases, so they can go stale. If you move the question column into the cookbooks README, the guide can link one owner. This is a cross-repository change and the cost of the copy is small, so it is optional.

The offer to edit the global agent file (:270-273) is acceptable as written. It asks first, it applies only to graphs that are a second brain or a company brain, and it uses an absolute --target. I do not raise it as a finding.

Tradeoffs and liability

  • Removed. A setup with no end state. A CLAUDE.md that listed paths but did not tell later sessions to use the graph. A first question that users without a use case could not answer.
  • Added. About 120 lines in an embedded skill file, which every onboarding agent reads. A list of eight cookbooks with a question for each, which must follow the cookbooks repository (O5). A template whose commands must stay valid for each CLI release. Your guard (each command in the template is one the guide runs earlier) is the correct owner, and I ran those commands on 0.15.0.
  • After five more changes of this kind. Each new cookbook adds a row in two repositories. Each CLI change to branch or mutate flags must update steps 7 and 8 together. The guard keeps this one check, not two. GQ 3 (#1302, #1316) will change query text. This PR adds no new .gq text (the step 4 example is unchanged), so it does not increase that migration work.

Validation

  • Exact head 9991fc06, merge base 4f7c2076. I reviewed in a clean detached worktree. The PR changes only documentation.
  • python3 scripts/check-docs.py with the pinned scripts/requirements-docs.txt: "Documentation OK (529 Markdown files checked)". bash scripts/check-agents-md.sh: OK. git diff --check 4f7c2076 9991fc06: clean.
  • CLI omnigraph 0.15.0, cookbooks at ModernRelay/omnigraph-cookbooks@c13bac1:
    • All 8 cookbook folders have schema.pg, queries/, seed.jsonl and seed.md, so the copy command's file list is correct for every choice.
    • omnigraph lint --schema schema.pg --query <file> --json for every query file of all 8 cookbooks: 46 of 46 files have top-level status: ok and 0 errors.
    • omnigraph init and omnigraph load --mode merge --json for all 8 cookbooks: every load published a commit.
    • The step 8 template commands on beads (a second cookbook, in addition to your second-brain run): schema show, branch create agent/try, mutate comment --branch agent/try (commit published), branch diff agent/try (2 changes), and branch merge agent/try --into main --delete-branch (fast_forward, branch deleted). All succeeded.
    • B1 reproduction on second-brain, with Habit and its three edges removed from schema.pg: the results are in B1.
  • No Decision needed comments on this PR. Before this review, the only review was Devin's (3 inline findings). B1, O1 and O4 check and refine them.
  • GQT regression rule: this PR changes no engine behavior, so no regression applies.
  • CI at the exact head 9991fc06: 28 passed, 4 skipped.
  • Other open PRs: #1422 changes another part of SKILL.md and does not touch the reference-table row or onboarding.md.

@ragnorc ragnorc left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review of the delta 9991fc0..fc23b22 on #1420

Outcome: two blocking defects in the new Studio section, each with a small fix. One finding is optional. The delta is one commit (fc23b220, "onboarding shows how to open the new graph in studio", +62 lines in skills/omnigraph/references/onboarding.md). It adds a Studio entry to step 9 and a new section, "See the graph in Studio" (:310-368). The section is the correct shape: Studio opens only a served graph, so the guide must create one. Most of its commands work as written on the 0.15.0 release. But the served copy does not contain the graph the user built (B2), and the first command fails for a user who kept a cookbook (B3).

The earlier review at 9991fc06 (B1 and O1-O5) still applies. This commit does not change those lines, so I do not repeat them here.

Why, what, how, impact. Before this commit, the guide ended with a local ./graph.omni and did not show the user how to look at it. This commit tells the agent how to serve a copy of the graph and open Studio on it: declare a cluster.yaml, apply it into ./served, load data, release the cluster lock, start omnigraph-server on loopback, register an anonymous target, and run omnigraph studio. It changes only documentation. The guide is embedded in the CLI, so after release every onboarding agent reads it.

Blocking

  • B2. The served copy is loaded from seed.jsonl, not from the graph. Line :337 loads seed.jsonl into ./served. By step 9, ./graph.omni is more than the seed: step 7 merges more.jsonl into main (:222-225), and the step 8 rules add every approved write. So Studio shows a different graph from the one the user queries, and nothing tells them. I followed steps 4-7 and then this section with the 0.15.0 release binaries. sources_for_claim returned 2 rows on ./graph.omni and 1 row on --target local --graph knowledge.

    The violated invariant: the served copy must hold the graph's current state. seed.jsonl is only the first input. The fix is to load an export of the graph instead of the seed:

    omnigraph export --target ./graph.omni > graph.jsonl
    omnigraph load --data graph.jsonl --mode merge --target local --graph knowledge

    Load the export instead of the seed, not after it. Supports has no @key, so the export gives the seed's edge a different id. When I loaded the export after the seed, the served graph had two load-test -> lower-latency edges. When I loaded only the export, every edge id matched ./graph.omni.

    Run the load after the server starts, through the local target. Then the load does not take the cluster lock, so the second force-unlock (:338) and its second <LOCK_ID> are no longer needed. One placeholder with two different values is easy for an agent to fill in wrong. I ran this order on a new root: cluster apply, one force-unlock, server, target add, load the export through local. The load published 5 entities. The server held the lock while it ran and released it when it stopped (lock_id: null). The --unauthenticated server with no policy bundle accepted the load.

  • B3. queries: queries.gq fails for a user who kept a cookbook. Line :324 always names queries.gq. A cookbook keeps its queries in queries/ (:110), and the completion check names both layouts (:283-284). With second-brain copied as step 3b says, cluster apply stops with query_file_missing: "could not read query file './queries.gq'". With queries: queries/, the apply succeeds and the server lists the cookbook's stored queries. The fix is one sentence: use queries: queries/ when the project kept a cookbook.

Optional

  • O6. Switching the agent file to the served copy needs more than a new --target (:364-366). The step 8 template uses --target ./graph.omni in five commands. The served graph needs --target local --graph knowledge in each one. It also needs a server that runs in every later session, but this section starts the server only as a background job. If the server is not running, the first query in the next session fails. A simpler default: keep ./graph.omni as the canonical store and treat ./served as a view. To refresh the view, delete served/ and run the section again from a new export. Say that the switch is possible, and list its two costs: --graph on every command, and a server that must run.

Alignment with other open PRs

  • #1360 makes a converged direct cluster apply release its own lock. If it lands, cluster status after the apply shows lock_id: null, and the force-unlock <LOCK_ID> at :336 has no id to use. Write it as a condition, for example "if lock_id is not null, release it". Then the text is correct whichever PR lands first. With B2's fix, this is the only lock step that remains.
  • #1343 (Studio on a managed cluster target) changes docs/user/cli/studio.md, but it does not change the rule that a local graph must be served first. The link at :367 stays valid.

Tradeoffs and liability

  • Removed. A setup with no way to see the graph. Studio's view of the schema, the tables and a branch's changes is a large help for a new user.
  • Added. About 60 lines in an embedded skill file. A second graph (./served) that can drift from ./graph.omni. The guide says this plainly, and O6 makes the default safer. Seven CLI commands that must stay valid for each release, among them the lock procedure, which #1360 already changes.
  • After five more changes of this kind. Each "next step" that needs a server would repeat the cluster, lock and target setup. If more steps need a served graph, one short "serve this graph" section that the others link to will cost less than copies. With one user today, the section as it is, with B2 and B3 fixed, is the correct size. docs/user/cli/studio.md does not describe how to serve a local graph, so this section is not a second copy of it.

Validation

  • Exact head fc23b220, merge base 4f7c2076, reviewed in a clean detached worktree. Documentation only.
  • python3 scripts/check-docs.py with the pinned scripts/requirements-docs.txt: "Documentation OK (529 Markdown files checked)". bash scripts/check-agents-md.sh: OK. git diff --check 9991fc06 fc23b220: clean.
  • Release binaries omnigraph and omnigraph-server 0.15.0 (omnigraph-linux-x86_64.tar.gz, checksum verified), with a separate OMNIGRAPH_HOME, so no real operator file changed:
    • Guide path (steps 4-7, then this section as written): cluster apply complete. The apply and the load each kept the lock, and force-unlock released each one. The server was ready with 1 graph. target add local registered the target. A stored query ran through local, omnigraph studio --target local --graph knowledge --json printed the link, and graphs list returned 403. All of this is as the section says. The result difference is in B2.
    • B2 fix (export loaded through local on a new root): the results are in B2.
    • Cookbook path (second-brain at ModernRelay/omnigraph-cookbooks@c13bac1, 349 entities loaded into graph.omni): the results are in B3.
  • Both installers include the server: scripts/install.sh:93 installs omnigraph-server, and the Homebrew formula installs omnigraph and omnigraph-server. So "the installer from step 1 already put omnigraph-server beside the CLI" (:313-314) is correct.
  • Not tested: the Studio desktop app itself. This Linux host has no Studio, so I checked the link and the server, not the app's view.
  • No Decision needed comments on this PR. Since 9991fc06, there are no new reviews or comments.
  • GQT regression rule: this commit changes no engine behavior, so no regression applies.
  • CI at the exact head fc23b220: 27 passed, 4 skipped.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant