From 33883118815a3e2c5e6046a7358ca3397a25709c Mon Sep 17 00:00:00 2001 From: nikhil2004 Date: Sat, 26 Sep 2026 04:40:37 +0530 Subject: [PATCH 1/4] docs: overhaul GitHub issue and pull request templates --- .github/ISSUE_TEMPLATE/bug_report.yml | 53 ++++++++++++++++++++-- .github/ISSUE_TEMPLATE/config.yml | 2 +- .github/ISSUE_TEMPLATE/feature_request.yml | 19 ++++++++ .github/PULL_REQUEST_TEMPLATE.md | 24 +++++++--- 4 files changed, 85 insertions(+), 13 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 01438c7f56..d95a5826d3 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -9,6 +9,14 @@ body: value: | Please search existing issues first. Include the smallest reproducible example you can. + - type: checkboxes + id: checks + attributes: + label: Pre-flight checks + options: + - label: I have checked the Troubleshooting section in the README + required: true + - type: textarea id: description attributes: @@ -39,14 +47,49 @@ body: id: version attributes: label: Graphify version - placeholder: "0.9.64" + placeholder: "e.g. 0.9.68" - - type: input + - type: dropdown + id: os + attributes: + label: Operating System + options: + - macOS + - Linux + - Windows + - WSL + validations: + required: true + + - type: dropdown + id: python + attributes: + label: Python Version + options: + - 3.10 + - 3.11 + - 3.12 + - 3.13 + validations: + required: true + + - type: dropdown + id: install_method + attributes: + label: Installation Method + options: + - uv tool install (recommended) + - pipx + - pip + - built from source (git clone) + validations: + required: true + + - type: textarea id: environment attributes: - label: Environment - description: Include operating system, Python version, and installation method. - placeholder: "macOS 15, Python 3.12, uv tool install" + label: Additional Environment Details + description: List any provider environment variables set (e.g., OPENAI_API_KEY) and whether a clean checkout reproduced the issue. - type: textarea id: additional diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index ac603f5520..b8e663c625 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -7,5 +7,5 @@ contact_links: url: https://github.com/Graphify-Labs/graphify/blob/v8/README.md about: Check the README and docs before opening an issue. - name: 🤝 Contributing guide - url: https://github.com/Graphify-Labs/graphify/blob/v8/README.md#development-setup + url: https://github.com/Graphify-Labs/graphify/blob/v8/CONTRIBUTING.md about: Read the development and contribution guidelines before opening a pull request. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 668a84a481..9f59a4d85e 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -47,6 +47,25 @@ body: validations: required: true + - type: dropdown + id: pr + attributes: + label: Are you willing to submit a PR? + options: + - Yes, I can work on this + - Yes, but I will need guidance + - No, I just wanted to request it + validations: + required: true + + - type: textarea + id: compatibility + attributes: + label: Compatibility / behavior impact + description: Does this affect node/edge IDs, cache semantics, graph.json schema, generated skills, MCP output, or incremental updates? + validations: + required: true + - type: textarea id: context attributes: diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 57e09327e6..df82394302 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,7 +2,6 @@ - ## Type of change - [ ] Bug fix @@ -12,9 +11,20 @@ - [ ] Refactor - [ ] Security fix +## Verification & Invariants + + + +- [ ] **Read** the [CONTRIBUTING.md](../CONTRIBUTING.md) guide. +- [ ] **Reproduced** the issue and identified the invariant. +- [ ] Made the **smallest fix** necessary. +- [ ] Added a **regression test** (if bug fix) or isolated boundary test. +- [ ] Kept the PR description **synchronized** with the final implementation. +- [ ] Documented any **limitations / unsupported cases** explicitly. + ## How was this tested? - + ```text @@ -22,8 +32,8 @@ ## Graphify-specific checklist -- [ ] I added or updated tests for behavior changes. -- [ ] I updated documentation or confirmed that no documentation is needed. -- [ ] I updated generated skill artifacts when changing their source fragments. -- [ ] I considered compatibility across supported Python versions. -- [ ] I confirmed that no API keys, generated graph data, or local-only files are included. +- [ ] I updated generated skill artifacts (`uv run python -m tools.skillgen --bless`) when changing their source fragments. +- [ ] I confirmed that AST/structural extraction remains deterministic (no ambient state dependencies like ENV variables). +- [ ] I reviewed changes for security implications (no unsafe interpolation into shell/Python). +- [ ] I confirmed no API keys or local-only graph data are included. +- [ ] (If applicable) I disclosed AI authorship in my commit messages. From c7fb7204290f9ce50b1a031b999b420a8a7f4418 Mon Sep 17 00:00:00 2001 From: nikhil2004 Date: Sat, 26 Sep 2026 04:40:37 +0530 Subject: [PATCH 2/4] docs: establish contributor guidelines and code of conduct --- CODE_OF_CONDUCT.md | 73 ++++++++++++++++++++++ CONTRIBUTING.md | 151 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 224 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000000..2f5bee0dbb --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,73 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, including the GitHub repository, Discord server, and any other channels managed by Graphify Labs. It also applies when an individual is officially representing the community in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers by directly messaging a Community Leader on the [Graphify Discord server](https://discord.gg/XDnKVpzdXB) or by emailing the maintainer directly if known. + +All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..e4a4fbb56a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,151 @@ +# Contributing to Graphify + +Graphify is a graph-building system whose correctness depends on preserving provenance, deterministic extraction, and safe incremental updates. A contribution is not complete because the new code works on the happy path; it is complete when the relevant invariant is explicit, tested, and preserved across rebuilds. + +## Before You Start +- Read [ARCHITECTURE.md](ARCHITECTURE.md) +- Read [SECURITY.md](SECURITY.md) when relevant +- Understand `v8` is the active development branch +- Use `graphify-out/GRAPH_REPORT.md` for repository orientation + +## What We Value + +1. **Preserve correctness, not merely successful execution**. A failed, partial, smaller, or differently keyed extraction must not overwrite valid persisted state or poison incremental caches. +2. **Preserve provenance; incidental richness is not evidence**. A real source-backed record must not lose to a richer sourceless stub. A location without a corresponding source file is not sufficient provenance. +3. **Keep deterministic extraction deterministic**. AST extraction, symbol identity, traversal order, merge behavior, and other structural passes must not depend on filesystem ordering, ambient environment state, network calls, or nondeterministic model output. +4. **Keep inference visibly separate from extracted fact**. Never turn uncertainty into false certainty just because a richer result looks better. Preserve the distinction between extracted fact, inference, and ambiguity. +5. **Prefer fail-closed behavior over guessed relationships**. +6. **Treat persistent graph/cache state as data that can be corrupted**. +7. **Make bug fixes prove the old failure with a regression test**. Demonstrate the old failure, not merely exercise the new code. +8. **Keep PRs narrow and reviewable**. Small, auditable diffs beat clever broad fixes. +9. **Document heuristic boundaries and unsupported cases**. +10. **Never hand-edit generated artifacts**. Edit the source fragment, run the generator, and run the corresponding verification checks. +11. **Do not let ambient environment state affect tests**. Tests must be deterministic with respect to the contributor's shell environment. +12. **Treat paths, source text, model output, URLs, and generated commands as untrusted**. Never construct shell commands or Python source by interpolating free text. +13. **Check cross-platform behavior when touching filesystem/process/install logic**. A change is not considered cross-platform-safe merely because it passes on Linux. +14. **Update documentation when behavior or invariants change**. Documentation is part of the behavior contract. +15. **Use Graphify itself to understand Graphify**, except when the graph is the thing being debugged. + +## Repository Architecture +- **Pipeline**: `detect()` → `extract()` → `build()` → `cluster()` → `analyze()` → `report.generate()` → `export.to_*()` +- **Where extractors live**: `graphify/extractors/` +- **Generated skills vs source fragments**: Skill files in `graphify/` are generated from fragments in `tools/skillgen/`. +- **What is generated and what is authoritative**: `tools/skillgen/fragments/` is authoritative. + +## Development Setup + +```bash +# Fork and clone the repository +git clone https://github.com//graphify.git +cd graphify +git remote add upstream https://github.com/Graphify-Labs/graphify.git +git fetch upstream +git checkout -b my-feature-branch upstream/v8 # Always branch off upstream v8, never commit directly to v8 + +# Set up the environment +uv sync +uv run pre-commit install + +# Run the test suite to confirm your setup +uv run pytest tests/ -q + +# Run linters and type checkers before pushing +uv run ruff check . +uv run pyright +``` + +- **Python versions**: 3.10+ +- **uv**: We use `uv` for dependency management. + +## Working on the Codebase +- **Use graphify itself**: Before making non-trivial architectural changes, use `graphify query ...` to navigate the codebase rather than blind grepping. Do not use the graph as evidence when the task concerns the graph's own correctness. +- **Update graph after code changes**: `graphify update .` +- **Root/path invariants**: Paths resolve relative to the calling module or scan root. +- **Cache considerations**: Be aware of relative/absolute path caching across rebuilds. +- **Generated skill files**: Regenerate with `uv run python -m tools.skillgen --bless`. Never hand-edit the generated files directly. +- **Corpus boundaries**: Do not create a second interpretation of the corpus boundary. Reuse the existing detection/ignore semantics whenever another pass walks project files (e.g. `.graphifyignore`). +- **Cross-platform**: Windows portability is a first-class contribution concern. Path separators, symlinks, absolute/relative paths, hash seeds, and shell interpolation must work correctly on Windows. + +## Making a Change +1. Find or create an issue +2. Reproduce +3. Identify invariant +4. Make smallest fix +5. Add regression test +6. Run targeted tests +7. Run full suite (`uv run pytest tests`) +8. Run lint/type checks (`uv run ruff check .`, `uv run pyright`) +9. Regenerate artifacts if you touched their sources (`uv run python -m tools.skillgen --bless`). + +## Tests +- **pytest**: The primary test runner. +- **Fixture conventions**: New language extractors need fixtures under `tests/fixtures/` and tests in `tests/test_languages.py`. +- **Environment isolation**: Tests must not accidentally depend on the contributor's ambient environment. When writing backend/provider tests, explicitly isolate or clear environment variables (e.g., `OPENAI_API_KEY`, `OLLAMA_HOST`). +- **Deterministic tests**: Ensure tests don't rely on ambient state or ordering. +- **Regression-test expectations**: Test must fail on pre-fix and pass on post-fix. + +## Language Extractors +- **Extractor module**: Defines logic for each language AST. +- **Dispatch table**: Registers the parser and language. +- **Tree-sitter dependency**: Use ASTs where possible. +- **Fixture**: Ensure comprehensive test cases in `tests/fixtures/`. +- **Cross-file resolution considerations**: Resolution stays local to AST paths. + +## Generated Skills and Monoliths +- Source fragments are authoritative. +- Run skillgen (`uv run python -m tools.skillgen --bless`). +- Never casually edit generated artifacts. +- Sanctioned round-trip changes only. +- Preserve multiset checks. + +## Data Integrity Rules +- **Zero-node guard**: Must run before writes. +- **Shrink guard**: Must not persist smaller corrupt graphs. (Note: forced writes can bypass this). +- `to_json` before report side effects. +- **Cache consistency**: Must be maintained across absolute/relative paths. (e.g., The Windows absolute-path issue taught us that earlier side effects that persist bad absolute-path entries into the semantic cache are still data loss, even if the final graph write passes the shrink guard). +- **Provenance**: Must be preserved. +- **Cross-file edges**: Must be preserved during incremental updates, even if node count is unchanged. + +## Security +- Review [SECURITY.md](SECURITY.md). +- Any change touching generated skill instructions, shell commands, subprocesses, URL ingestion, path handling, prompts, or serialization must be reviewed as a security-sensitive change. +- Never interpolate untrusted content into shell/Python. + +## Commit Messages +Use a conventional-commit prefix (e.g., `fix:`, `feat:`, `docs:`, `fix(extract):`) and make the subject describe the change. Explain why in the body when the change is non-trivial. Reference the relevant issue/PR. +- **AI Authorship Disclosure**: If an AI coding assistant materially contributed to the implementation, disclose it in the commit metadata according to the repository's authorship convention (e.g., `Co-Authored-By: Claude `). Do not attribute code to a model that did not contribute. + +## Pull Requests +- One concern per PR. +- No unrelated changes. +- Describe problem / implementation / verification. +- List commands actually run. +- Document limitations / unsupported cases. +- Keep description synchronized with final implementation. +- Rebase/resolve conflicts before requesting final review. + +## Issue Reports +### Bugs +Include exact version/commit, environment, minimal reproduction, expected vs actual, logs, graph/cache artifacts where relevant, and whether a clean checkout reproduced it. + +### Feature Requests +Focus on the problem first, proposed behavior, alternatives, and compatibility considerations. + +## Review Expectations +- Correctness, regression coverage, scope, determinism, provenance, security, and documentation. + +## Release / Generated Artifacts +- **What gets regenerated**: Skill files via skillgen, HTML exports. +- **What should not be committed**: Local cache (`.graphify_cached.json`), generated node artifacts outside of the expected outputs. + +## Getting Help +- **Discord**: Join the [Graphify Discord](https://discord.gg/XDnKVpzdXB) for questions and discussion. +- **Issues**: Search [existing issues](https://github.com/Graphify-Labs/graphify/issues) before opening a new one. +- **Discussions**: Use GitHub issues for bugs and feature requests, Discord for open-ended questions. + +## Further Reading +- [README.md](README.md) +- [ARCHITECTURE.md](ARCHITECTURE.md) +- [SECURITY.md](SECURITY.md) +- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) +- [The Memory Layer](https://safishamsi.gumroad.com/l/qetvlo) From a61eeebb29f0ff20364890c94fe1013be5f7c3b5 Mon Sep 17 00:00:00 2001 From: nikhil2004 Date: Sat, 26 Sep 2026 04:40:37 +0530 Subject: [PATCH 3/4] docs: correct factual drift in architecture and security policies --- ARCHITECTURE.md | 6 +++--- SECURITY.md | 12 ++++++------ 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 080f46f223..a3b1b5530c 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -8,7 +8,7 @@ graphify is a Claude Code skill backed by a Python library. The skill orchestrat detect() → extract() → build() → cluster() → analyze helpers → report.generate() → export.to_*() ``` -Each stage lives in its own module and they communicate through plain Python dicts and NetworkX graphs - no shared state, no side effects outside `graphify-out/`. Most stages are a single function; `analyze.py` and `export.py` are sets of sibling functions rather than one entry point. +Each stage lives in its own module and they communicate through plain Python dicts and NetworkX graphs. While designed to minimize shared state, some stages (like extractors) rely on ambient module-level state around the active scan root. Most stages are a single function; `analyze.py` and `export.py` are sets of sibling functions rather than one entry point. ## Module responsibilities @@ -87,7 +87,7 @@ All external input passes through `graphify/security.py` before use: - URLs → `validate_url()` (http/https only) + `_NoFileRedirectHandler` (blocks file:// redirects) - Fetched content → `safe_fetch()` / `safe_fetch_text()` (size cap, timeout) - Graph file paths → `validate_graph_path()` (must resolve inside `graphify-out/`) -- Node labels → `sanitize_label()` (strips control chars, caps 256 chars, HTML-escapes) +- Node labels → `sanitize_label()` (strips control chars, caps 256 chars) See `SECURITY.md` for the full threat model. @@ -99,4 +99,4 @@ One test file per module under `tests/`. Run with: pytest tests/ -q ``` -All tests are pure unit tests - no network calls, no file system side effects outside `tmp_path`. +The test suite is designed to avoid network access and uncontrolled filesystem effects; most tests are isolated with temporary directories and environment fixtures. diff --git a/SECURITY.md b/SECURITY.md index 795454b214..3de3465c20 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,8 +4,8 @@ | Version | Supported | |---------|-----------| -| 0.3.x | Yes | -| < 0.3 | No | +| Latest 0.9.x | Yes | +| < 0.9 | No | ## Reporting a Vulnerability @@ -18,11 +18,11 @@ Report security issues via GitHub's private vulnerability reporting, or email th - Potential impact - Suggested fix (if any) -We will acknowledge receipt within 48 hours and aim to release a fix within 7 days for critical issues. +We will acknowledge receipt as soon as possible and work with you to release a coordinated fix. ## Security Model -graphify is a **local development tool**. It runs as a Claude Code skill and optionally as a local MCP stdio server. It makes no network calls during graph analysis - only during `ingest` (explicit URL fetch by the user). +graphify is a **local development tool**. It runs as a Claude Code skill and optionally as a local MCP stdio server. Its network boundaries are: AST/code extraction is local and deterministic; semantic extraction may send content to a configured model/backend; `ingest` uses explicit outbound fetch; HTTP MCP is an opt-in network listener. ### Threat Surface @@ -32,12 +32,12 @@ graphify is a **local development tool**. It runs as a Claude Code skill and opt | Oversized downloads | `safe_fetch()` streams responses and aborts at 50 MB. `safe_fetch_text()` aborts at 10 MB. | | Non-2xx HTTP responses | `safe_fetch()` raises `HTTPError` on non-2xx status codes - error pages are not silently treated as content. | | Path traversal in MCP server | `security.validate_graph_path()` resolves paths and requires them to be inside `graphify-out/`. Also requires the `graphify-out/` directory to exist. | -| XSS in graph HTML output | `security.sanitize_label()` strips control characters, caps at 256 chars, and HTML-escapes all node labels and edge titles before pyvis embeds them. | +| XSS in graph HTML output | `security.sanitize_label()` strips control characters and caps at 256 chars. (Note: HTML escaping happens separately in the HTML exporter, not in `sanitize_label()`). | | Prompt injection via node labels | `sanitize_label()` also applied to MCP text output - node labels from user-controlled source files cannot break the text format returned to agents. | | Prompt injection via source file content | During the semantic pass, source files are attacker-controlled text mixed into the LLM context. `_read_files()` in `llm.py` wraps every file in a hash-stamped `` delimiter block, the extraction system prompt instructs the model to treat that block as inert data and never as instructions, and `_neutralise_injection_sentinels()` defangs known chat-template/jailbreak tokens (`<\|im_start\|>`, `[INST]`, `<>`, forged ``, etc.) before insertion. This is the table-stakes defense (issue #1210): it does not make injection impossible, but changes it from "works on first try" to "requires evasion." | | YAML frontmatter injection | `_yaml_str()` escapes backslashes, double quotes, and newlines before embedding user-controlled strings (webpage titles, query questions) in YAML frontmatter. | | Encoding crashes on source files | All tree-sitter byte slices decoded with `errors="replace"` - non-UTF-8 source files degrade gracefully instead of crashing extraction. | -| Symlink traversal | `os.walk(..., followlinks=False)` is explicit throughout `detect.py`. | +| Symlink traversal | `os.walk(..., followlinks=False)` is parameterized to avoid unchecked traversal where appropriate. | | Corrupted graph.json | `_load_graph()` in `serve.py` wraps `json.JSONDecodeError` and prints a clear recovery message instead of crashing. | ### What graphify does NOT do From 9d2592ea50e67f7abf01317f2a33f3b4be33fb18 Mon Sep 17 00:00:00 2001 From: nikhil2004 Date: Sat, 26 Sep 2026 04:40:37 +0530 Subject: [PATCH 4/4] docs: clarify repository orientation and team graph sync rules --- AGENTS.md | 2 +- README.md | 14 +++++++++----- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b919654c49..38857bdc2d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,6 +3,6 @@ This project has a graphify knowledge graph at graphify-out/. Rules: -- Before answering architecture or codebase questions, read graphify-out/GRAPH_REPORT.md for god nodes and community structure +- When working on Graphify itself, use the repository's existing Graphify guidance. For codebase questions, prefer scoped graph queries where available; use the report for broad orientation. Do not use the graph as evidence when the task concerns the graph's correctness itself. - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files - After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost) diff --git a/README.md b/README.md index 46d4289bd6..5027e81f13 100644 --- a/README.md +++ b/README.md @@ -446,12 +446,16 @@ dist/ ## Team setup -`graphify-out/` is meant to be committed to git so everyone on the team starts with a map. +For users building a team graph, the `graphify-out/` directory is gitignored by default. If your team wants to share a graph, you should **explicitly force-add only the queryable products** so your teammates can consume them: -**Recommended `.gitignore` additions:** -``` -graphify-out/cost.json # local only -# graphify-out/cache/ # optional: commit for speed, skip to keep repo small +*(Note: If you are contributing to the Graphify repository itself, do not commit your local `graphify-out/` at all unless it's a specific test fixture).* + +**Recommended git commands to share a graph (you only need to force-add once; git will track future changes normally):** +```bash +git add -f graphify-out/graph.json +git add -f graphify-out/GRAPH_REPORT.md +# git add -f graphify-out/wiki/ # optional: if using the wiki export +# git add -f graphify-out/obsidian/ # optional: if using the Obsidian export ``` > `manifest.json` is now portable — keys are stored as relative paths and re-anchored on load, so committing it is safe and avoids a full rebuild on first checkout.