Recommended workflow for team collaboration with committed graphs?

[fakesmallcc]

Context

Using graphify on a team repo. Committed graph.json, graph.html, GRAPH_REPORT.md, manifest.json; gitignored cache/ and .graphify_*.

Problems

1. LLM non-determinism: different team members running /graphify . produce different graph.json — guaranteed merge conflicts.
2. manifest.json mtimes drift per clone since git doesn't preserve mtimes → --update always sees everything as changed → constant churn.
3. Cache not shared: cache/ gitignored, so each contributor re-runs full extraction even though Cache uses absolute paths in hash, making it non-portable across machines #311 made cache keys portable.

Questions

1. What's the intended team workflow — single-maintainer / CI, or multi-contributor regeneration?
2. Should cache/ be committed now that keys are portable?
3. Should manifest.json be gitignored (it's essentially local state)?
4. CI recommendation for keeping the graph fresh?

Happy to contribute docs based on the answer.

[FolatheDuckofDuckingburg]

Make a team repo

[safishamsi]

Good summary of the pain points. Here is the intended workflow and answers to each question.

Intended workflow: single source of truth, not multi-contributor regeneration.

The graph is a build artifact, not source. Treat it like a compiled binary: one person (or CI) regenerates it, everyone else consumes it.

1. LLM non-determinism -- this is by design. Running /graphify . twice on the same files will produce slightly different graphs because the LLM is non-deterministic. The fix is to designate one maintainer or a CI job as the sole graph publisher. Other contributors run /graphify --query against the committed graph; they do not regenerate it.

2. manifest.json mtime drift -- you are right that git does not preserve mtimes, so --update will re-process everything after a fresh clone. The mitigation is to gitignore manifest.json and treat it as local state. The cache (once committed) does the real deduplication -- if the file content hash matches, extraction is skipped regardless of mtime.

3. Cache sharing -- yes, committing cache/ is safe now that keys are content-addressed (Cache uses absolute paths in hash, making it non-portable across machines #311). It trades repo size for speed: contributors skip re-extraction for files that have not changed. Whether the tradeoff is worth it depends on how large your corpus is.

Recommended CI setup:

• Run /graphify . (or graphify --update) in CI on every merge to main
• Commit graph.json, graph.html, GRAPH_REPORT.md, and optionally cache/
• Gitignore manifest.json
• Contributors query the committed graph; they do not regenerate it locally unless they are the designated graph maintainer

Happy to add a "Team workflow" section to the docs if you want to draft one.

[yasheshcygbit]

Good summary of the pain points. Here is the intended workflow and answers to each question.

Intended workflow: single source of truth, not multi-contributor regeneration.

The graph is a build artifact, not source. Treat it like a compiled binary: one person (or CI) regenerates it, everyone else consumes it.

1. LLM non-determinism -- this is by design. Running /graphify . twice on the same files will produce slightly different graphs because the LLM is non-deterministic. The fix is to designate one maintainer or a CI job as the sole graph publisher. Other contributors run /graphify --query against the committed graph; they do not regenerate it.
2. manifest.json mtime drift -- you are right that git does not preserve mtimes, so --update will re-process everything after a fresh clone. The mitigation is to gitignore manifest.json and treat it as local state. The cache (once committed) does the real deduplication -- if the file content hash matches, extraction is skipped regardless of mtime.
3. Cache sharing -- yes, committing cache/ is safe now that keys are content-addressed (Cache uses absolute paths in hash, making it non-portable across machines #311). It trades repo size for speed: contributors skip re-extraction for files that have not changed. Whether the tradeoff is worth it depends on how large your corpus is.

Recommended CI setup:

• Run /graphify . (or graphify --update) in CI on every merge to main
• Commit graph.json, graph.html, GRAPH_REPORT.md, and optionally cache/
• Gitignore manifest.json
• Contributors query the committed graph; they do not regenerate it locally unless they are the designated graph maintainer

Happy to add a "Team workflow" section to the docs if you want to draft one.

I think this should also be available in README.md file. Right now there is no way of knowing what should be in .gitignore. It would give good visibility to everyone.

On a side note, although it is fine to commit cache files now, letting hooks run on commit will still work fine as it updates the graph on a local system of another team member with a cache already generated and available from someone else's system?