ai-workspace: Instructions file for Codex

AGENTS.md

Project map for AI agents. Keep this file up-to-date as the project evolves.

Project Overview

Cross-project shared context CLI + MCP server. Manages local shared context with SQLite and optionally publishes versioned project snapshots to a PostgreSQL-backed, read-only hosted MCP service.

Tech Stack

• Language: Rust (edition 2024)
• Database: SQLite (rusqlite, bundled) locally; PostgreSQL (sqlx) for cloud snapshots
• CLI: Clap v4 (derive)
• Protocol: MCP over stdio locally and authenticated HTTP in cloud mode

Project Structure

ai-workspace/
├── Cargo.toml              # Package config, dependencies
├── Cargo.lock              # Locked dependency versions
├── Makefile                # Build automation (build, test, lint, fmt, check)
├── README.md               # Project landing page
├── src/
│   ├── main.rs             # Entry point, clap App definition
│   ├── execution.rs        # Request-local cwd, environment and CLI output capture
│   ├── local/
│   │   ├── mod.rs          # Owner discovery, CLI forwarding, stdio bridge
│   │   └── server.rs       # Local HTTP MCP and serialized state-owner worker
│   ├── models.rs           # Data models (Project, Group, SharedItem, SharedItemKind)
│   ├── walk.rs             # File tree walker and grep (ignore + regex crates)
│   ├── indexer.rs          # FTS5 indexer for shared .md files (mtime refresh, reindex)
│   ├── codegraph.rs        # Rust-only CodeGraph parser, sync/reindex, source snippets
│   ├── cloud/
│   │   ├── auth.rs         # OIDC/JWKS JWT validation
│   │   ├── client.rs       # Snapshot push HTTP client
│   │   ├── http.rs         # Hosted Axum server and snapshot endpoint
│   │   ├── mcp.rs          # Hosted read-only MCP adapter
│   │   ├── models.rs       # Versioned cloud wire records
│   │   ├── snapshot.rs     # Deterministic local snapshot builder
│   │   ├── subscriptions.rs # Authenticated modern MCP event SSE subscriptions
│   │   └── store.rs        # PostgreSQL tenant read model
│   ├── cli/
│   │   └── mod.rs          # CLI subcommands and handlers
│   ├── db/
│   │   ├── mod.rs          # DB module exports
│   │   ├── schema.rs       # SQLite schema creation (tables, FTS5, triggers)
│   │   ├── owner.rs        # Canonical DB identity and cross-process ownership lock
│   │   └── crud.rs         # Database CRUD operations (Db struct)
│   └── mcp/
│       ├── mod.rs          # MCP server entry (stdio loop, request routing)
│       ├── protocol.rs     # JSON-RPC types (request, response, error)
│       ├── resources.rs    # Scoped event resources and local subscriptions
│       └── tools.rs        # MCP tool implementations (workspace, project, service, event, codegraph tools)
├── migrations/
│   └── 0001_cloud_read_model.sql # PostgreSQL JSONB/FTS tables and forced RLS
├── tests/
│   ├── cli_tests.rs        # CLI integration tests
│   ├── local_owner.rs      # Native owner election, HTTP/stdio sharing, recovery and access tests
│   ├── cloud_push.rs       # Snapshot push/redaction integration tests
│   ├── cloud_server.rs     # Cloud CLI/server boundary tests
│   ├── fts_search.rs       # FTS5 fulltext search integration tests
│   ├── mcp_http_tests.rs   # Hosted/local MCP compatibility tests
│   ├── mcp_subscriptions.rs # Live stdio event notification integration tests
│   ├── mcp_consistency.rs  # Live search/read revision and access revocation tests
│   └── mcp_tests.rs        # MCP protocol integration tests
└── .ai-factory/
    └── DESCRIPTION.md      # Project specification and tech stack