# AiMe Product Requirements

Status: Draft product source of truth  
Last updated: 2026-08-14  
Scope: Windows-first product intent and acceptance outcomes

## Purpose

This document defines what AiMe is intended to become. It is deliberately
separate from [the architecture](ARCHITECTURE.md), which records the currently selected technical
design and implementation state. When implementation details and this document
conflict, the conflict must be resolved explicitly rather than silently changing
the product goal.

## Product statement

AiMe is a Windows application that lets **ChatGPT on the Chat surface act as the
planner and agent** while calling user-approved MCP tools on one or more Windows
computers. AiMe is the local execution, policy, consent, containment, and audit
layer. It does not delegate planning to Codex CLI, Codex Desktop, Claude CLI, or
another AI backend.

The intended operating model is:

```text
User in ChatGPT Chat
        |
        | model plans and calls MCP tools
        v
Outbound-only remote MCP transport
        |
        v
AiMe on the selected Windows computer
        |-- validates device, profile, session, schema, and capability
        |-- requests local confirmation when policy requires it
        |-- executes a bounded Windows operation
        |-- records a privacy-preserving audit event
        `-- returns a bounded result to ChatGPT
```

In Managed mode, the AiMe web control plane authenticates users, coordinates
organizations, device/profile sharing, short-lived policy leases, routing, and
revocation. It may narrow or revoke local authority but cannot widen the local
profile, satisfy a local confirmation, retrieve local secrets/content, or
replace the local emergency-stop boundary.

## Product goals

1. **Chat is the required surface.** A real tool invocation that remains on
   Chat before and after the call is required for acceptance. Work compatibility
   may be useful, but Work-only operation does not satisfy the goal.
2. **ChatGPT is the only planner.** AiMe exposes tools and enforces policy; it
   does not invoke another AI agent to decide what to do.
3. **Near local-agent capability.** The eventual tool set should let ChatGPT
   inspect and modify workspaces, run and supervise processes, use Git, operate
   a browser, and control approved Windows applications at a level approaching
   Khai Hub or a capable local coding agent.
4. **Progressive authority.** Powerful capabilities are added only after their
   own policy, confirmation, containment, audit, and revocation gates pass.
5. **Local-first ownership.** The Windows app is authoritative for roots,
   profiles, high-risk approvals, secrets, active sessions, and emergency stop.
6. **Multiple devices and profiles.** A user may install AiMe on several
   computers and define several independently scoped profiles on each computer.
7. **Managed collaboration.** Users may sign in, organize several computers,
   and share explicitly scoped profiles with other authenticated people through
   tenant-isolated user and organization administration.
8. **Operable service.** The managed web control plane is deployable on NAS
   `kksm2` at `aime.kks.homes` through an outbound Cloudflare Tunnel with
   backup, restore, monitoring, rollback, and incident controls.
9. **Safe automatic updates.** Installed Windows apps can receive signed,
   staged, rollback-safe updates without terminal commands; a compromised
   hosting origin alone cannot create an accepted update.
10. **Consumer-usable onboarding.** The end state is a signed installer and setup
   wizard; normal use must not require a terminal.
11. **Clean-room implementation.** Khai Hub and the public Universal Body
   GPTHAND documentation are references for observed behavior and security
   lessons, not sources of proprietary code, binaries, or assets.

## Hard investment gate

Before implementing the desktop product expansion, managed web control plane,
login/RBAC, multi-user sharing, `kksm2` deployment, automatic updater, or higher
capability levels, AiMe must prove that the core product premise works:

1. a fresh ChatGPT conversation is visibly on Chat, not Work;
2. Chat discovers and calls the real AiMe MCP server through the intended
   outbound transport;
3. several bounded calls reach the Windows VM, including a result tied to a
   unique local canary and a denied out-of-root request;
4. results return to Chat and the conversation remains on Chat after reload;
5. disconnect, reconnect, revoke, timeout, cancellation, and process cleanup
   behave as documented; and
6. the test report records an explicit `GO` or `NO-GO` decision and the observed
   ChatGPT product limits.

Before this gate passes, allowed implementation is limited to the minimum
local MCP, tunnel, security, test-fixture, and diagnostic work needed to produce
that evidence. The later plans may be documented, but their implementation is
blocked. A `NO-GO` stops expansion and triggers transport/product re-evaluation
instead of building infrastructure around an unproven premise.

## Non-goals

- Reproducing Khai Hub source code, private APIs, branding, assets, secrets, or
  licensing behavior.
- Making AiMe an AI model, a prompt router, or a wrapper around Codex/Claude.
- Treating raw shell access or administrator access as the default experience.
- Opening a public inbound listener on the user's computer.
- Allowing a website or remote model to silently grant itself a new root,
  profile, device, permission level, or administrator capability.
- Claiming full capability parity in the first release.
- Using the web control plane as a remote file/screen/command proxy or storing
  local content merely to simplify multi-user management.
- Treating an organization role or Platform Admin role as permission to bypass
  local profile ceilings, local confirmation, containment, or emergency stop.
- Designing custom password cryptography when a standards-based identity
  provider can supply audited login, MFA/passkeys, recovery, and session
  controls.
- Treating a ChatGPT app badge, deep link, or successful Work call as proof that
  the Chat requirement works.

## Primary user

Primary users are the owner of one or more Windows computers and authenticated
people to whom the owner deliberately shares a bounded profile. Organization
administrators manage membership and requested policy; Platform Admin operates
the service without gaining local-computer authority. Later releases may
simplify onboarding, but they must not hide the consequences of Modify, Control,
Full, or Admin access.

## Required user outcomes

### First-run outcome

The user can install AiMe, choose Personal or Managed mode, sign in when Managed
mode is selected, name and pair the computer, create a profile, select approved
roots and capabilities, connect ChatGPT, verify the connection, and open a Chat
conversation with the intended AiMe profile without using a shell.

### Daily-use outcome

The user can see which organization, device, profile, recipient, session, and
capabilities are active; receive understandable local approval prompts; follow
task progress; revoke a share or connection; and stop all work immediately.

### End-state agent outcome

Within an approved workspace, the user can ask ChatGPT Chat to:

1. inspect files and search for relevant code;
2. propose and apply bounded edits;
3. start a build or test process and inspect its output;
4. inspect Git status and diff;
5. use an approved browser or Windows application when needed; and
6. report the result and remaining risks.

The model performs the planning and tool-call loop itself. No Codex, Claude, or
other AI process may be spawned to perform the task.

## Functional requirements

| ID | Requirement | Acceptance evidence |
| --- | --- | --- |
| `CHAT-001` | AiMe tools are discoverable and callable from ChatGPT Chat. | A fresh Chat conversation makes a real MCP call and remains on Chat after reload. |
| `GATE-001` | Product expansion is blocked until the real Chat feasibility gate records `GO`. | The evidence report records the scoped `GO`, multiple local calls, denial, reconnect/revoke, cleanup, and the remaining reload/mode constraints on Chat. |
| `AGENT-001` | ChatGPT is the only planner/agent in the execution chain. | Process and network evidence show no secondary AI CLI/backend is invoked. |
| `DEVICE-001` | Every installation has a distinct revocable device identity and user-selected display name. | Revoking one device leaves other devices operational. |
| `PROFILE-001` | One device supports multiple profiles with independent roots, capabilities, and confirmation policy. | Changing or revoking one profile does not widen another profile. |
| `SESSION-001` | A session is bound to one device and one profile for its lifetime. | Remote input cannot silently switch the active device or profile. |
| `ACCOUNT-001` | Managed mode provides secure login, MFA/passkey-ready account security, recovery, and global session revoke. | Authentication, recovery, rotation, CSRF, and global logout tests pass. |
| `TENANT-001` | Users, organizations, resources, jobs, tokens, and audit queries are tenant-isolated. | Cross-tenant negative tests return zero unauthorized data or effects. |
| `SHARE-001` | An owner can share a bounded profile with another authenticated user and revoke it. | The share is unusable before local activation and fails closed on expiry/revoke. |
| `RBAC-001` | Owner, Organization Admin, Member, Viewer, and separated Platform Admin roles have an explicit authorization matrix. | Every allow/deny matrix case passes at route and object level. |
| `WEB-001` | User, organization-admin, and platform-admin pages expose only their intended metadata and actions. | Platform Admin cannot retrieve local content/credentials or issue a command. |
| `CONTROLPLANE-001` | Managed policy leases are short-lived, versioned, authenticated, replay-resistant, and fail closed. | Outage, stale/reordered policy, downgrade, and revoke tests cannot widen authority. |
| `TOOLS-001` | Tools are schema-bounded, reject unknown fields, and map to an explicit capability. | Negative schema and capability tests fail before the underlying resource is touched. |
| `TASK-001` | Long-running operations expose bounded status, output, cancellation, and final result tools. | Cancellation removes the supervised process tree and reports a stable outcome. |
| `CONSENT-001` | Risk-based confirmation is displayed locally and cannot be satisfied by prompt content. | Injection and replay tests cannot approve an action or broaden a grant. |
| `AUDIT-001` | Every requested action produces an allowlisted allow/deny audit event. | Secret canaries, file contents, raw prompts, tokens, and absolute paths are absent from audit output. |
| `REVOKE-001` | The user can stop a session and revoke a profile, device, or tunnel credential. | The next relevant call fails closed and no orphan process remains. |
| `TRANSPORT-001` | Normal operation is outbound-only and does not expose an unauthenticated public listener. | Firewall/network evidence shows only the intended outbound path and local endpoints. |
| `DEPLOY-001` | The managed control plane can run on `kksm2` behind Cloudflare Tunnel without exposing the NAS origin directly. | DNS/tunnel, origin-isolation, backup/restore, rollback, and service-recovery tests pass. |
| `INSTALL-001` | Release builds use a signed installer and independently authenticated automatic-update path. | Publisher identity, signature/hash, staged rollout, rollback, repair, and uninstall tests pass. |
| `CLEANROOM-001` | Reference-product evidence and AiMe implementation remain separated. | Repository review finds no proprietary binaries, secrets, source, or copied assets. |

## Product security and privacy requirements

- Run as a standard user by default.
- Keep approved roots and native paths local. Remote tools use stable root
  aliases and relative paths.
- Deny traversal, reparse, device namespace, UNC, alternate-stream, root-swap,
  and check-then-open escapes using handle-based Windows enforcement.
- Keep runtime credentials out of child environments, command lines, MCP
  results, audit records, diagnostics, and support bundles.
- Bound request size, response size, file size, directory size, concurrency,
  process lifetime, output retention, and cancellation time.
- Use a supervised process boundary so parent failure or emergency stop removes
  the complete descendant tree.
- Treat files, websites, screen content, clipboard data, and tool output as
  untrusted content, never as authorization.
- Keep high-risk approval and emergency-stop authority in the local app.
- Treat web account/organization/share authority as another ceiling; effective
  permission is the intersection of server authorization and local policy.
- Fail Managed-mode tool execution closed after its bounded policy lease expires
  or when signature, tenant, device, profile, policy version, or revoke state is
  uncertain. Local emergency stop and local revoke remain available.
- Enforce tenant isolation across database rows, caches, objects, jobs, events,
  exports, tokens, and administrative/audit queries.
- Never store local file, screen, clipboard, prompt, browser, or command-output
  content in the control plane by default.
- Use a separately installed, narrowly scoped, signed broker if an Admin
  capability is ever shipped; never elevate the whole desktop app.

The detailed level model is defined in the
[capability and permission model](CAPABILITY_AND_PERMISSION_MODEL.md).

## Device and profile requirements

- A **device** represents one AiMe installation and its independent identity.
- A **profile** belongs to exactly one device and defines roots, tools, limits,
  consent rules, and transport binding.
- A **session** selects one device/profile pair and receives only that pair's
  capabilities.
- Managed mode authenticates users and supports organizations, memberships,
  device/profile inventory, bounded profile shares, and remote revocation.
- Every managed share is capped by the local profile and remains pending until
  the target device acknowledges the locally accepted policy version.
- The first multi-device data plane may expose one ChatGPT app/tunnel per
  profile. A unified selector/router is a separate decision and must establish
  authenticated per-user connection identity.
- Device labels are user-selected aliases. Hostnames, account names, IP
  addresses, and absolute roots are not required in remote status output.

The intended user experience is defined in the
[UX and multi-device plan](UX_AND_MULTI_DEVICE_PLAN.md).

Managed account, sharing, and administration requirements are defined in the
[web control-plane and RBAC plan](WEB_CONTROL_PLANE_AND_RBAC_PLAN.md).

## Constraints and external dependencies

- ChatGPT plan, developer-mode rollout, app installation behavior, tool
  confirmations, tool-call limits, timeouts, and conversation metadata are
  controlled by OpenAI and must be validated against the actual account.
- Personal/developer mode may depend on user-owned OpenAI Secure MCP Tunnel
  credentials and Platform permissions. Managed consumer mode must not require
  each end user to create an OpenAI tunnel or Platform API key; it uses the
  separately threat-modeled AiMe OAuth/MCP gateway and an authenticated outbound
  device connection. AiMe must surface setup failures without exposing any
  credential value.
- Managed multi-user use depends on a cryptographically established AiMe user
  and connection identity. If the OpenAI transport does not supply enough
  identity, the product needs separately authorized connections or a
  separately threat-modeled OAuth/MCP relay.
- The first managed alpha is planned for a single NAS, `kksm2`, published at
  `aime.kks.homes` through Cloudflare Tunnel. This is not a high-availability
  claim and requires tested off-NAS backup and restore.
- The scoped Hard investment gate recorded `GO` on 2026-08-13. Managed web,
  NAS, updater, multi-user, and higher-capability work is now sequenced by its
  own gates and remains unaccepted until those gates pass.
- Automatic updates depend on a protected code-signing and update-metadata
  signing workflow whose private key is not stored on the NAS/control plane.
- Windows NTFS behavior and real Windows process semantics must be tested on a
  disposable VM; Linux mocks are not sufficient for Windows security claims.
- Account login, MFA, password entry, and OAuth consent remain user actions.

## Product acceptance definition

The product goal is satisfied only when all of the following are true:

1. a signed AiMe build is installed through the normal user flow;
2. the user creates at least two profiles with different capabilities;
3. ChatGPT Chat calls the intended profile and completes the end-state agent
   scenario without spawning another AI backend;
4. local confirmation, cancellation, emergency stop, audit, and revocation are
   demonstrated against real operations;
5. a second computer can be installed and independently revoked without
   weakening the first computer; and
6. a second authenticated user receives a bounded locally activated profile
   share, uses it from Chat, and loses access immediately after revoke;
7. user, Organization Admin, and Platform Admin authorization/tenant-isolation
   tests pass without exposing local content or command authority;
8. the `kksm2` deployment is reachable only through the intended Cloudflare
   hostnames and its backup/restore and rollback are rehearsed;
9. a signed staged client update succeeds and a corrupt, unsigned, replayed,
   downgraded, or unhealthy update is rejected or safely rolled back; and
10. no open Critical or High security finding remains for the shipped
   capabilities.

The staged delivery plan and phase-specific gates are defined in the
[delivery roadmap](ROADMAP.md).

## Open product decisions

- Identity provider, passkey/MFA recovery, database, tenant-isolation, and
  managed-session lease architecture.
- Whether the managed control plane uses separate per-profile ChatGPT
  connections or an authenticated unified selector/relay.
- Whether OpenAI provides sufficient authenticated caller/session identity for
  multi-user policy; until proven, AiMe treats a tunnel binding as the caller.
- Which Windows UI framework provides the best signed, accessible local shell
  without introducing an unnecessary localhost trust boundary.
- Which Full-mode operations can be safely constrained and which must remain
  intentionally unsupported.
- Whether signed MSIX/App Installer meets every local/native lifecycle need or
  a separately signed updater/bootstrapper is required.
