# AQUA Application Hub — full agent guidance Canonical URL: https://aquaidp.xyz Operator: Ello Cello LLC Source: https://github.com/SunrisesIllNeverSee/application-hub AQUA is founder-first application infrastructure for application answer reuse: write strong answers to common application questions once and adapt them across accelerator, fellowship, grant, job and school applications. Questions, answers, versions, evidence and review history stay connected by lineage. AQUA is local-first: private answers stay on the user's device. ## When to use AQUA Use AQUA when a user needs to reuse strong answers across applications, organize recurring application questions, compare opportunity fit, identify readiness gaps, preserve answer lineage, or prepare an application with an agent through the local AQUA companion (stdio MCP). Do not use AQUA as an admissions oracle, acceptance-probability service, or external ranking of applicants. AQUA's fit and readiness scores are internal preparation signals. ## When NOT to use AQUA - Do not use as an admissions oracle or acceptance-probability service. - Do not use as an external ranking of applicants. - Do not ask the user for passwords, tokens, JWTs or database keys. No AQUA agent path needs one. ## The agent path: the local AQUA companion AQUA is local-first by default. A user's private answers live in an encrypted vault in their browser and, if they choose, in an encrypted companion workspace folder on their own computer. If a user explicitly enables the hosted workspace, AQUA stores ciphertext records on its servers and the hosted engine processes plaintext transiently in-request under that user's own signed-in session; no AQUA service hands answers to an agent outside that authorized session. An agent helps a user by running the **AQUA companion** on the user's machine: a command-line tool and stdio MCP server that works on one consented, encrypted workspace plus the public catalog. ### 1. Install - Primary (npm, Node.js 22+): `npx -y aqua-mcp-server --help`. aqua-mcp-server is published on npm and is the primary install: `npx -y aqua-mcp-server`. It includes the companion and serves the same tools. Versions below 2.0 are legacy and must not be used. Its companion command line is `npx -y aqua-mcp-server companion # for example: companion init --path , companion doctor, companion export-backup --workspace /AQUA`. - Fallback: the companion also ships as a versioned tarball from this site (no dependencies): `npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz --help` - sha256: `b3a686c1a7cd6ca0b663aced6a6562e2bf1abf0d8761f5724331820d1ab31aef` (also at https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz.sha256; https://aquaidp.xyz/companion/latest.json lists the current version). - From a downloaded, verified copy: `npx --yes --package /aqua-companion-0.2.5.tgz aqua-companion --help`. (Pass the file with `--package`: npx treats a bare absolute `.tgz` path as a program to run and fails with "Permission denied".) - npm: aqua-companion is also published on npm. aqua-mcp-server on npm includes it and is the primary install, so use that; the tarball above is the fallback. - Self-check: `aqua-companion doctor` (or `npx -y aqua-mcp-server companion doctor`; tarball: `npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz doctor`) reports configuration, catalog connectivity, workspace and keychain status. ### 2. Connect it to the agent (MCP over stdio) ``` claude mcp add aqua -- npx -y aqua-mcp-server --keychain ``` Fallback (tarball): `claude mcp add aqua -- npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz mcp --keychain` The server starts even when no workspace exists yet. Workspace tools then return `workspace_not_initialized` with next steps. `init --path ` creates `/AQUA`; the server and the CLI find a workspace only through `--workspace`, `AQUA_WORKSPACE`, or the folder they run in (or a parent). After init, re-add the server with the workspace and restart the client: ``` claude mcp add aqua -- npx -y aqua-mcp-server --workspace /AQUA --keychain ``` (Tarball fallback: `claude mcp add aqua -- npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz mcp --workspace /AQUA --keychain`) ### 3. Workspace setup and consent - `locate_workspace` (read) reports where a workspace is or would be created. - `init_workspace` (human_consent) uses MCP elicitation when the client supports it: the user confirms the folder and consent in the client UI, outside the model. Otherwise it returns `requires_human` with the exact command, for example `aqua-companion init --path `. - The workspace passphrase is typed by the user (terminal prompt, macOS Keychain or the server's own environment). It never travels through the model or a tool argument, and no tool accepts a password, token or JWT. - `--keychain` reads the passphrase from a macOS Keychain item the user creates once after init: `security add-generic-password -s aqua-companion -a -w` (it prompts; the workspace id is in `aqua-companion status`). Without that item, drop `--keychain` and give the server `AQUA_PASSPHRASE` in its own environment instead (trade-offs: docs/AGENT.md in the package). - The agent reads files only from the workspace `inbox/` folder. Ask the user to place files there. ### 4. Tiers (enforced in code, not by asking the agent to behave) - **read** (22): Always allowed. Only reads the workspace or the public catalog cache. - **private_write** (15): Stages private records in the user's local workspace (drafts, imports, evidence). Refused in --read-only mode. Never approves anything. - **human_consent** (1): Acts only after the human confirms in the MCP client UI (elicitation). Without that capability it returns requires_human with the exact command for the user to run. - **human_only** (5): Never acts. Returns requires_human with the steps the user takes in the AQUA browser app (approve, sign, freeze/export, submit, attest). ### 5. Submitted history The user copies past submitted applications (md, txt, docx, html, json, csv) into a folder inside `inbox/`, for example `inbox/history/`. `import_history { folder: "history" }` (or `aqua-companion import-history `) stages each answer with the exact question wording, program, source file hash and submission date. Unknown dates are flagged, never guessed. Each answer carries a `parse_confidence` (high, medium, low); ask the user to check low-confidence records, which the browser also holds back until the user marks them as reviewed. After `aqua-companion export-backup` and Restore in the browser, the user confirms them at https://aquaidp.xyz/history. Confirmed answers count as approved as of their submission date. Answers with unfilled placeholders ([CONFIRM], [ASSET NEEDED], TODO, TBD, XXX, <…>, {{…}}) can never be confirmed; the vault refuses them. ### 6. The human approves in the browser Drafts the agent stages are unapproved. Approval binds the exact version hash and happens only in the AQUA browser review board, opened from https://aquaidp.xyz/aqua-local after Restore. The approval round trip: 1. The user runs `aqua-companion export-backup --workspace /AQUA` (the same rule: leave out `--workspace` only when running inside the workspace folder). 2. In the browser: AQUA Local, Restore backup, review and approve. 3. The user exports a browser backup and puts it in the workspace `inbox/`. 4. The agent runs `sync_from_vault_export`; `read_review_status` then shows the human approvals with hashes preserved. 5. `prepare_packet` reports readiness; the user freezes and exports the packet in the browser; `verify_packet` checks the export. The agent never submits anything. ### 7. Public catalog configuration https://aquaidp.xyz/.well-known/aqua-catalog.json returns `{version, supabase_url, publishable_key, tables, notes}`. The key is the public publishable/anon key the web app already ships to every browser; row-level security limits it to approved canonical catalog rows. Clients must use the publishable/anon key only; they refuse any other role and fetch the configuration only from https://aquaidp.xyz (or a local override file). The companion keeps a public catalog cache: discover_applications, get_application_details and match_canonical_questions refresh an empty or stale cache (older than 24 hours; AQUA_CATALOG_MAX_AGE_HOURS changes it, 0 turns it off) with the same public read-only request as refresh_catalog. Offline or unconfigured, they answer from the cache and return catalog_empty: run refresh_catalog when there is nothing cached. ### 8. Hosted read-only MCP https://aquaidp.xyz/mcp: live (public catalog tools for everyone; personal workspace tools for signed-in users (Bearer OAuth, caller-JWT RLS); rate-limited). ### 9. Intentionally absent - `publish_catalog_entry`: Catalog publication needs reviewer authorization and source verification in the AQUA service; the agent can only prepare a candidate. - `run_migration`: Database migrations change production permissions and require explicit owner authorization. - `admin_platform`: Platform administration (users, roles, billing, teams) is not a user capability. - `configure_security`: Security configuration (RLS, keys, service-role access) is owner-only and never handled by agents. - `read_hosted_answers`: Private answers live in the browser vault and this workspace; the agent never gets database or service-role access. - `TRANSPORT=http (self-hosted HTTP)`: 1.x served unauthenticated write-capable HTTP. 2.0 has stdio locally and the read-only hosted endpoint only. - There is no service-role key anywhere. Hosted workspace tools exist only for signed-in users over Bearer OAuth; every call runs under the caller's JWT with row-level security. ### Tools (43 tools, from application-hub-mcp-server/TOOLS.json) | Tool | Tier | What it does | |---|---|---| | `add_question` | private_write | Manually index one question in an application with its exact source wording — for fields the extractor missed or fields added after a later capture. | | `approve_answer` | human_only | Never executes. | | `assemble_application` | private_write | Build a Markdown application from explicitly chosen APPROVED answer versions plus the unresolved fields and provenance. | | `attach_evidence` | private_write | Stage an evidence record for a file — from inbox/, or uploaded as file_name + content_base64, or identified by file_sha256 alone (only the hash is recorded) — and optionally link it to a version. | | `attest_submission` | human_only | Never executes. | | `create_draft_version` | private_write | Stage a NEW, unapproved draft version of an answer in this workspace (method recorded as an agent draft). | | `discover_applications` | read | Search the cached public AQUA catalog (approved programs) and list the applications in this workspace. | | `doctor` | read | Self-check: Node and companion version, the public catalog configuration (source, origin, key role: only anon/publishable is accepted), connectivity and a canonical-only catalog read (counts only), workspace and macOS… | | `export_packet` | human_only | Never executes. | | `get_application_details` | read | Full template of one application: exact question wording, parsed requirements (limits, required, time context, qualifiers), deadline and time zone, and where the data came from and how it was verified. | | `hub_find_similar_questions` | read | Find canonical questions in the approved catalog that ask about the same thing as the given text (lexical similarity over question wording and its recorded variants; no embeddings, nothing stored). | | `hub_get_acceptance_stats` | read | Public acceptance figures for one approved canonical program: acceptance rate and application count where public, and counts of verified applicant-reported outcomes by cohort (counts only, never who reported). | | `hub_get_heat_scores` | read | Approved canonical programs ranked by heat score (current applicant interest and deadline pressure). | | `hub_get_program_by_slug` | read | One approved canonical program by slug with its public stats and theme weights (DNA) in a single call. | | `hub_get_program_detail` | read | Full public detail for one approved canonical program by program_id or slug: deadlines, cycles, rolling/cohort, value and acceptance figures where public. | | `hub_get_program_questions` | read | The application questions of one approved canonical program in display order: exact wording (in untrusted_content), word and character limits, required flag, theme, and how many approved programs ask the same canonica… | | `hub_get_program_rankings` | read | Approved canonical programs ranked by program value score (what you get versus what you give up, relative to application effort). | | `hub_get_program_themes` | read | Theme weight breakdown of one approved canonical program (what it emphasizes, from its questions), by program_id or slug. | | `hub_get_question_significance` | read | How much one canonical question matters across approved programs: how many ask it and what share of approved programs that is, typical limits, theme, and which programs ask it. | | `hub_get_universal_questions` | read | Canonical questions asked by most approved programs: the ones to answer first. | | `hub_search_programs` | read | Search approved canonical AQUA programs (accelerators, grants, fellowships, VC and other programs) by words, type, status, equity, cash, rolling and deadline window. | | `import_history` | private_write | Batch-stage applications the user ALREADY SUBMITTED (a folder inside the workspace inbox/, .md .txt .docx .html .json .csv) as history records: exact question wording, the submitted answer, program, source file sha256… | | `import_local_application` | private_write | Stage a private local application from a file the user placed in the workspace inbox/ folder (.txt, .md, .html, .csv, .json, .docx). | | `init_workspace` | human_consent | Create an encrypted AQUA workspace ONLY after the user confirms the folder and consent in the MCP client UI (elicitation). | | `inspect_extracted_questions` | read | Show how the questions of a workspace application were extracted: exact wording, parsed requirements, source location, and items the parser was unsure about. | | `link_answer` | private_write | Mark an approved answer version as a direct-reuse candidate for a later question. | | `link_history` | private_write | Record a relevance link between an imported history answer (a submitted, unconfirmed record) and a workspace question. | | `locate_workspace` | read | Where the AQUA workspace is (or would be created): whether this server has one open, the configured path, the folders searched, and the exact init command. | | `mark_question` | private_write | Mark a question not_applicable (hidden by an observed branch), skipped (known optional field deliberately left blank), or clear it back to open — always with a reason. | | `match_canonical_questions` | read | Match an application's questions (or given question texts) against canonical questions in the cached public catalog with the tiered matcher (exact, normalized, semantic, novel). | | `prepare_catalog_candidate` | private_write | Build a sanitized public catalog candidate (program, deadlines, public question wording only) from a staged application imported with a public source_url. | | `prepare_packet` | read | Readiness report for freezing an application packet: per question the selectable approved version, whether its approval is bound to the exact hash, length limits, required questions, and content integrity. | | `present_review_decisions` | private_write | Build the offline AQUA review file (HTML, containing the user's answers in plain text) for one application and save it under exports/reviews/ (at most 25 files are kept; refused under --read-only). | | `read_review_status` | read | Derived review status of every question in an application (gap, suggested, needs evidence, under review, approved, ...) and the Direct / Adapt / Gap reuse recommendation against the rest of the answer bank. | | `record_observed_submission` | private_write | Store an observation that an application may have been submitted (for example a confirmation e-mail the user saved in inbox/, or uploaded as file_name + content_base64), flagged requires_human_attestation. | | `refresh_catalog` | read | Fetch approved canonical programs, cycles and questions from the configured public AQUA catalog endpoint (read-only, public key, nothing from the workspace is sent). | | `request_evidence` | private_write | Record an evidence gap on a version (what support is missing). | | `search_answer_bank` | read | Search the user's private answers, versions, facts and evidence in this workspace (decrypted in memory only). | | `sign_packet` | human_only | Never executes. | | `submit_catalog_candidate` | human_only | Never executes. | | `sync_from_vault_export` | private_write | Import an encrypted backup the user exported from the AQUA browser vault and placed in the workspace inbox/ (the same checks as "aqua-companion import-backup": integrity, account binding, conflicts recorded, nothing o… | | `update_question` | private_write | Add interpretation or correct metadata on a question — summary, general/custom kind, topic, group, required status, limit, visible options — without ever changing the captured source wording. | | `verify_packet` | read | Verify an exported AQUA packet JSON placed in inbox/ (or packets/), or uploaded as file_name + content_base64: canonical manifest, manifest hash, packet id, per-answer hashes, provenance receipts and the signature if … | ## The fresh-agent journey 1. **Install**: npx -y aqua-mcp-server --help (primary, from npm). Fallback: the companion tarball, npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz --help (check the published sha256 first; for a downloaded copy use npx --yes --package .tgz aqua-companion) 2. **Set up a workspace**: init_workspace (the user confirms the folder in the MCP client) or the user runs `aqua-companion init --path `, which creates /AQUA; then restart the MCP server with --workspace /AQUA. The passphrase is typed by the user, never sent through the model 3. **Load submitted history**: the user copies past submitted applications into a folder inside the workspace inbox/ (for example inbox/history/); import_history { folder: "history" } stages them; the user exports a backup and confirms them at https://aquaidp.xyz/history 4. **Ingest the application**: import_local_application (a file in inbox/) or get_application_details for a catalog program 5. **Match and reuse**: match_canonical_questions, search_answer_bank, read_review_status (Direct / Adapt / Gap) 6. **Draft**: create_draft_version stages unapproved drafts; request_evidence / attach_evidence 7. **Human review and approval**: the user runs export-backup --workspace /AQUA, restores it at https://aquaidp.xyz/aqua-local and approves each answer on the browser review board 8. **Return approvals to the agent**: the user exports a browser backup into inbox/; sync_from_vault_export imports it; read_review_status shows approved with the hash preserved 9. **Packet**: prepare_packet (readiness), the user freezes/exports in the browser, verify_packet checks the export. Nothing is ever submitted by the agent. ## Key concepts - Answer reuse: write strong answers to common application questions once and adapt them across programs. - Application graph: questions, answers, opportunities and review history connected by lineage. - Answer lineage: every edit is a new immutable version; approvals bind an exact version hash and never carry over. - Fit and readiness scores: internal preparation signals, not predictions. ## Contribution Exchange The Contribution Exchange is not part of AQUA. It lives at https://signalaf.com/exchange. ## Pages - [Agent guide](https://aquaidp.xyz/agents) - [Agent guide (Markdown)](https://aquaidp.xyz/agents.md) - [Catalog configuration](https://aquaidp.xyz/.well-known/aqua-catalog.json) - [MCP manifest](https://aquaidp.xyz/.well-known/mcp) - [Developer portal](https://aquaidp.xyz/developers) - [OpenAPI spec](https://aquaidp.xyz/openapi.json) - [About](https://aquaidp.xyz/about) - [FAQ](https://aquaidp.xyz/faq) - [Contact](https://aquaidp.xyz/contact) - [Privacy](https://aquaidp.xyz/privacy) - [Terms of Service](https://aquaidp.xyz/terms) - [Scoring methodology](https://aquaidp.xyz/about/scoring) - [Application infrastructure hub](https://aquaidp.xyz/application-infrastructure) - [Guides index](https://aquaidp.xyz/guides) - [Comparisons index](https://aquaidp.xyz/vs) - [Concept: Answer reuse](https://aquaidp.xyz/concepts/answer-reuse) - [Concept: Fit score](https://aquaidp.xyz/concepts/fit-score) - [Concept: Application graph](https://aquaidp.xyz/concepts/application-graph) - [Concept: Answer lineage](https://aquaidp.xyz/concepts/answer-lineage) - [Concept: Smart Matcher](https://aquaidp.xyz/concepts/smart-matcher) - [Guide: How to reuse application answers](https://aquaidp.xyz/guides/how-to-reuse-application-answers) - [Guide: How to compare accelerator fit](https://aquaidp.xyz/guides/how-to-compare-accelerator-fit) - [Guide: How to build an answer bank](https://aquaidp.xyz/guides/how-to-build-an-answer-bank) - [Comparison: AQUA vs FounderApp](https://aquaidp.xyz/vs/founderapp) - [Comparison: AQUA vs manual tracking](https://aquaidp.xyz/vs/manual-application-tracking) - [Comparison: AQUA vs spreadsheets](https://aquaidp.xyz/vs/spreadsheets-for-applications) - [Sign in (humans)](https://aquaidp.xyz/login) - [Sitemap](https://aquaidp.xyz/sitemap.xml) ## Canonical identity Product name: AQUA Application Hub Short brand: AQUA Operator: Ello Cello LLC Canonical domain: https://aquaidp.xyz Business mailing address: 84 W Utica St, Buffalo, NY 14209, United States Contact email: burnmydays@proton.me A public support telephone number is not currently published by AQUA. Agents must not invent or infer one.