# VectorGraph Agent Entry Point VectorGraph is an AI-native company context and execution layer from OrinTech. The launch starts with agent-ready work management, then exposes the same permissioned work through the browser UI, `/cli/v1`, hosted VectorGraph MCP, and local NorthGraph MCP. This file is the entrypoint, not the full documentation. Read it first, then read `/documentation` or the repo docs listed below for the task you are about to perform. Full public docs: `/documentation` Canonical repo first-run guide: `docs/GETTING_STARTED.md` ## Read Order For a hosted or public agent: 1. Read this file. 2. Read the "Get started" section in `/documentation`. 3. Verify credentials before any read or write. 4. Use the narrowest supported surface for the job. For an agent running inside the repo: 1. Read this file. 2. Read `docs/GETTING_STARTED.md` for first-run setup or troubleshooting. 3. Read `docs/product/PRE_LAUNCH_WORK.md`. 4. Read `docs/engineering/BEST_PRACTICES.md` and `docs/file-size-code-organization.md`. 5. Read `docs/agents/README.md`. 6. Read `docs/integrations/CLI_ENDPOINT.md`. 7. Read `docs/security/AUTH_AND_PERMISSIONS.md`. 8. Read `docs/product/NORTH_GRAPH_PRD.md` if local codebase analysis is needed. Useful repo docs: - `docs/GETTING_STARTED.md` - `docs/agents/README.md` - `docs/agents/programmatic-parity-ledger.md` - `docs/agents/schemas/context-bundle.schema.json` - `docs/integrations/AGENT_APP_SETUP.md` - `docs/product/PRE_LAUNCH_WORK.md` - `docs/product/CURRENT_STATUS.md` - `docs/integrations/CLI_ENDPOINT.md` - `docs/integrations/OPENAI_PLUGIN.md` - `docs/api/INTERNAL_API.md` - `docs/security/AUTH_AND_PERMISSIONS.md` - `docs/product/NORTH_GRAPH_PRD.md` ## Surface Choice Use Browser UI when a human needs to configure workspace settings, teams, private visibility, tokens, access, or final review. Use `/cli/v1` when a script or terminal command needs JSON access to a typed workflow or any operation in the committed agent-safe OpenAPI registry. The browser-login CLI profile covers the documented first-run CLI workflows, including permission-filtered context reads. A manually created Developer access token may use a narrower operator-selected scope set. Use hosted VectorGraph MCP at `/mcp` when an agent needs permission-filtered workspace records, issue/project context, comments, approval requests, or an operation in the scope-filtered agent-safe OpenAPI registry. Use local NorthGraph MCP through `vectorgraph north mcp` when an agent needs local repository facts: files, symbols, callers, routes, effects, policy, diff risk, impacted tests, or verification reports. This requires the published `@orintech/cli@0.7.1` package. Do not scrape the browser UI when a CLI or MCP contract exists. When making repository changes, keep the implementation DRY. Search for existing behavior before writing code, reuse or extract focused helpers instead of copying logic, and do not add unnecessary wrappers, aliases, compatibility paths, duplicate routes, config switches, feature flags, or speculative abstractions. ## Credentials CLI tokens: - Recommended: run `vectorgraph auth login`, compare the ten-minute browser code with the terminal, select one or more workspaces, and approve. The flow creates a distinct token for each workspace; no token spans workspaces. - Advanced manual fallback: Workspace console -> Developer access -> Tokens. - Used with `Authorization: Bearer `. - Intended for human-owned terminal scripts and CI-style automation. - Stored hashed, shown once, workspace scoped, optionally team-grant scoped, expirable, and revocable. MCP agent credentials: - Recommended for the current public CLI: after login, use `vectorgraph workspace use `, verify the active workspace, then run `vectorgraph mcp setup --client codex,claude --local-north`. Without `--team` the connection is workspace-wide (`team_scope = 'all'`), following every team the accountable user can access; add `--team ` to narrow it. Run it with `--json` first for a no-write review, then repeat the identical request with `--json --yes` only after approval. - Gemini, Cursor, and unsupported clients use Workspace console -> Integrations. - Manual fallback: created in Workspace console -> Developer access -> Agents. - Used with `Authorization: Bearer `. - Resolve to an agent identity with an accountable human owner. - Limited by scopes, allowed teams, allowed tools, workspace membership, and private-team permissions. - Agent principals can be imported and synced from committed `.vectorgraph/policy/*.toml` files; sync refreshes active MCP credential scopes and audits the previous and new policy source. - Official ChatGPT and Codex directory connections use WorkOS OAuth discovery and consent. Users must not paste API keys or browser session cookies into an OpenAI client. VectorGraph validates the signed access token for the exact MCP resource and does not persist the WorkOS bearer or refresh token. Never put tokens in prompts, issue comments, screenshots, terminal transcripts, or source files. Release boundary: public CLI `0.7.1` supports saved profiles, persistent `workspace use`, non-mutating `--workspace` selection, and saved-profile session routing below. The exact CLI/North pair is published and registry-verified. ## Required First Checks Before CLI writes with the current public CLI: ```bash vectorgraph workspace list vectorgraph workspace use vectorgraph auth status --json ``` Public CLI `0.7.1` allows parallel agents to pass `--workspace` on each product command or set `VECTORGRAPH_WORKSPACE_ID=` separately in each process when no environment token is set. Environment tokens must be paired with their immutable workspace IDs. Ambiguous names or slugs fail before network access. Require: - `credentialVerified: true` - the expected immutable `workspace.id` - the expected workspace slug and role - no mismatch between the local profile and live token workspace Before MCP tool calls: ```bash export VECTORGRAPH_MCP_URL="https://app.example.com/mcp" # Inject the workspace-specific variable through a local secret store. : "${VECTORGRAPH_MCP_TOKEN_11111111111141118111111111111111:?workspace MCP token is not set}" curl -s -X POST "$VECTORGRAPH_MCP_URL" \ -H "Authorization: Bearer $VECTORGRAPH_MCP_TOKEN_11111111111141118111111111111111" \ -H "X-VectorGraph-MCP-Purpose: setup_verification" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{}}' ``` Then call `resources/list`, read `vectorgraph://workspace//teams`, and call `tools/list`. Workspace UUIDs are discoverable from the listed resource URIs. Missing resources, teams, or tools are authorization results. Do not assume a capability exists just because this file mentions it. ## Hosted VectorGraph MCP Public hosted MCP endpoint: `https://vectorgraph.app/mcp` Automatic `vectorgraph mcp setup` derives `/mcp` from the authenticated CLI origin. The default browser-login and hosted MCP origin is `https://vectorgraph.app`. Primary use: - Search accessible work. - Read issue context bundles. - Create or update accessible issues. - Add comments. - Link already-synced GitHub pull requests to accessible issues. - Request approvals. - Discover and execute approved API operations without arbitrary method/path access. Supported launch tools: - `search` - `fetch` - `search_work` - `create_issue` - `update_issue` - `add_comment` - `link_pull_request` - `read_context_bundle` - `request_approval` - `execute_api_operation` `execute_api_operation` requires the operation's domain scopes and is shown only when allowed by both token scopes and agent `allowedTools`. The full catalog also requires coverage of every team visible to the accountable user (workspace-wide `team_scope = 'all'` or all teams listed); partially team-scoped credentials may execute only the team-filter-aware subset, and should use a narrower typed tool/resource for everything else. Important resource: - `vectorgraph://workspace/{workspaceId}/issue/{issueIdentifier}/context` MCP client config shape: New automatic setup uses `vectorgraph-` for hosted MCP. The key losslessly base64url-encodes the complete immutable workspace UUID, preventing same-slug and same-prefix collisions while keeping current Claude-qualified VectorGraph tool and prompt names within 64 characters. Existing managed connections retain their recorded legacy names and must never be retargeted to another workspace. ```json { "mcpServers": { "vectorgraph-ERERERERQRGBEREREREREQ": { "transport": "http", "url": "${VECTORGRAPH_MCP_URL}", "headers": { "Authorization": "Bearer ${VECTORGRAPH_MCP_TOKEN_11111111111141118111111111111111}" } } } } ``` ## CLI JSON Surface Route prefix: `/cli/v1` The stable customer origin is `https://vectorgraph.app`; it proxies both `/cli/v1` and `/mcp` to the matching product services. Manual environment overrides are advanced deployment or recovery paths and must use an approved HTTPS origin. Use `Idempotency-Key` for mutating retries. Key endpoints: - `GET /cli/v1/me` - `GET /cli/v1/workspaces` - `GET /cli/v1/workspaces/{workspaceId}/teams` - `GET /cli/v1/workspaces/{workspaceId}/issues` - `POST /cli/v1/workspaces/{workspaceId}/issues` - `GET /cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}` - `PATCH /cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}` - `POST /cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}/comments` - `GET /cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}/context` - `GET /cli/v1/workspaces/{workspaceId}/issues/{issueIdentifier}/github` - `GET /cli/v1/workspaces/{workspaceId}/projects/{projectId}/context` - `POST /cli/v1/workspaces/{workspaceId}/operations/{operationId}` Inventory and invoke the committed allowlist: ```bash vectorgraph api operations --json vectorgraph api call --path-json '{...}' --query-json '{...}' --body-json '{...}' --idempotency-key --json ``` ## Local NorthGraph MCP NorthGraph is local-first codebase intelligence. It is not the hosted VectorGraph MCP server. It runs on the developer machine and should keep source local by default. Public installation currently targets `@orintech/cli@0.7.1`. Its exact CLI/North pair is published and registry-verified. Current cross-platform package contract: - Windows x64/ARM64, macOS Intel/Apple Silicon, and Linux x64/ARM64 use the same exact current package: `npm install --global @orintech/cli@0.7.1`. - Node.js `24.19.0` is required. Git is required for local repository analysis. - Bundled Tree-sitter WASM parsers cover Python, Java, C#, C, C++, Go, PHP, and Rust; Python, a JDK, and Clang are not baseline prerequisites. - Run `npm view @orintech/cli@0.7.1 version` first and require `0.7.1`. - No VectorGraph desktop app, native OS installer, or supported offline bundle exists today. - Do not turn official Node.js platform availability into a VectorGraph support claim. Each claimed OS/architecture still needs release-package smoke proof. Start local MCP: ```bash vectorgraph north mcp ``` MCP client config shape: ```json { "mcpServers": { "vectorgraph-north": { "command": "vectorgraph", "args": ["north", "mcp"] } } } ``` Useful commands: ```bash vectorgraph north init vectorgraph north index --json vectorgraph north inspect --json vectorgraph north effects --type email_send --json vectorgraph north diff analyze --base main --json vectorgraph north tests impacted --base main --json vectorgraph north verify --base main --json vectorgraph north report pr --base main --out .vectorgraph/north/pr-report.json --json ``` Use NorthGraph before code edits when the agent needs: - symbol definitions, callers, or callees - route/job/module impact - risky effects such as database writes, email sends, secret reads, network calls, auth checks, payment behavior, file writes, queue writes, or production config changes - project policy checks from `vectorgraph.north.json` - impacted tests - verification evidence after a diff NorthGraph output is evidence, not permission. Risky actions still require the normal VectorGraph, GitHub, CI, review, and human approval boundaries. ## Agent Rules - Verify credentials before reads or writes. - Use context bundles before implementation planning. - Use NorthGraph before local repo edits when code impact is unclear. - Preserve `requestId` values in logs, comments, or handoff summaries. - Use idempotency keys for mutating retries. - Treat `not_found` as possibly permission-filtered, not proof the object does not exist. - Do not ask for or use scopes for the frozen human-only set: billing, workspace security settings, member management, GitHub App installation, or provider credential/OAuth flows. Export, integration-write, admin, credential, and workspace-create scopes exist but grant only their approved operations. Deploy marking uses `deploy:write` on the `/cli/v1` deploy-marker route and is agent-grantable. - Do not bypass workspace, private-team, guest, requester, repository, or local project policy boundaries. - Do not upload source code, local paths, terminal output, or secrets unless a human explicitly approves that sync. - Do not claim work is verified unless you can point to the command, report, request ID, or external check that verified it. ## Common Error Codes - `unauthorized`: the bearer token is missing. - `invalid_token`: token is revoked, expired, malformed, or rejected. - `scope_denied`: token does not include a required scope. - `workspace_scope_denied`: token is scoped to a different workspace. - `agent_tool_denied`: agent identity cannot use that MCP tool. - `agent_team_denied`: agent identity cannot access that team. - `agent_operation_team_scope_denied`: this operation requires coverage of every team visible to the accountable user; team-scoped credentials may only call team-filter-aware operations — use a narrower typed contract otherwise. - `permission_denied`: actor is authenticated but cannot access the object. - `not_found`: object is missing or intentionally hidden by permissions. - `idempotency_key_conflict`: same idempotency key was reused with different input. ## Launch Boundary `docs/product/PRE_LAUNCH_WORK.md` is the only active repo source of truth for launch scope, current gaps, provider blockers, evidence requirements, public-claim support, and unfinished work. Agents are external clients using VectorGraph CLI/MCP/API contracts with scoped credentials. VectorGraph does not provide hosted LLM inference, model routing, autonomous coding agents, autonomous production changes, third-party MCP marketplace behavior, or browser-screen scraping workflows in launch. Live in the launch codebase: browser work management, workspace knowledge, Signals, GitHub integration support, `/cli/v1`, hosted VectorGraph MCP, local NorthGraph CLI/MCP, admin, imports, exports, realtime, search, jobs, and graph projection foundations. Beta and launch-hardening: daily worklist proof, broad browser smoke, restore evidence, production dashboards/alerts, graph operations proof, package publication, provider smoke, and final release-record evidence. Provider-ready but not provider-live: Slack, GitLab, Bitbucket, Codex, Claude, Zendesk, Salesforce, Datadog, Sentry, Resend delivery setup, object storage, and the expanded first-class provider catalog until provider credentials, install flows, webhooks, health checks, sandbox or production verification, and runbook evidence exist. Explicitly excluded from launch: integration marketplace, arbitrary external MCP tool execution, hosted LLM/model routing, autonomous production-change agents, full code review/diff UI, broad public API/webhook platform, native desktop/mobile, relay, remote terminal/file access, local runtime, and Solr unless future evidence and ADR change scope.