# Vector Agent Entry Point

Vector is an AI-native company context and execution layer. The launch starts with
multi-workspace work management, then exposes the same permissioned work through
the browser UI, `/cli/v1`, hosted Vector MCP, and local North Graph 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`

## Read Order

For a hosted or public agent:

1. Read this file.
2. Read `/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/product/CURRENT_STATUS.md`.
3. Read `docs/agents/README.md`.
4. Read `docs/integrations/CLI_ENDPOINT.md`.
5. Read `docs/security/AUTH_AND_PERMISSIONS.md`.
6. Read `docs/product/NORTH_GRAPH_PRD.md` if local codebase analysis is needed.

Useful repo docs:

- `docs/agents/README.md`
- `docs/agents/programmatic-parity-ledger.md`
- `docs/agents/schemas/context-bundle.schema.json`
- `docs/product/CURRENT_STATUS.md`
- `docs/integrations/CLI_ENDPOINT.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 workspaces,
teams, issues, comments, context bundles, or linked development metadata.

Use hosted Vector MCP at `/mcp` when an agent needs permission-filtered
workspace records, issue/project context, comments, approval requests, or
audited work-management tool calls.

Use local North Graph MCP through `vector north mcp` when an agent needs local
repository facts: files, symbols, callers, routes, effects, policy, diff risk,
impacted tests, or verification reports.

Do not scrape the browser UI when a CLI or MCP contract exists.

## Credentials

CLI tokens:

- Created by a human in Workspace console -> Developer access -> Tokens.
- Used with `Authorization: Bearer <token>`.
- Intended for human-owned terminal scripts and CI-style automation.
- Stored hashed, shown once, scoped, expirable, and revocable.

MCP agent credentials:

- Created by a human in Workspace console -> Developer access -> Agents.
- Used with `Authorization: Bearer <token>`.
- Resolve to an agent identity with an accountable human owner.
- Limited by scopes, allowed teams, allowed tools, workspace membership, and
  private-team permissions.

Never put tokens in prompts, issue comments, screenshots, terminal transcripts,
or source files.

## Required First Checks

Before CLI writes:

```bash
export VECTOR_BASE_URL="https://app.example.com"
export VECTOR_TOKEN="vta_..."

curl -s \
  -H "Authorization: Bearer $VECTOR_TOKEN" \
  "$VECTOR_BASE_URL/cli/v1/me"
```

Expected shape:

- `requestId`
- `actor.actorType`
- `token.scopes`
- `token.workspaceId`
- accessible `workspaces`

Before MCP tool calls:

```bash
export VECTOR_BASE_URL="https://app.example.com"
export VECTOR_MCP_TOKEN="vta_..."

curl -s -X POST "$VECTOR_BASE_URL/mcp" \
  -H "Authorization: Bearer $VECTOR_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{}}'
```

Then call `tools/list`. Missing tools are authorization results. Do not assume a
tool exists just because this file mentions it.

## Hosted Vector MCP

Endpoint: `/mcp`

Primary use:

- Search accessible work.
- Read issue context bundles.
- Create or update accessible issues.
- Add comments.
- Request approvals.

Supported launch tools:

- `search_work`
- `create_issue`
- `update_issue`
- `add_comment`
- `read_context_bundle`
- `request_approval`

Important resource:

- `vector://workspace/{workspaceId}/issue/{issueIdentifier}/context`

MCP client config shape:

```json
{
  "mcpServers": {
    "vector": {
      "transport": "http",
      "url": "${VECTOR_BASE_URL}/mcp",
      "headers": {
        "Authorization": "Bearer ${VECTOR_MCP_TOKEN}"
      }
    }
  }
}
```

## CLI JSON Surface

Route prefix: `/cli/v1`

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`

## Local North Graph MCP

North Graph is local-first codebase intelligence. It is not the hosted Vector
MCP server. It runs on the developer machine and should keep source local by
default.

Start local MCP:

```bash
vector north mcp
```

MCP client config shape:

```json
{
  "mcpServers": {
    "north-graph": {
      "command": "vector",
      "args": ["north", "mcp"]
    }
  }
}
```

Useful commands:

```bash
vector north init
vector north index --json
vector north inspect <symbol> --json
vector north effects --type email_send --json
vector north diff analyze --base main --json
vector north tests impacted --base main --json
vector north verify --base main --json
vector north report pr --base main --out .vector/north/pr-report.json --json
```

Use North Graph 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 `vector.north.json`
- impacted tests
- verification evidence after a diff

North Graph output is evidence, not permission. Risky actions still require the
normal Vector, GitHub, CI, review, and human approval boundaries.

## Agent Rules

- Verify credentials before reads or writes.
- Use context bundles before implementation planning.
- Use North Graph 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 admin, billing, export, security, member-management, or
  GitHub installation-management scopes in launch.
- 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

- `invalid_token`: token is missing, revoked, expired, or malformed.
- `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.
- `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

Agents are external clients using Vector CLI/MCP/API contracts with scoped
credentials. Vector 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.