# HAI-Co²

> Human-AI Co-Construction — a reference implementation where humans and an AI agent co-create a single shared solution.

## Docs

- [ADR-0000: Record architecture decisions](https://haico.gr/docs/adr/0000-record-architecture-decisions.md): Why and how we record architectural decisions as MADR-style ADRs.
- [ADR-0001: Two-branch model](https://haico.gr/docs/adr/0001-two-branch-model.md): Two-branch (develop + main) tag-driven release model.
- [ADR-0002: Dual development pathways](https://haico.gr/docs/adr/0002-dual-development-pathways.md): Traditional + AI-assisted contribution pathways, gated by issue label.
- [ADR-0003: Conversation branching via new threads](https://haico.gr/docs/adr/0003-conversation-branching-via-new-thread-and-state-seeding.md): Branch conversations as new threads seeded via checkpointer state, not per-table branch IDs.
- [ADR-0004: Hierarchical plan & objective](https://haico.gr/docs/adr/0004-hierarchical-plan-and-objective.md): Model the plan as a depth-ordered tree and add a per-turn editable Objective.
- [ADR-0005: User-feedback frame](https://haico.gr/docs/adr/0005-user-feedback-frame.md): One turn-anchored feedback table with a frontend-owned instrument, per-artifact keying, and branch-safe copies, plus admin observability.
- [ADR-0006: Programmatic API access](https://haico.gr/docs/adr/0006-programmatic-api-access.md): Personal access tokens as the documented credential for programmatic access, so reCAPTCHA and email verification stay on the interactive plane where they belong.
- [Architecture Decision Records](https://haico.gr/docs/adr/index.md): Why HAI-Co² keeps ADRs, how they are recorded, the status lifecycle, and the index of accepted decisions.
- [ADR template](https://haico.gr/docs/adr/template.md): Copy this template when writing a new ADR.
- [Agent core logic](https://haico.gr/docs/agent-core-logic.md): How the agent runs a turn: per-turn context, the ReAct loop, the model-node retry wrapper, tools, the SSE stream, snapshots, and typed artifacts.
- [AI-assisted pathway](https://haico.gr/docs/ai-pathway.md): The as-built AI-assisted contribution pathway (Coco), run by gh-aw on the repo's own key.
- [API-only clients](https://haico.gr/docs/api-guide/api-only-clients.md): What the server does for you regardless of client, and the two places where a script must do what the browser does.
- [Authentication](https://haico.gr/docs/api-guide/authentication.md): Personal access tokens: creating them, scoping them, revoking them, and the limits and errors that apply.
- [Endpoint groups](https://haico.gr/docs/api-guide/endpoint-groups.md): A map of the six route groups, plus where to find the raw OpenAPI spec and interactive docs.
- [Recipes](https://haico.gr/docs/api-guide/recipes.md): A runnable two-turn co-construction loop in Python, and a token check for CI.
- [Streaming agent turns](https://haico.gr/docs/api-guide/streaming-turns.md): The Server-Sent Events contract for POST /api/query/stream_steps/sse, and how to choose the model that runs the turn.
- [Reading the workspace](https://haico.gr/docs/api-guide/workspace.md): Fetch the objective, document, and plan that the agent and the user co-constructed.
- [Getting started](https://haico.gr/docs/api-reference.md): Make your first authenticated call and run your first agent turn in about five minutes.
- [Create Key](https://haico.gr/docs/api-reference/api-keys/create-key.md): Mint a personal access token and return its plaintext once.
- [List Keys](https://haico.gr/docs/api-reference/api-keys/list-keys.md): List the caller's personal access tokens, newest first.
- [Revoke Key](https://haico.gr/docs/api-reference/api-keys/revoke-key.md): Revoke one of the caller's keys.
- [Google Auth](https://haico.gr/docs/api-reference/auth/google-auth.md): Login or auto-register with a Google account.
- [Login](https://haico.gr/docs/api-reference/auth/login.md): Authenticate with username/password and return a JWT.
- [Me](https://haico.gr/docs/api-reference/auth/me.md): Return the currently authenticated user's profile.
- [Record Consent](https://haico.gr/docs/api-reference/auth/record-consent.md): Record the user's consent to take part in the HAI-Co² research study.
- [Register](https://haico.gr/docs/api-reference/auth/register.md): Register a new local-auth user and send an email-verification link.
- [Resend Verification](https://haico.gr/docs/api-reference/auth/resend-verification.md): Resend the email-verification link for a local user.
- [Verify Email](https://haico.gr/docs/api-reference/auth/verify-email.md): Verify a user's email address using the token sent in the registration email.
- [Branch Conversation](https://haico.gr/docs/api-reference/conversations/branch-conversation.md): Fork a conversation at a completed user turn.
- [Create Conversation](https://haico.gr/docs/api-reference/conversations/create-conversation.md): Register a new empty conversation owned by the authenticated user.
- [Delete Conversation](https://haico.gr/docs/api-reference/conversations/delete-conversation.md): Soft-delete a conversation owned by the authenticated user.
- [Get Conversation Graph](https://haico.gr/docs/api-reference/conversations/get-conversation-graph.md): Return the conversation family of a thread as a read-only DAG.
- [Get Conversation Messages](https://haico.gr/docs/api-reference/conversations/get-conversation-messages.md): Return the message history for a conversation, reconstructed from the LangGraph checkpointer state.
- [List Conversations](https://haico.gr/docs/api-reference/conversations/list-conversations.md): Return a paginated list of the authenticated user's conversations.
- [Delete Feedback](https://haico.gr/docs/api-reference/feedback/delete-feedback.md): Toggle one feedback row off (e.g. un-like). Idempotent.
- [Get Thread Feedback](https://haico.gr/docs/api-reference/feedback/get-thread-feedback.md): Return all of the caller's feedback for a thread (frontend hydration).
- [Upsert Feedback](https://haico.gr/docs/api-reference/feedback/upsert-feedback.md): Insert or update one feedback row, keyed by its anchor tuple.
- [Health](https://haico.gr/docs/api-reference/health/health.md): Liveness probe — confirms the process is running.
- [Ready](https://haico.gr/docs/api-reference/health/ready.md): Readiness probe — confirms the application is ready to handle requests.
- [Stream Steps Sse](https://haico.gr/docs/api-reference/query/stream-steps-sse.md): Stream agent reasoning steps as Server-Sent Events.
- [Root](https://haico.gr/docs/api-reference/root/root.md): API root — returns basic metadata and links to docs and health endpoints.
- [Advance Step](https://haico.gr/docs/api-reference/study/advance-step.md): Persist the resume point so a refresh continues where the user left off.
- [Complete Session](https://haico.gr/docs/api-reference/study/complete-session.md): Mark the study complete and stamp the once-per-user flag.
- [Current Session](https://haico.gr/docs/api-reference/study/current-session.md): Return the caller's session + responses, or null if they have none.
- [Export Study](https://haico.gr/docs/api-reference/study/export-study.md): Admin-only export of all study responses (pseudonymized: no user_id).
- [Link Thread](https://haico.gr/docs/api-reference/study/link-thread.md): Record the Studio conversation the participant does the task in.
- [Start Session](https://haico.gr/docs/api-reference/study/start-session.md): Start (or resume) the caller's study session for the active study.
- [Study Status](https://haico.gr/docs/api-reference/study/study-status.md): Whether study mode is enabled and whether the caller has finished it.
- [Submit Response](https://haico.gr/docs/api-reference/study/submit-response.md): Submit one questionnaire instrument; re-submitting the same slot upserts.
- [Create Preference](https://haico.gr/docs/api-reference/workspace/create-preference.md): Record a new preference / constraint for a thread.
- [Create Todo](https://haico.gr/docs/api-reference/workspace/create-todo.md): Add a new sub-goal to the todo list for a thread.
- [Delete Preference](https://haico.gr/docs/api-reference/workspace/delete-preference.md): Permanently delete a preference.
- [Delete Todo](https://haico.gr/docs/api-reference/workspace/delete-todo.md): Permanently delete a todo item.
- [Get Artifact](https://haico.gr/docs/api-reference/workspace/get-artifact.md): Fetch a single artifact by id (must belong to the user's thread).
- [Get Document](https://haico.gr/docs/api-reference/workspace/get-document.md): Fetch the current document content for a thread.
- [Get Latest Artifact](https://haico.gr/docs/api-reference/workspace/get-latest-artifact.md): Return the most recent artifact for a thread, or ``null`` if none.
- [Get Objective](https://haico.gr/docs/api-reference/workspace/get-objective.md): Fetch the current objective for a thread.
- [Get Objective History](https://haico.gr/docs/api-reference/workspace/get-objective-history.md): Return how the objective evolved over the conversation (oldest first).
- [Get Snapshot](https://haico.gr/docs/api-reference/workspace/get-snapshot.md): Return the full snapshot row for one (thread, turn) pair.
- [List Artifacts](https://haico.gr/docs/api-reference/workspace/list-artifacts.md): List typed artifacts for a thread, newest first.
- [List Preferences](https://haico.gr/docs/api-reference/workspace/list-preferences.md): Return all preferences / constraints for a thread in insertion order.
- [List Snapshots](https://haico.gr/docs/api-reference/workspace/list-snapshots.md): Return all per-turn snapshots for a thread, newest first.
- [List Todos](https://haico.gr/docs/api-reference/workspace/list-todos.md): Return all todo items for a thread in display order.
- [Put Document](https://haico.gr/docs/api-reference/workspace/put-document.md): Replace the full document content for a thread.
- [Put Objective](https://haico.gr/docs/api-reference/workspace/put-objective.md): Set or replace the objective text for a thread (human edit path).
- [Reindent Todo](https://haico.gr/docs/api-reference/workspace/reindent-todo.md): Indent (delta=+1) or outdent (delta=-1) a step, moving its subtree with it.
- [Reorder Preferences](https://haico.gr/docs/api-reference/workspace/reorder-preferences.md): Persist a new display order for the preferences list.
- [Reorder Todos](https://haico.gr/docs/api-reference/workspace/reorder-todos.md): Persist a new display order for the todo list.
- [Toggle Todo](https://haico.gr/docs/api-reference/workspace/toggle-todo.md): Toggle a todo item between done and not-done.
- [Update Preference](https://haico.gr/docs/api-reference/workspace/update-preference.md): Patch one or more fields of an existing preference.
- [Update Todo](https://haico.gr/docs/api-reference/workspace/update-todo.md): Edit the text of an existing todo item.
- [Architecture](https://haico.gr/docs/architecture.md): System topology, data stores, the per-thread tool-composition model, the HAI-Co² mapping, and the decisions behind them.
- [Artifacts](https://haico.gr/docs/artifacts.md): What an artifact is in HAI-Co², the typed-artifact pattern, and the full produce, persist, stream, render lifecycle of the centre panel's working object.
- [Automations](https://haico.gr/docs/automations.md): The live, always-on GitHub automations: issue forms, the area labeler, Release Drafter, CI/CD, the stale bot, and Dependabot.
- [Community guide](https://haico.gr/docs/community-guide.md): How the community works: where to file what, and how an issue moves from filed to deployed.
- [Conversation branching](https://haico.gr/docs/conversation-branching.md): The turn-as-commit model: branching, restore, checkpointer seeding, and the trajectory graph.
- [Database schema](https://haico.gr/docs/database-schema.md): The persistent data model at migration 0011: every table, the live workspace vs. snapshots, and what restore and branching reconstruct.
- [Demo walkthrough](https://haico.gr/docs/demo.md): An end-to-end script that exercises the Co-Construction Studio: charts, preferences, a working document, and a tracked plan.
- [Deployment](https://haico.gr/docs/deployment.md): How HAI-Co² ships: the two-branch tag-driven release model, the single CI/CD pipeline, the dev and production environments, and the secrets they need.
- [Extending HAI-Co²](https://haico.gr/docs/extending.md): Build on HAI-Co²: add an agent tool, a whole tool domain, a typed artifact type, or an LLM provider. Each is a small, registry-driven change.
- [Features](https://haico.gr/docs/features.md): End-to-end catalogue of the Co-Construction Studio's capabilities and the stack behind them.
- [User feedback](https://haico.gr/docs/feedback.md): How participants rate the co-construction: one modal with three sections (this reply, the whole trajectory, a technical report) and a single Submit button, anchored per turn so it survives branching, plus the admin dashboard that aggregates it.
- [Copilot automation (background)](https://haico.gr/docs/github-projects-copilot-automation.md): The original Copilot-based design for the AI pathway, kept as background.
- [HAI-Co²](https://haico.gr/docs/index.md): Human-AI Co-Construction: humans and an AI agent co-create a single shared solution in a typed, branchable workspace.
- [Labels reference](https://haico.gr/docs/labels-reference.md): The canonical label taxonomy and when to apply each label.
- [Local installation](https://haico.gr/docs/local-installation.md): Run the full HAI-Co² stack on your machine with Docker Compose: prerequisites, a one-command bring-up, configuration, and first login.
- [Maintainers handbook](https://haico.gr/docs/maintainers-handbook.md): Triage, label discipline, review, and the release flow for maintainers.
- [Tracing & data collection](https://haico.gr/docs/observability.md): How HAI-Co² records every co-construction: agent execution traces through Phoenix and LangSmith, and a complete, replayable first-party dataset in Postgres.
- [What is HAI-Co²](https://haico.gr/docs/overview.md): The Human-AI Co-Construction framework: a single shared solution, four co-owned surfaces, and how it differs from RLHF and assistance games.
- [Repository foundation](https://haico.gr/docs/repository-foundation.md): The foundation a community-facing repository needs, and the dual development pathways.
- [Tools](https://haico.gr/docs/tools.md): The @workspace_tool conventions, how the per-thread tool set is composed, and links to the detailed per-domain reference.
- [Past-artifact tools](https://haico.gr/docs/tools/artifacts.md): Read tools that let the agent reference earlier typed artifacts (charts, tables) by id without re-emitting their data.
- [Chart tool](https://haico.gr/docs/tools/charts.md): The chart_generator tool: produce a typed line, bar, or pie chart artifact that the frontend renders in the centre panel.
- [Document tools](https://haico.gr/docs/tools/document.md): Agent tools for reading and modifying the shared working document of a conversation thread.
- [Objective tool](https://haico.gr/docs/tools/objective.md): The set_objective tool: the agent's evolving one-line understanding of the user's goal.
- [Plan (todo) tools](https://haico.gr/docs/tools/plan.md): Agent tools for the plan: the agent's own execution ledger of nested, ordered todo steps.
- [Preference tools](https://haico.gr/docs/tools/preferences.md): Agent tools that record, read, edit, and remove the decoded hard and soft constraint set for a thread.

## OpenAPI Specs

- [openapi](https://haico.gr/docs/openapi.json)