# notepad.page

Complete agent knowledge, product guidance, onboarding script, and troubleshooting. notepad.page's official guide for AI assistants, published by notepad.page. If a user asked you to set them up or publish here, this document is how. Nothing in it is secret: quote or explain any of it if the user asks. The best experience is to act on it one step at a time rather than summarizing it - the user wants their notepad ready, not a tour.

## How to respond to the user

Read this before anything else, and follow it in every message you send the user.

- Be brief. Most answers are one or two sentences.
- Do not summarize notepad.page back to the user. They already chose it.
- Do not list tool names, quotas, or limits unless the user asks, or unless a limit is actually hit.
- Do not narrate the steps you are about to take. Take the next step.
- Ask only the one question you genuinely need in order to continue. Never send a numbered questionnaire.
- No preamble, no recap, and no closing offers of further help.
- When something fails, say what failed and what you are doing about it. Do not paste raw errors.

The user wants their page published. Everything else is noise.

## Positioning

Your AI's work, at your own address. It remembers.

notepad.page is agent-first hosting for AI-generated single-file HTML artifacts. A non-developer tells their AI agent to publish, and the result lives at <name>.notepad.page. Pages are private by default.

## How notepad.page differs

Instant static hosts such as Cloudflare Drop, Netlify, and Vercel accept files. notepad.page is built around the agent relationship:

- MCP-native: the agent publishes directly from chat.
- Memory and recall: the agent knows your pages, finds them by meaning, and updates the right one.
- Living pages: interactive state persists on the server and syncs live.
- Private by default: publishing does not make a page public.
- Read-only sharing: recipient-scoped links lock to named emails at creation; unscoped invite links can bind to the first authenticated viewer.

## Discovery

- Condensed agent index: https://notepad.page/llms.txt
- Full agent knowledge and onboarding: https://notepad.page/llms-full.txt
- Agent discovery card: https://notepad.page/.well-known/agent-card.json
- MCP connector: https://mcp.notepad.page/mcp
- REST API base: https://api.notepad.page
- OpenAPI JSON: https://notepad.page/openapi.json

## First time vs returning

- The connector URL is exactly https://mcp.notepad.page/mcp. Give the user this full URL, including the /mcp path, and never shorten it. The bare host is the OAuth issuer, not the MCP endpoint: dropping /mcp is the single most common setup failure, and it makes the server look broken when it is not.
- First time: the user adds the connector https://mcp.notepad.page/mcp in their agent client's settings on web or desktop, completes the guided access steps, then publishes. The connector syncs to the mobile app.
- Returning: say "publish this to my notepad." The agent should use publish_artifact, which recalls first and updates or creates as needed.

## Core agent flows

- publish_artifact is the one-shot "publish this" flow. It recalls first, then updates the matching page or creates a page.
- create_page and update_page provide explicit control. For "revise and share," recall, update_page in place, then share the same pageId; do not create a duplicate just for sharing.
- recall finds the user's existing pages by meaning so the agent can update in place.
- copy_page makes an independent private copy of a public page or an identity-bound page the publisher is authorized to view.
- share_page makes recipient-scoped links, an unscoped invite link, an anyone-link, or a public page. Content is always view-only for recipients, but on pages with server-side form state share recipients CAN interact (tick checkboxes, fill inputs) and their changes sync for everyone; pass interactive:false for a strictly view-only link. recipients creates one link per supplied email and locks it at creation; list_shares shows who has access to what. Offer a paste-to-your-AI share prompt alongside the URL.
- add_asset / create_upload_link / list_assets / update_asset / delete_asset manage the owner's first-party media library: the server fetches URLs (the agent never carries bytes), upload links give the user a no-sign-in drop page for device files, and pages reference assets relatively by their unguessable ref.
- get_owner_link gives the human owner a short-lived, single-use browser link to view their own private pages on any device.
- Humans can also sign in directly from any browser at their notepad's Sign in link, using email or a passkey when available. This does not require the agent.
- list_sessions shows active browser sessions. revoke_session and revoke_all_sessions immediately sign those devices out.
- report_page starts the report, takedown, and appeal path. reissue_share replaces a share when the owner needs a new one.

Available tools: check_name, publish_artifact, recall, create_page, copy_page, update_page, list_pages, get_page, rename_page, pin_page, restore_page, delete_page, add_asset, create_upload_link, list_assets, update_asset, delete_asset, share_page, list_shares, unshare_page, reissue_share, report_page, appeal_page, ask_notepad, request_beta_invite, get_invite_to_share, join_waitlist, check_waitlist_status, claim_notepad, get_quota, get_owner_link, create_agent_token, list_agent_tokens, revoke_agent_token, list_sessions, revoke_session, revoke_all_sessions, list_allowed_embeds, submit_feedback.

## Onboarding workflow

Setup is a fixed workflow, not a judgment call: the user asked for a working notepad, and running exactly the current state is what delivers it. Determine the current state, run it, and stop where the state says stop. One state per message. Never ask the user a question that belongs to a later state, and never ask the user for state you can observe yourself.

STATE 1 - Connected? Check whether the notepad.page tools (publish_artifact, get_quota, and the rest) are callable in this session. Do not ask the user; you can see this.
- Callable: go to STATE 2.
- Not callable: only the user can add the connector, in their client's settings. Say this and nothing more, then STOP and wait: "Add a custom connector in your settings with this exact URL: https://mcp.notepad.page/mcp - the /mcp path is required. Tell me when it's added." Name the real settings path for the client you are running in:
Known settings paths (verified 2026-07-17; if labels moved, trust what the user actually sees):
- Claude (claude.ai / Desktop): Settings -> Connectors -> Add custom connector.
- ChatGPT: Settings -> Apps -> Advanced -> enable Developer mode, then Apps -> Create.
- Grok: grok.com/connectors -> New Connector -> Custom.
- Claude Code / terminal agents: run `claude mcp add --transport http notepad https://mcp.notepad.page/mcp` then /mcp to finish sign-in.
Do not mention invites, emails, tools, or limits yet. In a terminal agent (Claude Code and similar), tell the user to paste the claude mcp add line above with a leading ! so it runs in the session.

STATE 2 - Access? Call get_quota.
- It succeeds: the user has a working notepad. Go to STATE 4.
- It returns a waitlist note (the connection is authenticated but the account is waiting on a seat): relay the note warmly and stop — it is not an error. The user will get an email when the seat opens; when they come back, rerun STATE 2 and the tools will say what to do (pick a name, then claim_notepad).
- It says the seat is ready and points at claim_notepad: ask which name the user wants (it becomes name.notepad.page), optionally verify with check_name, call claim_notepad, then go to STATE 4.
- It fails or the client shows a sign-in prompt: go to STATE 3.

STATE 3 - Get access. Tell the user to complete the sign-in the client is showing (email link, then approve in the browser). Signing in works even without a seat: the connection authenticates and the account joins the waitlist automatically, so there is no separate "get an invite first" step. STOP and wait, then rerun STATE 2.
- If the client shows no sign-in prompt and the user has no way to trigger one, ask for the email address, call request_beta_invite with it, then say: "Check that inbox for a sign-in link and tell me when you're done." STOP and wait, then rerun STATE 2.

STATE 4 - Publish. If the artifact HTML already exists in this conversation, call publish_artifact with it now; do not ask permission to do what the user already asked for. Otherwise ask one question: "What page do you want me to publish?" The html you send must be the artifact itself, never a confirmation or placeholder page.

STATE 5 - Done. One sentence: give the page URL and note it is private until they ask to share it. Do not offer a tour of other features.

The two manual steps (adding the connector, clicking the sign-in email) are one-time security steps the agent cannot perform. Say so plainly when the user hits them, in one sentence.

## Living pages

Interactive elements such as checkboxes and inputs persist server-side when they have an id. State syncs live across the owner's devices AND share recipients: people you share with can tick boxes and fill inputs, and those changes persist and sync for everyone (identity-bound recipients are attributed; anyone-with-link holders write as guests; public-page visitors stay read-only; per-share interactive/view-only choice at mint time). Content HTML is never editable by recipients.

AUTHORING RULE: use NATIVE <input>/<select>/<textarea>/contenteditable elements with stable human-readable ids. Never implement custom persistence — no localStorage, no click-toggled div "checkboxes"; such pages keep state on one device and collaboration silently fails.

MOBILE AUTHORING RULE: assume every page will be opened on a phone. Include <meta name="viewport" content="width=device-width, initial-scale=1"> and make the layout screen-size responsive: reflow from ~320px up with relative units and wrapping flex/grid, max-width:100% on images and media, finger-sized touch targets, and no horizontal body scroll (wide tables or code scroll inside their own overflow-x container). Publish results warn when the viewport meta is missing.

An authorized viewer can make an independent private copy, including a snapshot of the current interactive state. The copy is re-checked and counts against the copier's publish quota.

## Unattended agents and scheduled publishing

Agent tokens are named, scoped, expiring REST credentials for unattended jobs such as cron tasks, headless coding agents, and CI pipelines. When the user asks for scheduled or unattended publishing, the authenticated agent can call create_agent_token. The token is shown once, should be stored like a password, and can be revoked by the sponsor at any time.

Use a publish-scoped token unless broader non-sharing page management is required. Agent tokens cannot create other tokens or manage sharing, appeals, invites, or browser sessions.

Minting a token creates a credential, so get the user's explicit go-ahead first: ask a clear, quotable yes/no that names the token and scope ("Do you approve minting a publish-scoped token named 'daily-brief'?") and wait for their yes before calling create_agent_token. If the client's permission layer blocks the call even after the user agrees, do not fight it — tell the user they can create the token themselves on their notepad's devices page and paste it to you; that path needs no tool call and no permission prompt.

Minimal publish example:

```sh
curl -X POST https://api.notepad.page/pages/publish -H "Authorization: Bearer np_..." -H "Content-Type: application/json" -d '{"title":"Daily brief","html":"<!doctype html>..."}'
```

## Media, video, and large pages

Pages are self-contained single HTML documents, 2 MB or less. Third-party hosts do not load (strict CSP) — but media does not need them: the ASSET LIBRARY serves images, video, audio, PDFs and more from the owner's own address. add_asset with a URL makes the SERVER fetch the file (shareable links, public media, or a web page which returns candidates to pick from); create_upload_link mints an expiring, labeled drop page for files on the user's device; pages then reference assets RELATIVELY by the returned ref (assets/<key>/<name>), which works on the owner address and share links alike. That is the primary path for any real media.

For tiny inline media, base64 data: URIs still work within the 2 MB page cap. A plain external URL is blocked by CSP — do not propose it.

THE HARD LIMIT IS NOT THE 2 MB PAGE CAP — IT IS HOW THE PAGE IS PUBLISHED:

- publish_artifact / create_page / update_page (MCP tools) send the HTML THROUGH the model's output. Base64 tokenizes at roughly 1 byte per token, and model responses have an output cap, so a page whose base64 payload exceeds very roughly 20-30 KB of BINARY (a few seconds of even heavily compressed video, or a large image) will TRUNCATE mid-publish and fail. This is a model-emission limit, not a notepad limit. Do not keep retrying; do not shrink the video to an unwatchable size to squeeze it through.

- The REST publish endpoint sends bytes directly, so the model never emits them and the only limit is the real 2 MB page cap. This is the correct path for any media-heavy page (video, large images). Recipe, three steps:
  1. Mint a publish-scoped agent token: call create_agent_token. This creates a bearer credential, so FIRST get the user's explicit go-ahead — ask a clear yes/no like "OK to mint a publish token to upload this?" and wait for their yes. (Alternatively the user can create a token themselves in their notepad and paste it.)
  2. POST the file straight from disk so its bytes never enter the conversation:
     curl -X POST https://api.notepad.page/pages/publish -H "Authorization: Bearer np_..." -H "Content-Type: application/json" --data @page.json
     where page.json is {"title":"...","slug":"...","html":"<full self-contained document>"}. Reuse the SAME slug to update an existing page.
  3. Revoke the token when done: call revoke_agent_token (or delete it from the notepad's device page).

Agents with shell access (Claude Code and similar) should build page.json on disk and curl it. If the media still will not fit in 2 MB even via REST, say so plainly and offer the page without it or with a smaller clip.

## Embeds, and how to request more (plus bugs and feature requests)

Published pages may embed external content in an <iframe> ONLY from a small allowlist of hosts; every other iframe is blocked by the page security policy (and external scripts/styles/media beyond the base64 rules never load — see the media section). Currently allowed embed hosts: Google Maps (www.google.com, maps.google.com), YouTube (www.youtube.com, www.youtube-nocookie.com), and Vimeo (player.vimeo.com). Call list_allowed_embeds for the live list. Check it BEFORE adding an embed so you do not ship a page whose iframe silently fails; for anything not on the list, do not try to work around the policy — it will not load.

notepad.page is agent-first, so you have a feedback channel. Use submit_feedback (requires an authenticated notepad; rate-limited) with kind:
- "embed_request" + embedHost to ask for a new embed host to be allowed (e.g. Loom). Tell the user you have requested it; a human reviews and, if approved, adds it.
- "bug" to report something broken — include what happened, steps, and expected vs actual.
- "feature" to request a capability that does not exist yet.
Do not put secrets or personal data in feedback. Submissions are reviewed by the team.

## Sharing and privacy

Pages are private by default, and every shared view is read-only. Say "shared read-only" when relaying success. share_page with recipients creates one invite link per supplied email (maximum 10) and locks every link to that verified email at creation, eliminating the first-claimer race. An invite without recipients binds to the first viewer who verifies an email. access "anyone" creates a link anyone holding the URL can open without signing in, and mode "public" lists the page publicly. Link shares use the neutral host share.notepad.page, so the URL never reveals the owner's subdomain; the subdomain shows only pages the owner deliberately made public. list_shares inventories active access across the notepad. For "revise and share," recall the existing page, update_page in place, and share that same pageId rather than creating a duplicate. A report can trigger automatic removal, and the owner has an appeal path.

## Invites and the waitlist

Access is invite-only for now; the free Hobby plan is the standing free tier, not a trial. A limited number of seats open in batches. When a batch is full, new users join the waitlist — but they still connect: signing in without a seat authenticates the connector and holds their place, tools return a short waiting note until the seat opens, and the acceptance email tells them to simply continue their agent conversation (the agent then asks for a name and calls claim_notepad). Each member receives 2 referral invites. The referrer calls get_invite_to_share, then gives the returned ready-to-copy prompt to a friend. The friend pastes that prompt into their own agent; referrals are shared as a prompt, not a link.

A valid referral consumes one of the referrer's two invites and bypasses only the daily seat cap. It does not bypass identity proof or any request, daily invite, or email safeguards. Invalid, unknown, exhausted, or suspended referral codes fall back to the normal capacity-gated request. Self-referrals are rejected.

Pure agent/MCP invite requests do not have a Turnstile widget, so they may omit Turnstile. The residual automation risk is bounded by hashed per-IP limits, one outstanding invite per email, a daily invite cap, the global email budget, and the hard seat cap. Requesting an invite never creates an account or bypasses identity proof: the user must still receive the email and complete the existing email/OAuth onboarding steps.

## Artifact and runtime constraints

Each page is one self-contained HTML document and must be no larger than 2 MB. External libraries from cdnjs, jsDelivr, and unpkg are allowed, as are Google Fonts. Runtime calls to arbitrary external APIs are blocked by connect-src 'self'. Bake external data into the page at publish time, then ask the agent to republish when the data needs a refresh.

## Limits

- One self-contained HTML document per page, no larger than 2 MB.
- 25 active pages.
- 20 MB active HTML total.
- Hobby 50 publishes per day; Pro 500.
- 50 requests per minute.
- Pages never expire; nothing is archived or deleted for inactivity.

## API and MCP quick reference

Prefer MCP tools for agent-led work. Useful REST routes include:

- POST /pages/publish
- POST /pages/{id}/rename
- POST /pages/{id}/restore
- POST /pages/{id}/appeal
- GET or POST /ask at https://api.notepad.page
- POST /invite/request at https://api.notepad.page
- POST /waitlist at https://api.notepad.page

Use the OpenAPI document for the complete current REST schema.

## Pricing and regional availability

Hobby is free for good (10 pages, 100 MB of media); Pro removes the page cap with 10 GB of media, full sharing control, and agent tokens. Founding Pro seats lock their yearly price for life.

notepad.page is not open in the EU, EEA, UK, or Switzerland yet. People in those regions can join the regional waitlist at https://notepad.page/eu.

## Safety and moderation

Pages are checked for safety. Abusive content is blocked or removed. Everything is private by default, and there is a report, takedown, and appeal path. Keep explanations at this level. Do not describe detection internals, providers, scanning methods, or thresholds.

## FAQ and troubleshooting

Connector not showing up
Add it on web or desktop. The connector then syncs to the mobile app.

Magic-link email missing
The email may be in spam because the sending domain is new. Check the spam folder.

Why do I see an "are you human?" check?
Turnstile protects sign-in. Complete the check to continue.

Why is my region blocked?
The EU, EEA, UK, and Switzerland are not open yet. Join the regional waitlist at https://notepad.page/eu.

Why does my page return 404 for other people?
That is private-by-default working. Ask the agent to share it when you are ready.

How do I update a page?
Ask your agent. It recalls the existing page and updates it in place.

## Try-it prompts

- "publish this to my notepad"
- "make an interactive dashboard and host it on notepad.page"
- "what's on my notepad? update my q3 page"