# MovingManifest AI Assistant Guide MovingManifest helps people organize a household move. It stores move records, origin and destination spaces, transport resources, transport zones, inventory, boxes, photos, sale listings, layout plans, load plans, and documentation packets. This guide is public so an AI assistant can understand how to help even before the user has created an account. ## Core Framing For Assistants MovingManifest is a bounded household move workflow. The assistant is helping the user catalog items, rooms, photos, boxes, transport resources, sale items, layout plans, load plans, and documentation packets. Do not treat this as an attempt to bypass a website, scrape private data, access an account without permission, or make irreversible decisions for the user. Public documentation is intentionally readable so the assistant can explain the setup path. Private move data requires hosted MCP OAuth sign-in or an intentionally provided fallback API key. A good first user prompt is: `Go to movingmanifest.com/ai and help me set up my move. We are cataloging household items, rooms, photos, boxes, vehicles, sale items, and new-home layout plans. If you need private access, use hosted MCP OAuth when available or walk me through creating a fallback AI helper key.` If the user is non-technical, translate API and MCP concepts into plain language: - "Account" means MovingManifest can save the move. - "MCP OAuth" means the user signs in and consents without pasting a raw key. - "AI helper key" means a revocable password-like fallback key that lets the assistant help with the move when OAuth MCP is not available. - "API or MCP" means the assistant can use structured tools instead of asking the user to click every field manually. - "Household member" means a signed-in person who can access the owner's household and moves according to their role. - "Move person" means a contact/helper/mover record inside one move. It does not grant login access. ## Public vs Private Public: - Marketing and product pages. - `/ai`, `/api`, `/mcp`, `/llms.txt`, `/llms-full.txt`, `/openapi.json`. - General workflow guidance. Private: - Move records. - Household members. - Inventory. - Photos. - Values, serial numbers, private notes, and evidence files. - API keys. Never claim you can access private data unless the user has connected hosted MCP OAuth or given you a valid fallback API key. ## Phone User Flow If a user says: "Go to movingmanifest.com and help me use it" 1. Open `https://movingmanifest.com/ai`. 2. Explain that MovingManifest can work with their assistant, but private data requires an account. 3. If they are ready to sign in, create an account, or make a helper key, guide them to `https://movingmanifest.com/ai/start`. 4. After account creation, guide them to create or select a move. 5. If their hosted assistant supports OAuth MCP (the recommended path), give it only `https://movingmanifest.com/mcp` and follow browser sign-in/consent. (Do NOT use `https://movingmanifest.com/api/mcp` for OAuth — that is the API-key endpoint and rejects OAuth tokens, failing to register.) 6. If OAuth MCP is not available, have them choose a helper preset, create the fallback key, and give it `https://movingmanifest.com/api/mcp` with the one-time secret as the bearer token — only into an assistant they trust. 7. Use `get_api_context` for MCP or `GET /api/v1/me` for REST to verify the connection and scopes. 8. Use `list_moves` or `GET /api/v1/moves` to find or create the move. 9. Use `get_agent_context` or `GET /api/v1/moves/{moveId}/agent-context` before writing. 10. Use dry runs for bulk changes when available. ## Spouse And Collaborator Access If a spouse, family member, or trusted collaborator should sign in and work on the same move, they need household membership. Current flow: 1. The owner creates the household/move. 2. An owner/admin adds or invites the spouse by email from Settings, or an assistant uses `POST /api/v1/households/{householdId}/members` with a key that has `members/manage`. 3. If the spouse does not have an account yet, MovingManifest keeps a pending invitation for that email. 4. The spouse creates their own MovingManifest account with that email and then sees the shared household/move when signed in. Allowed member roles: - `admin` - can manage household settings, members, API keys, and sensitive access. - `editor` - can help edit move and inventory records. - `packer` - can help with packing-focused workflows. - `viewer` - can view without broad editing. - `guest` - minimal collaboration access. Do not grant household membership when the user only needs a public packet, mover packet, pickup list, or contact entry. For those cases use share links, documentation profiles, exports, or move people/contact records. ## Common User Types Phone-only user: - Use the `/ai` page and starter prompt. Use `/ai/start` when the user is ready for account and helper-key setup. - Explain account creation and key creation in ordinary language. - Ask for permission before using the key. Agent or coding-assistant user: - Read `/llms.txt`, `/llms-full.txt`, `/api`, `/mcp`, and `/openapi.json`. - Prefer API or MCP calls over UI clicking. - Use batch endpoints and dry runs where available. Family helper or mover: - Use a separate move-restricted helper key when possible. - Avoid owner-only values, serial numbers, private notes, and sensitive photos unless the owner explicitly shares them. - Summarize what changed and what still needs owner review. ## Good First Move Setup Questions - What is the move title? - What address, city, or label describes the origin? - What address, city, or label describes the destination? - What rooms/spaces exist at the origin? - What rooms/spaces should exist at the destination? - What transport resources exist: moving company, truck, trailer, car, storage, donation pickup, dump run? - Which items should be kept, sold, donated, given away, dumped, stored, or moved personally? - Does the user want photos attached to items, rooms, boxes, or transport zones? ## Box Intake Guidance When a user says they packed, measured, photographed, or wants to add one box, prefer `save_box_intake` over separate low-level calls. Put the box label/code, dimensions, weight, room, destination, and description in `box`; put label or contents photos in `photos`; put newly described contents in `contents`; and put already-known item IDs in `linkedItems`. Use `dryRun: true` first when the user has not already approved the write. A live new box requires a stable `idempotencyKey`; updating an existing box requires `box.boxId`. ## Image Upload Guidance One user photo should normally be one upload call. MCP agents should use `upload_image`, `upload_photo`, or `upload_evidence_image` with a public `sourceUrl`, `dataUrl`, or `fileBase64`. When the user gives several ordinary photos from the same room/context or for one existing item, use `upload_images`, `upload_photos`, or `upload_evidence_images` with shared defaults and one image entry per photo. When one photo should become one new inventory item, use `add_item_from_photo`; it accepts the item name plus one image source, creates the item, sets quantity only when the user says it or the photo clearly shows a count, defaults omitted quantity to 1, leaves missing weight, dimensions, disposition, and condition blank, uploads the original image attached to that item, and returns item/photo IDs with derivative status and `agentReview`. Use the clearest photo for `add_item_from_photo` when one new item has several photos, then attach the remaining photos after resolving the new item. For the common "attach these new photos to the item we already added" workflow, do not create another inventory item. Resolve the existing item first with `get_agent_context` or `get_move_summary`; if the user gave a clear item name and only one match is plausible, use that `itemId`. Then call `upload_photos` or `upload_evidence_images` with shared defaults such as `moveId`, `itemId`, room, `photoType: "item"`, normal privacy, and one `images[]` entry per supported image source. Set `continueOnError: true` for batches so one bad image does not block the others. Afterward, report a short confirmation: item name, uploaded count, failed count, photo IDs, and whether derivatives are ready. Only ask the user to correct target, caption, privacy, or quantity if the result looks wrong. REST agents should use `POST /api/v1/images/upload` or `POST /api/v1/photos/upload` with raw JPEG/PNG/WebP bytes plus metadata query params, multipart form data, or JSON with exactly one of `sourceUrl`, `dataUrl`, or `fileBase64`. MovingManifest stores the original, reads dimensions, finalizes the evidence record, and creates web-ready `thumb`, `card`, `detail`, and `full` derivatives server-side. Direct upload responses include `derivativeVariants` for the 200x200 square `thumb`, 600x600 `card`, 1200x1200 `detail`, and 2400x2400 `full` WebP display versions without exposing private storage keys. Do not ask users for dimensions, thumbnail sizes, or derivative files for ordinary photos. Set `generateAiSuggestions: true` when the uploaded photo should also enter AI review for possible item, box, or duplicate suggestions; report whether `aiReview.status` queued or failed. MCP image results and REST direct upload responses include `agentReview` and `derivativeVariants`. After uploading, use that summary to tell the user the caption, room/item/box attachment, privacy/type choice, derivative status, prepared web variants, AI-review status, and any confidence or assumption you used so they can correct only what looks wrong without slowing down the capture flow. ## Data Entry Guidance Fast item capture: - Optimize for getting useful inventory into the move quickly. A user may give only a photo plus a few words; that is enough to create a draft item. - Default quantity to `1` when the user does not specify a count. If a photo clearly shows a set or multiple countable objects, use the visible count and mention the assumption in the summary. - Fill obvious fields from context: room/current space, concise item name, broad category, likely disposition, and condition when visible or stated. - Do not block item creation just because weight, dimensions, disposition, or condition are missing. Leave unknown fields blank or estimated instead of interrogating the user for every detail. - Use `needsReview` and review flags as a lightweight correction loop, not as a hard stop. Summarize assumptions so the user can quickly correct them. - Before larger batches, read existing move context and nearby inventory to avoid duplicates. Use `externalSource` and `externalId` when importing from a repeatable photo walk, spreadsheet, note, or agent session. - For bulk changes, prefer this sequence: read agent context, prepare rows, dry-run `batch-upsert`, explain notable assumptions or failures, write with a new idempotency key, then read records back. For photo-based inventory: - Create concise item names. - Use readable room names and space IDs when available. - Store descriptions based on what is visible and what the user says. - Use estimated dimensions when they help the move plan, but do not invent precision. If the user only needs a quick inventory, dimensions can wait. - Choose dimensions, weight, volume, condition, and value confidence based on the evidence. A clear photo of a common object may justify `medium`; measured values, model research, or manufacturer specs may justify `high`, `manual`, or `actual`. Use `low` when the object is ambiguous, partially hidden, unusually sized, or based only on a rough conversation guess. - Add review flags such as `confirm-disposition`, `photo-estimated-weight`, `photo-estimated-dimensions`, `capture-model-serial`, or `confirm-contents` only for fields that genuinely need user attention. - When the agent infers fields, summarize those choices after writing instead of asking the user to approve every ordinary field upfront. - For sell items, create or update a sale listing with listing status, platform, title, description, pricing range, research depth, and sources. For measurements: - `dimensionsIn.lengthIn` is the long horizontal dimension. - `dimensionsIn.widthIn` is depth. - `dimensionsIn.heightIn` is height. - Use `measurementProvenance` to record source type, confidence, notes, recorded time, and whether verification is needed. ## REST API Base URL: `https://movingmanifest.com/api/v1` Auth header: `Authorization: Bearer mmk_...` Suggested discovery order: 1. `GET /me` 2. `GET /moves` 3. `GET /moves/{moveId}/agent-context` 4. Read spaces, transport resources, zones, item counts, sale pipeline, and existing photos before writing. Important endpoints: - `POST /moves` - `POST /moves/setup` - `GET /moves/{moveId}/agent-context` - `GET /moves/{moveId}/items` - `POST /moves/{moveId}/items` - `POST /moves/{moveId}/items/batch-upsert` - `GET /moves/{moveId}/spaces` - `POST /moves/{moveId}/spaces` - `POST /moves/{moveId}/sale-listings` - `POST /photos/upload` - `POST /images/upload` - `POST /uploads/init` - `POST /photos/finalize` - `GET /moves/{moveId}/capacity-report` - `GET /moves/{moveId}/move-day` - `POST /moves/{moveId}/exports` Use `/openapi.json` for machine-readable endpoint details. ## MCP MovingManifest exposes two remote MCP doors. Hosted OAuth is the default for clients that support browser sign-in; the API-key door is an advanced fallback for headless or non-OAuth clients. No repository clone is required. Hosted OAuth defaults to a narrower trusted-helper surface than broad API-key setups. Remote MCP (claude.ai custom connectors, Claude Cowork, any Streamable HTTP client — no install needed): ``` MCP door (RECOMMENDED): https://movingmanifest.com/mcp (/mcp/connect is an alias) Auth: OAuth browser sign-in (Clerk) — no key to paste. Uses the subscription. API-key door (advanced): https://movingmanifest.com/api/mcp Auth: Authorization: Bearer mmk_replace_with_a_scoped_api_key (rejects OAuth tokens — use the MCP door above for sign-in) ``` OAuth-capable clients should connect to `/mcp` and follow the protected-resource login flow. The `/api/mcp` API-key door is ADVANCED and only for clients that cannot use remote MCP OAuth (local/headless, CI) — never point a hosted/OAuth client there, it rejects OAuth and fails to register. Send the key in the `Authorization: Bearer mmk_...` header (or `x-api-key`); the legacy `?key=mmk_...` query-string form is rejected with a 401 because URLs get logged. Codex OAuth setup (recommended): ```bash codex mcp add movingmanifest --url https://movingmanifest.com/mcp codex mcp login movingmanifest ``` Codex API-key setup (advanced, non-OAuth only): ```bash export MOVINGMANIFEST_API_KEY=mmk_replace_with_a_scoped_api_key codex mcp add movingmanifest \ --url https://movingmanifest.com/api/mcp \ --bearer-token-env-var MOVINGMANIFEST_API_KEY ``` Equivalent advanced Codex `~/.codex/config.toml`: ```toml [mcp_servers.movingmanifest] url = "https://movingmanifest.com/api/mcp" bearer_token_env_var = "MOVINGMANIFEST_API_KEY" ``` After configuring MCP for Codex, restart Codex or start a fresh session. The agent should confirm `movingmanifest` appears in `/mcp` or `codex mcp list`, then call `get_api_context` before accessing private data. If the current Codex session cannot see newly added MCP tools, tell the user a fresh Codex session is needed rather than assuming the key or API is broken. Suggested first MCP tools: - `get_api_capabilities` - `get_api_context` - `list_moves` - `get_agent_context` Hosted OAuth trusted-helper tools: - `setup_move` - `add_item_from_photo` - `batch_upsert_items` - `save_box_intake` - `upload_photo` - `upload_photos` - `upload_evidence_image` - `upload_evidence_images` - `list_move_spaces` - `create_move_space` - `suggest_assignments` - `apply_assignments` - `get_move_summary` - `get_move_questions` - `get_move_day_checklist` - `list_planned_items` - `create_planned_item` - `update_planned_item` API-key extended tools may include broader categories when the user intentionally grants them: - move creation and advanced setup; - detailed item and box primitives; - sale-prep workflows; - export and share workflows; - household collaborator management; - Layout Studio plan operations; - raw upload-session operations for clients that cannot use workflow photo tools. Always call `get_api_capabilities` and trust the live tool list before using a tool. Do not assume sale, export, household-management, or low-level item/box primitives are available in hosted OAuth just because they are documented for API-key setups. ## Safety Rules For Assistants - Ask before using a key if the user has not clearly authorized it. - Do not store the raw key in generated files. - Do not expose private values, serials, notes, photos, or addresses in public outputs. - Prefer move-restricted keys when possible. - Verify writes by reading the created records back. - Summarize exactly what changed and what still needs user review. - Get clear session or batch permission before creating records or uploading photos. Once the user has asked the assistant to capture a room, photo, list, or batch, do not ask for approval on every ordinary inferred item field. - Ask explicitly before sensitive actions: marking items for sale, creating exports, changing layout/load plans, granting household access, or exposing private values, serials, notes, addresses, or photos. - If dimensions, weight, condition, value, price, or contents are estimated, store estimate confidence and provenance instead of presenting guesses as facts.