Understand the system in three diagrams.

flowchart TB
    accTitle: hnindex system architecture
    accDescr: An MCP agent calls a local hnindex server with workspace files and SQLite storage. Semantic retrieval optionally uses embeddings and Qdrant.
    agent_client["AI agent / MCP client<br/>Codex · Claude · Cursor"]
    subgraph local_workspace["Local workspace"]
        hnindex_server["hnindex MCP server<br/>Context · AST · code lookup"]
        project_files["Source files<br/>README · Git"]
        sqlite_store[("SQLite<br/>FTS · graph · declared tasks")]
        project_files -->|Read and check freshness| hnindex_server
        hnindex_server <-->|Index and task storage| sqlite_store
    end
    subgraph semantic_services["Optional semantic retrieval"]
        embedding_provider["Embeddings<br/>Ollama local or cloud API"]
        qdrant_store[("Qdrant vectors<br/>Local or hosted")]
    end
    agent_client <-->|MCP / stdio| hnindex_server
    hnindex_server -.->|Code chunks and queries| embedding_provider
    embedding_provider -.->|Vectors| hnindex_server
    hnindex_server <-.->|Store and retrieve vectors| qdrant_store

sequenceDiagram
    accTitle: Agent context and code location sequence
    accDescr: A developer declares a task. The agent inspects the workspace, optionally builds a graph, records the task, retrieves locations, then reads and edits current source.
    actor developer as Developer
    participant agent_client as Codex / AI agent
    participant hnindex_server as hnindex MCP
    participant sqlite_store as SQLite
    participant project_files as Files and Git
    developer->>agent_client: Describe the task
    agent_client->>hnindex_server: workspace_context(path)
    hnindex_server->>project_files: Read purpose and Git state
    hnindex_server-->>agent_client: Workspace and index status
    opt Graph missing or needs refresh
        agent_client->>hnindex_server: index_code_graph(path, project_name)
        hnindex_server->>project_files: Parse TS/JS source
        hnindex_server->>sqlite_store: Store graph and source snapshots
        hnindex_server-->>agent_client: Index summary
    end
    agent_client->>hnindex_server: workspace_context(project_name, task, session_id)
    hnindex_server->>sqlite_store: Persist explicitly declared task
    hnindex_server-->>agent_client: Project and session context
    agent_client->>hnindex_server: locate_code(project_name, symbol)
    hnindex_server->>sqlite_store: Look up indexed definitions
    hnindex_server->>project_files: Check source freshness
    hnindex_server-->>agent_client: File, lines, evidence and freshness
    agent_client->>project_files: Read current source and edit
    agent_client-->>developer: Explain changes and validation

flowchart TB
    accTitle: Developer and agent workflow
    accDescr: The developer connects MCP and requests work. The agent gathers context, indexes if needed and locates code. Fresh source is read before editing and developer review.
    subgraph developer_steps["Developer"]
        connect_client(["Connect MCP client"])
        declare_task["Declare task"]
        review_changes["Review changes"]
        continue_work(["Continue or start next task"])
        connect_client --> declare_task
        review_changes --> continue_work
    end
    subgraph agent_steps["AI agent"]
        get_context["Read workspace context"]
        prepare_index["Index or refresh graph"]
        locate_code["Locate code and references"]
        check_freshness{"Source fresh?"}
        read_edit["Read source and edit"]
        get_context --> prepare_index --> locate_code --> check_freshness
        check_freshness -->|Yes| read_edit
        check_freshness -->|No or missing| prepare_index
    end
    declare_task --> get_context
    read_edit --> review_changes
    continue_work -.-> declare_task