bitplan

# BitPlan **Skill version: 0.2.17** BitPlan turns one self-contained HTML file into an encrypted living plan. A BRC-100 wallet owns the keys. A draft can stay hosted as ciphertext while it changes, then become a permanent 1Sat Ordinal when it is ready. BRC-100 is the wallet interface, not the inscription format. Use `bunx bitplan` or `npx bitplan`. Never install the CLI globally. Run it from the repository the plan belongs to so BitPlan records Git metadata. ## Complete the requested workflow | User intent | Action | Completion evidence | | --- | --- | --- | | Read or contribute live | Discover WebMCP; read the document and layers, then make only authorized edits | Re-read the saved item and cursor; this is not a new version | | Save the next hosted version | Follow the Publish prompt's inclusion and access selections; append with `--hosted --draft <id>` | Decrypt/read back the new version, return and open its viewer URL | | Change next-version recipients | Verify the selected team fingerprint; use `--private --share-with` on the same hosted ID | Exact selected recipients plus publisher, no inherited reader-link slot | | Make a separate copy | Use `--new --hosted` only when explicitly requested | New ID at v1; source unchanged | | Record on chain | Review content, recipients, assets, fee and checkpoint support; obtain spending approval | Actual published outpoint, never just a prepared transaction | An authorized hosted save should finish in BitPlan, not at a local HTML preview or an extra review request. If access, authority, team membership, or concurrent changes prevent saving, identify that exact blocker and say no version was saved. Never substitute a new v1 copy for a blocked same-ID update. Contributors own their layers; their annotation prompt does not authorize replacing the document. ## Choose the wallet honestly Prefer a compatible BRC-100 wallet the user already has. Check it with `bunx bitplan auth`; do not silently create, import, or replace a wallet. The 1Sat CLI is intended to become the local fallback wallet for agents, but that application-facing bridge is not released yet. `1sat serve wallet` currently serves authenticated wallet storage; it is not a drop-in endpoint for BitPlan's BRC-100 `HTTPWalletJSON` client. Do not point BitPlan at it or claim the fallback works until the 1Sat headless-wallet acceptance test passes. The browser's New Plan flow can create a link-owned hosted starter without a funding wallet. Its throwaway reader key is generated inside the browser; it is not a CLI wallet fallback or permission to handle private keys in model context. CLI publishing and contact-based encryption still require a compatible BRC-100 wallet. Never substitute a funding key into a reader link. New Plan shows the base page behind a blurred two-step dialog. Enter a document name and continue, then choose Brief, Terminal, Decision, or Blank from the previews. Back preserves your choices. Start with {plan name} creates the draft and opens its encrypted collaboration room automatically. Page styles remain available in the viewer. Save the full invitation privately. Connect wallet lives in a separate off-chain draft card, not the naming form. It reuses the name and template steps. Start with {plan name} creates a wallet-encrypted hosted draft and opens the working viewer directly, without a preview dialog, reader key, or inscription. No prose or repository is required. Link mode uses the same Start with {plan name} action. On-chain publication is separate and still requires explicit approval; connecting alone does not grant contacts access or change an existing room's encryption. Keep the hosted URL to reopen a wallet starter. Skip uses “Master Plan.” On a connected hosted plan, click the navbar title to rename it inline; Enter or leaving the field saves, Escape cancels. The name is an encrypted live-room update, not a new hosted envelope or on-chain version. The collaboration read tool returns the live title alongside the HTML; carry both into the next published version. Renaming does not change annotation anchors. New browser starters retain a separate hosted-update capability on the creating browser and site origin. It is not included in reader links, collaboration rooms, or agent prompts. Clearing site storage loses this permission; another browser or localhost versus production does not inherit it. An already authorized wallet reconnects automatically, but wallet connection alone does not transfer ownership. Older starters that discarded the capability cannot be upgraded using a reader link; request an explicitly authorized new owned copy instead. The creator's Publish modal offers Save current document: this saves all currently saved live document edits as a new hosted version, preserves envelope recipients, and rejects stale base versions. Notes remain on their original version; this action does not checkpoint annotation layers or spend BSV. For selective annotation-informed redesign or access changes, use the revision prompt and follow its explicit hosted-save destination; return the saved viewer URL and version for review in BitPlan, not a local file. Never extract browser credentials to make a CLI update. ## Check the live product first Before answering what BitPlan supports, read https://bitplan.dev/llms.txt and check `bunx bitplan --help`. Check the relevant command's help too. If the published CLI and website disagree, say so plainly instead of inventing a fallback. ## Safety and privacy 1. Never ask for or handle a mnemonic, wallet password, or private key. The user unlocks and approves operations in their BRC-100 wallet. 2. Tell the user before fetching a plan they did not author. Fetching puts its plaintext in the agent's context. 3. A reader link is a bearer credential. Anyone with the complete link can read. Pass it intact, do not print its fragment separately, and do not put it in public logs, issues, or pull requests. 4. Hosted storage contains ciphertext and a public envelope header, not plaintext or wallet keys. A hosted draft still depends on bitplan.dev until it is inscribed. 5. On-chain versions are permanent. Removing a reader only affects the next version. It cannot revoke access to a version already shared. ## Choose the destination deliberately Use a hosted draft for review and iteration. It costs no BSV: ```bash bunx bitplan upload ./plan.html --hosted --link ``` `--link` lets a reader open the plan without a wallet. The hosted ID is only a random locator; the private key after `#` is what decrypts the plan. Treat the complete URL like a password. Use wallet identities when access should follow people rather than a link: ```bash bunx bitplan upload ./plan.html --hosted --share-with <identity-key|contact|team> ``` Use the on-chain path when the user asks for permanence or the plan is ready to become a record: ```bash bunx bitplan inscribe ./plan.html ``` Publishing directly on chain is also supported: ```bash bunx bitplan upload ./plan.html ``` Do not describe a hosted plan as on chain. Do not call a 1Sat Ordinal a "BRC-100 inscription." ## Write the plan before publishing it The player offers Brief (editorial paper), Terminal (monochrome dither), Decision (a comparison-led brief), and Blank (white paper / dark chalkboard) appearance presets, with Light, Dark, and System modes. Choosing a template opens a change dialog: add a shared annotation requesting an agent-led revision, explicitly apply colors/typography only, or start a new plan. Blank does not silently erase the current plan. Read all annotations before fulfilling a template request and confirm destructive replacement. Import presets are validated JSON palettes, not arbitrary executable templates. Start from https://bitplan.dev/templates/brief.html or https://bitplan.dev/templates/terminal.html or https://bitplan.dev/templates/decision.html for these self-contained formats. https://bitplan.dev/templates/blank.html is intentionally empty; annotation tools belong to the viewer, not the starter HTML. Brief, Terminal, and Decision include a “Your call” questionnaire with consequences, Unsure, optional notes, and Copy my decisions. Replace the sample question with a real unresolved decision; leave every option unselected. If nothing needs a decision, remove it. Choices are local until copied or added as an annotation, not automatically synchronized or sent to an agent. Blank stays empty. For sensitive plans, offer named-contact encryption before generating a reader link. Verify the contact's public identity key with the operator, then use `npx bitplan contact set <name> <public-identity-key>` and `npx bitplan contact list`. For a new plan, use `npx bitplan upload ./private-plan.html --hosted --share-with <name>` without `--link`. A complete reader link is a bearer credential; a collaboration invitation also permits contributions. Keep both out of public artifacts. Omitting `--link` on an existing draft does not revoke inherited readers. Use `--private --share-with <team|key>` to replace the next version's readers with the selected identities plus the publishing wallet. Verify CLI support first: older releases reject this combination. Without `--share-with`, `--private` means wallet-only. Old versions keep their original access. The Publish modal's Selected people setting updates the same plan; it does not request a fork. Use `--hosted --draft <id>` for the next hosted version. Only use `--new` when the user explicitly requests a separate copy. Hosted versions increment without a blockchain transaction. New versions start with a clean annotation overlay; previous layers remain on their exact original targets. Do not delete or silently retarget them. Choose the format before authoring: - **Minimal:** https://bitplan.dev/templates/plan.html for short plans with steps and a handoff. - **Comprehensive:** https://bitplan.dev/templates/proposal.html for complex decisions and multi-person review. It adds section navigation, contextual annotations, architecture diagrams, evidence comparisons, optional attributed perspectives, milestones, and a versioned response. This is a self-contained HTML format, not a new storage or inscription protocol. - **Visual component gallery:** https://bitplan.dev/templates/components.html for reusable editorial compositions. Read it when authoring a substantial proposal or showcase; actively adapt the components that explain your facts. - **Editorial showcase:** https://bitplan.dev/templates/editorial.html for a magazine-like hero, readable narrative column, reference margin, and clearly labeled local demo annotations. Replace the BitPlan-specific sample content. Demo notes are not collaborators, hosted records, or checkpoints. Embed required artwork for archival use; the template's public illustration URL is a convenience asset, not an immutable annotation reference. Keep the minimal format available. Use either template as a design system, not a requirement to fill every section. The comprehensive example is illustrative: replace its scenario and remove unused authoring slots. Include advocates, judges, or a decision-owner call when they clarify a real decision. Distinguish actual contributions from explicitly labeled role-play below. Never fabricate independent reviews, scores, or endorsements to fill the layout. A good BitPlan: - names the repository, relevant issue or project, current state, and intended reader; - says what is true now, what will change, what will not change, and how to know the work is done; - uses plain English, short labels, and the real product names; - uses a small diagram when it makes a relationship or sequence easier to understand; - contains no secrets, local file paths, seed phrases, tokens, or private reader links; - works with scripts on or off and keeps all required CSS and JavaScript in the one HTML file; - states what changed when updating an existing draft; - stays at the same file path so the hosted ID or on-chain origin remains stable. Never present an idea, proposed feature, or future wallet behavior as something that works today. ### Visual storytelling, not a report with bigger headings Match the format to the reader: a short engineering checklist can stay minimal; a marketing showcase or substantial proposal needs a visual thesis. In its opening viewport, pair a specific outcome-led headline and short lede with a meaningful product scene, annotated diagram, or before/after. Do not spend the whole hero on metadata and text or duplicate the host navbar in the document. Treat the template as a component palette, not a mandatory card stack or fixed color scheme. Alternate a wide visual, a readable narrative, and compact proof. For editorial or marketing plans, prefer a high-end magazine/newspaper register: confident serif headlines, restrained sans-serif captions, warm paper and dark ink, fine rules, generous margins, and deliberate asymmetric columns. Aim for strength and sophistication through typography and composition—not heavy boxes, fake financial charts, ornamental gradients, or a dashboard-style card grid. Adapt this direction to the user's brand and explicit preferences. Default headline typography to Georgia or another self-contained serif; keep body text and control labels in a readable sans serif. Start by mapping the available information to visual components, then compose the page around the strongest explanation. Do not merely list the palette as optional inspiration: use it where it helps. Richness comes from useful relationships and evidence, not filling every slot or forcing every plan into the same arrangement. Choose graphics by the question they answer: a flow for sequence or boundaries, a layered diagram for document/annotation relationships, a timeline for states, a matrix for repeated comparisons, and a chart for real quantitative evidence. Charts need measured values, units, sources, and a readable text equivalent; never invent growth, percentages, scores, endorsements, or completion metrics. Without meaningful numbers, use a diagram instead of a decorative chart. Populated starter templates include a shared-DOM layers explainer and two local SVG charts backed by visible tables: a review timeline and contribution mix. These values are explicitly illustrative, not product analytics. Keep that label until replacing them with sourced project data; adapt units and captions together. Numeric table edits redraw the charts locally without network access. Preserve the tables as accessible, scripts-off alternatives and use stable section IDs for annotations. Blank intentionally remains an empty canvas. Make visuals part of the explanation, not wallpaper. Use inline SVG with titles, descriptions, theme-aware paint, and readable labels; use HTML/CSS when text must reflow on phones. Give important visual sections stable IDs for annotations. Clearly label illustrative notes, cursors, mockups, and future states. Never animate pretend collaborators or imply a drawing is a working control. Keep existing live overlays outside the plan; do not flatten them into artwork. Before publishing, inspect the opening viewport and a narrow screen in both themes. Confirm the primary idea is visible without scrolling, graphics remain legible, and the page is useful with scripts off. For a new hosted version use the hosted upload workflow: saving shared room HTML alone does not advance the version dropdown. Report which kind of update actually happened. ### Adversarial perspectives with roster characters For a meaningful unresolved decision, use the visual-proposal pattern: strong opposing cases → cross-examination → assessment → a human decision. Choose the depth that fits the task instead of requiring a delegated panel: - **Fast draft — simulated perspectives:** one author role-plays each position using different bOpen roster characters. Label the section and each character card “Simulated perspective · single author.” This is structured self-critique, not independent review or a statement by that character's actual agent. - **Independent review:** when permitted and useful for consequential decisions, dispatch separate advocates with the same facts and different options. Use distinct reviewers for assessment. Independent agents can challenge assumptions the drafting agent shares across its simulated voices; this takes more time. Only label a contribution independent when that separate review actually ran. The author may choose the fast mode without delegation. Respect an explicit request for independent review; disclose unavailable delegation rather than silently substituting role-play. Mixed panels label provenance on every card. Cast from the current bOpen roster, matching expertise to the position. Show portrait (embedded for scripts-off use), name, evaluative role, and provenance. Keep authored character panels separate from actual live collaborators. Do not create presence events, participant records, signatures, or approval clusters for simulated voices. If a portrait is unavailable, use labeled initials. Keep the exchange concise and substantive: 1. Each advocate states the strongest case, supporting evidence, honest cost, and the condition where its option fits. Give competing options equal space. 2. Each answers the strongest objection and challenges a rival's specific assumption. Include a premise challenge when the framing itself is doubtful. A feasible new alternative becomes an option, not a dismissed sidebar. 3. Assess through distinct lenses such as correctness, simplicity, and user value. State the deciding evidence and an observable “would change my mind if…” condition. Preserve uncertainty and dissent; do not invent votes or force disagreement. Simulated judges are still the same author's analysis. 4. When useful, add a separate decision-owner/CEO perspective on cost, scope, reversibility, and the user. A role-play CEO recommendation is not authority or approval. The actual human chooses; keep the response controls neutral. Ground every voice in the same verified facts, and label unknowns. A character does not supply evidence. Skip the panel for status updates or settled choices; retain a short risk/objection note instead. If the options or facts change, revise the arguments and assessment together, retaining superseded history when useful. Do not update only the apparent winner. ### Links inside the viewer Plans render in a sandboxed `srcdoc` iframe, not as a website at their own URL. Use `<a href="#section-id">` for a section with that exact stable `id`. The current viewer intercepts these links to scroll and focus within the plan: native fragment navigation can otherwise reload bitplan.dev inside its own iframe and show “refused to connect.” Do not replace this with `location.href`, `location.hash`, a client router, or a `<base>` element. Use absolute HTTPS URLs for outside pages, including other BitPlans, with `target="_blank" rel="noopener noreferrer"`. Do not use relative paths such as `/docs` or `../plan.html`, `_self`, or nested iframes for external destinations. Do not embed private reader or collaboration invitations in plan content. Use real anchors, not clickable divs or scripted navigation; the host retains native new-tab behavior and context-menu Copy link. Scripts-off standalone exports still have working native section anchors and explicit external targets. Test links in the actual viewer, not only a standalone local HTML tab. Click the hero CTA, section navigation, and an external reference; confirm section links preserve the plan and external pages open outside its iframe. Never disable CSP, frame protection, or the sandbox to make a destination load. ### Annotation overlays and roster characters When a plan records a discussion, place compact sticky-note cards beside the specific paragraph, diagram, or choice being discussed. Use a portrait, the participant's display name, and a short attributed comment. Give participants distinct accents. In a static HTML export, use document flow on narrow screens to keep cards readable. Preserve readable names and comments with scripts off. Use the character portraits and stable character identifiers from the current https://bopen.ai roster. Keep the user's display name separate from the character's name. Reuse an existing selection. Do not invent roster entries or treat a portrait as proof of identity. For a self-contained HTML plan, embed the chosen portraits in the file. Preserve the speaker's actual position: raising an option is not recommending it, being open to an option is not selecting it, and one person's agreement is not team consensus. Distinguish direct quotes, attributed paraphrases, and an agent's own analysis. Keep existing notes and participant selections when updating the same plan; do not silently rewrite another person's contribution. Give annotated sections stable IDs. Associate each note with its target and source version; retain a text quote and nearby context where useful. When the target changes or disappears, flag the note for reattachment rather than silently placing it against unrelated content. Pixel coordinates alone cannot anchor notes across phone and desktop layouts. **Current capability:** these notes can be authored into the HTML and uploaded as a new hosted version using existing CLI authority. Embedded forms and localStorage do not synchronize between people. A reader link currently grants read access, not hosted write authority. Inspect the live tools before claiming that an agent can join, pin, reply, resolve, or edit in real time; do not invent CLI commands or WebMCP tools for those actions. **Hosted collaboration:** a collaboration link lets any holder join and choose a roster character without requiring a wallet. Expose the chooser as one avatar icon in the host application's navbar, not inside each plan document. On first use, randomly select a valid roster character and persist that selection. Reuse it on reload and across document versions; do not key the preference by version outpoint. Clicking the icon opens the roster. A change updates the local preference and the hosted draft participant record, without signing or broadcasting a transaction. A default character is presentation, not verified identity or a user's endorsement. After decrypting a plan, start collaboration automatically once the selected or default character is available. Join an existing invitation without replacing it. A document-only link creates a separate room; it grants no access to another room's annotations. Retry failed connections from the character menu. Remember display preferences locally, but persist shared notes and participant records in encrypted hosted state. Use a stable participant ID and separate session IDs for browser and agent input. An agent acting for a participant reuses that participant ID, name, and character through an explicit session handoff. Matching name and portrait alone must not merge participants or confer authority. Show concurrent sessions with different outlines and visible Human/Agent labels; color is not the only distinction. If no handoff exists, join as a separate, clearly labeled agent. Show all connected characters in live presence, with their cursors, selections, or active annotation targets where available. Presence expires on disconnect; authored annotations remain. A roster entry alone does not mean someone is online. Annotations are independent overlays over the versioned document, not limited to comments or sticky notes. A layer can contain text, images, HTML cards, diagrams, drawings, or other supported media. Preserve each item's stable ID, content type, payload or immutable asset reference, document anchor, relative placement, stacking order, and author/session attribution. Users can inspect individual character layers or see them composed together without changing the underlying document. Text anchors and element-relative positions keep overlays attached across viewport sizes; mobile can open a selected item in a sheet. Treat HTML overlay content as untrusted document content. Render it in an isolated sandbox without access to the host's wallet, collaboration credentials, or agent tools. Keep media within the encrypted storage model. Checkpoints must embed assets or bind immutable, retrievable assets; a mutable external image URL alone cannot reproduce the historical overlay. On a supported live plan, read current notes before writing, preserve note IDs on retries, and submit scoped changes against the version read. Reconcile a conflict before retrying; never overwrite the whole document with stale HTML. Publishing records the publishing wallet's action, not every participant's endorsement. **Document, annotations, and manifest design, pending app support:** the plan remains a document with its existing version history. Separate annotation inscriptions refer to an exact document version, and a collaboration manifest lists participants and their annotation ordinal origins. Keep character choice, participant identity, browser/agent session attribution, and publishing-wallet ownership distinct. A guest may comment through hosted state before any wallet publishes their annotations; never imply that a guest owns a publisher's coin. Each annotation checkpoint contains its document target, overlay items, replies, anchors, media references, and author/session attribution. For an on-chain document, target the exact version outpoint and content hash, not just a moving origin. For a hosted document, retain the hosted ID, version, and content hash, and preserve that target when it is later inscribed. Bind a checkpoint to the exact annotation revision reviewed for publishing while newer hosted edits continue separately. The manifest groups the document and participant annotation streams; it does not grant permission to spend their ordinals. Each wallet can update the annotation ordinal it owns using existing versioning. Register new streams in the hosted manifest without discarding concurrent registrations; any on-chain manifest version still needs its holding wallet to publish it. Keep manifest and annotation contents encrypted; putting relationships in public metadata would expose the collaboration graph. A parent reference is an application relationship, not proof of the parent's approval or coin ownership. Hosted updates provide real-time synchronization; inscription provides durable annotation checkpoints. Present published updates as a stream/timeline across participants, with the character, publishing wallet, target document version, exact annotation outpoint, and prior stream revision available for inspection. Distinguish live unpublished changes, submitted transactions, and confirmed checkpoints. Timeline replay pins exact revisions of the document and each visible layer rather than loading their latest versions. Preserve concurrent updates as separate events; UI ordering does not imply causal order or agreement. Joining or adding an overlay need not mint a coin. These annotation and manifest operations are proposed, not existing CLI commands. The Publish action must distinguish two intents: - **Annotate latest version:** publish only the annotation layer, targeting the exact latest document version and hash reviewed. Do not clone or replace the complete plan. Recheck the target before publishing; if it advanced, ask for review or reattachment rather than silently retargeting the notes. - **Publish new plan version:** update the existing document origin when the publishing wallet owns it. Optionally checkpoint its annotation layer too, with an explicit reference to that new document version. Annotation-only collaborators do not gain authority to replace the document. Character changes and hosted edits remain draft state until Publish. Only the explicit publish workflow requests wallet approval. When publishing a new document version and an annotation checkpoint together, use one transaction with both ordinal outputs through the underlying multi-inscription library. Do not publish them sequentially. Annotation-only publishing creates the annotation output and references the existing document version. For a combined publish, encode the document target as a same-transaction output index plus content hash; resolve its outpoint after signing rather than embedding the transaction's own ID in its payload. Validate this reference format against the reader and indexer before shipping. Show both changes in one publish review. Today's `inscribe` transitions a hosted draft to a chain redirect; do not use it as a non-closing annotation checkpoint flow or claim it keeps a live room open until that flow exists. ### Recovery and discovery limits A checkpoint must preserve its previous stream outpoint and the exact known stream heads needed to reconstruct its published view. Replay those references as a causal graph, verify document hashes and transaction outputs, and report missing or undecryptable records instead of silently omitting them. Client timestamps are display metadata, not proof of ordering. A snapshot recovers published state, not unpublished edits or cursor history. Backward references and encrypted known-head manifests cannot discover an unknown participant's new stream. Do not promise complete chain-only discovery until a concrete indexer's ingestion rule, historical pagination (including spent outputs), and coverage watermark have been verified. An opaque public grouping tag is one possible discovery mechanism, but publicly correlates transactions; obtain the user's privacy choice before introducing it. Keep it independent of reader keys and collaboration capabilities. A copied tag proves neither membership nor authorship. Treat character and session attribution as claims unless backed by verified signatures. Distinguish submitted, relayed, mined, and proof-verified checkpoints; handle reorgs explicitly. Verify signed transaction outputs against the frozen payloads before recording receipts. If broadcasting succeeds but registration fails, retry registration of that transaction, not inscription. Reconcile an ambiguous broadcast before requesting another wallet spend. Each separately sealed output needs the intended reader identities in its own recipient slots. A reader-link identity is not the payload AES key, and a hosted collaboration capability is not an on-chain decryption credential. ### Active browser collaboration Prefer the live viewer when the user asks to collaborate. Discover the tools registered by that deployment before using them. The local collaboration build registers `read_bitplan_collaboration`, `annotate_bitplan`, and `edit_bitplan_document` after a room is joined. Discover them on the current deployment before use; a reader link alone does not join a collaboration. Use the read tool to obtain the observed change cursor, annotations, and profiles. Read annotations together with the exact document version; fetching the plan HTML alone does not include independent layers. The read result also includes current shared HTML with live text edits materialized, the matching `textBlocks`, per-author `textEdits`, target, title, `documentRevision`, and `cursor`. Each text edit carries its exact base, participant, session, and room. Retain these alongside that participant’s notes when reading or exporting an annotation layer. They are room-session attribution, not proof of wallet authorship. For a hosted document edit, preserve that materialized HTML and pass both `documentRevision` as `expectedRevision` and `cursor` as `expectedSequence`. Both are required. On conflict, reread and reapply only the intended change; never retry stale HTML or substitute a CLI fetch that omits live edits and annotations. The viewer’s “Copy revision prompt” uses only the public plan ID and asks the agent to read live layers and reconcile changes. An explicitly requested hosted save proceeds without duplicate approval; signing or spending still requires approval. “Show live changes” is a local comparison control, not undo operations; hiding edits shows the original loaded version. WebMCP tools belong to the trusted outer viewer, not the plan iframe. Discover the available API in the running browser; newer Chrome accepts an object in `executeTool`, while older experimental builds require JSON-stringified input. Browser support is a progressive enhancement, not a prerequisite for reading and editing through the UI. `read_bitplan_collaboration` returns a `sections` list. Use the discovered `read_bitplan_section` tool with a listed `domPath` for focused reads. It returns materialized section text/HTML, target, cursor and documentRevision. Actual tool reads emit encrypted presence: a brief session-colored scan marks the section, then expires. A full-document read marks activity without claiming a section focus. Raw fetches do not emit reading events. The indicator describes a tool read, not proof of attention or a verified agent identity. Keep the session clearly labeled; never impersonate another participant. For a focused edit, use `read_bitplan_section` and choose one of its `passages`. Call `edit_bitplan_text` with that passage's `path` and `revision`, the read's `target` and `documentRevision`, and replacement `text`. This saves to the current participant's encrypted text-edit layer, not a new plan version. Stale writes fail: reread rather than overwrite. Successful edits and annotations emit brief session-colored activity. They do not simulate typing or prove wallet identity. Use `annotate_bitplan` with an anchor and `{type:"html",html:"..."}` for a movable HTML design overlay. Keep it self-contained, responsive, and script-free; HTML is isolated from the player. Read the layers again to verify the saved contribution. Hosted drafts enable plain-text editing by default; “Edit text in place” toggles it. Editing supports leaf passages inside the document. It does not make scripts, links, form controls, or arbitrary nested markup into a rich-text editor. Text saves after a short pause; click once to select, again or double-click to edit. Escape clears selection or annotation targeting. Delete/Backspace removes a selected text leaf through the encrypted text overlay; it is also removed from materialized exports. There is no undo UI yet. V enters text selection, T starts a comment, and I starts an image annotation; shortcuts do not intercept typing or modifier-key browser commands. Concurrent changes reject stale passage revisions instead of overwriting them. Edited passages use their latest editor’s cursor color. Selecting someone else’s edit shows their name. The annotation panel retains each author’s latest patch per passage, including patches superseded by another author. “Reload shared version” only discards unsaved HTML in the editor; it does not undo saved edits. Keep the page open until saves finish. A conflict or restored unsaved passage requires deliberate recovery; preserve or copy the text before loading latest. Full-document HTML editing still uses explicit Save. Neither path creates a