Repository navigation
Conversation
…h a completion check
There was a problem hiding this comment.
Devin Review found 3 potential issues.
1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)
| 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. |
There was a problem hiding this comment.
🔴 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.
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} . |
There was a problem hiding this comment.
🟡 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.
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. |
There was a problem hiding this comment.
🟡 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.
| - 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. |
Was this helpful? React with 👍 or 👎 to provide feedback.
ragnorc
left a comment
There was a problem hiding this comment.
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 runsomnigraph init --schema schema.pg graph.omni(:187) in the same directory. I followed these steps with the 0.15.0 CLI onsecond-brainand droppedHabitand its three edges:initrefuses: "graph already initialized or initialization metadata exists at '…/graph.omni'".--forcedoes not help, because a__manifestexists.- A new graph with the trimmed schema refuses the cookbook seed:
load --mode mergereturns "line 52: unknown node type 'Habit'". - The cookbook queries also break.
lint --schema schema.pggives 3 errors inqueries/projects.gqand 4 errors inqueries/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/andseed.jsonltogether. The trial graph holds only the cookbook's seed, so removegraph.omniand run step 5 again on the trimmed files. I also checked the in-place option:schema planandschema applyon the trial graph dropped the four types (4drop_typesteps). 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 exampleC=beadsand thencp -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) mentionv0.14.0only 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,initand 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.mdin the project … and … aCLAUDE.mdwhose 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 existingAGENTS.md, or create one. If aCLAUDE.mdexists, add the@AGENTS.mdline 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.mdthat 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
branchormutateflags 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.gqtext (the step 4 example is unchanged), so it does not increase that migration work.
Validation
- Exact head
9991fc06, merge base4f7c2076. I reviewed in a clean detached worktree. The PR changes only documentation. python3 scripts/check-docs.pywith the pinnedscripts/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 atModernRelay/omnigraph-cookbooks@c13bac1:- All 8 cookbook folders have
schema.pg,queries/,seed.jsonlandseed.md, so the copy command's file list is correct for every choice. omnigraph lint --schema schema.pg --query <file> --jsonfor every query file of all 8 cookbooks: 46 of 46 files have top-levelstatus: okand 0 errors.omnigraph initandomnigraph load --mode merge --jsonfor all 8 cookbooks: every load published a commit.- The step 8 template commands on
beads(a second cookbook, in addition to yoursecond-brainrun):schema show,branch create agent/try,mutate comment --branch agent/try(commit published),branch diff agent/try(2 changes), andbranch merge agent/try --into main --delete-branch(fast_forward, branch deleted). All succeeded. - B1 reproduction on
second-brain, withHabitand its three edges removed fromschema.pg: the results are in B1.
- All 8 cookbook folders have
- No
Decision neededcomments 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.mdand does not touch the reference-table row oronboarding.md.
ragnorc
left a comment
There was a problem hiding this comment.
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 loadsseed.jsonlinto./served. By step 9,./graph.omniis more than the seed: step 7 mergesmore.jsonlintomain(: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_claimreturned 2 rows on./graph.omniand 1 row on--target local --graph knowledge.The violated invariant: the served copy must hold the graph's current state.
seed.jsonlis 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.
Supportshas 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 twoload-test -> lower-latencyedges. When I loaded only the export, every edge id matched./graph.omni.Run the load after the server starts, through the
localtarget. Then the load does not take the cluster lock, so the secondforce-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, oneforce-unlock, server,target add, load the export throughlocal. The load published 5 entities. The server held the lock while it ran and released it when it stopped (lock_id: null). The--unauthenticatedserver with no policy bundle accepted the load. -
B3.
queries: queries.gqfails for a user who kept a cookbook. Line :324 always namesqueries.gq. A cookbook keeps its queries inqueries/(:110), and the completion check names both layouts (:283-284). Withsecond-braincopied as step 3b says,cluster applystops withquery_file_missing: "could not read query file './queries.gq'". Withqueries: queries/, the apply succeeds and the server lists the cookbook's stored queries. The fix is one sentence: usequeries: 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.omniin five commands. The served graph needs--target local --graph knowledgein 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.omnias the canonical store and treat./servedas a view. To refresh the view, deleteserved/and run the section again from a new export. Say that the switch is possible, and list its two costs:--graphon every command, and a server that must run.
Alignment with other open PRs
- #1360 makes a converged direct
cluster applyrelease its own lock. If it lands,cluster statusafter the apply showslock_id: null, and theforce-unlock <LOCK_ID>at :336 has no id to use. Write it as a condition, for example "iflock_idis 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.mddoes not describe how to serve a local graph, so this section is not a second copy of it.
Validation
- Exact head
fc23b220, merge base4f7c2076, reviewed in a clean detached worktree. Documentation only. python3 scripts/check-docs.pywith the pinnedscripts/requirements-docs.txt: "Documentation OK (529 Markdown files checked)".bash scripts/check-agents-md.sh: OK.git diff --check 9991fc06 fc23b220: clean.- Release binaries
omnigraphandomnigraph-server0.15.0 (omnigraph-linux-x86_64.tar.gz, checksum verified), with a separateOMNIGRAPH_HOME, so no real operator file changed:- Guide path (steps 4-7, then this section as written):
cluster applycomplete. The apply and the load each kept the lock, andforce-unlockreleased each one. The server was ready with 1 graph.target add localregistered the target. A stored query ran throughlocal,omnigraph studio --target local --graph knowledge --jsonprinted the link, andgraphs listreturned 403. All of this is as the section says. The result difference is in B2. - B2 fix (export loaded through
localon a new root): the results are in B2. - Cookbook path (
second-brainatModernRelay/omnigraph-cookbooks@c13bac1, 349 entities loaded intograph.omni): the results are in B3.
- Guide path (steps 4-7, then this section as written):
- Both installers include the server:
scripts/install.sh:93installsomnigraph-server, and the Homebrew formula installsomnigraphandomnigraph-server. So "the installer from step 1 already putomnigraph-serverbeside 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 neededcomments on this PR. Since9991fc06, 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.
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.mdit 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.mdsection, imported by a one-lineCLAUDE.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 acluster.yaml, applies a served copy in./served, loads the seed into it again, releases the lock each direct write keeps, startsomnigraph-server --unauthenticatedon loopback, registers it as an anonymous target and runsomnigraph studio --graph.With the 0.15.0 CLI I copied
second-brainfrom omnigraph-cookbooks main into a new directory as step 3b says: lint passed on all 8 query files,initand a merge load wrote 349 entities across 12 node types and 36 edge types, andclose_friendsreturned 4 rows. I then ran every command in the template on that graph:schema show,branch create,mutate add_task --branch,branch diffandbranch merge --delete-branch. The omnigraph.dev docs importer accepts the guide from this branch, and its served/onboarding.mdresolves 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, andomnigraph studioopened 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-intelandvc-os, whose READMEs list none, so a README change can leave one stale. The trial path was run only forsecond-brainon 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 addrewrites 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.