# Build tools on FlashDrive Use this skill when creating or adapting a tool whose data lives on a FlashDrive drive. Preserve a storage format the user explicitly requires. For connection, mounting and conflict-copy commands, read the [FlashDrive access skill](../SKILL.md) advertised by release metadata and use the installed client's command names and the connection's configured addresses. Read [conflict recovery](recovery.md) before replacing files or resolving conflict copies. When a product capability or setup detail is uncertain, use the MCP `about` tool with a topic, or query `/agent-qna.txt?topic=` on the configured API origin with a URL-encoded question. Check the answer's update date and environment; an unanswered question is not confirmation of support. ## Choose the simplest useful format A tool can be a folder of Markdown files plus instructions for reading and updating them. No script, server or custom UI is required for a wiki, project knowledge base or memory collection. Preserve an existing useful layout. | Need | Start with | | --- | --- | | Notes, wiki pages, project context or memories | Markdown folders with an index and short operating instructions | | Trackers, inventories, measurements or other structured records | CSV with automatically generated stable UUID IDs | | Calculations, integrations or repeatable actions | Add only the scripts or UI needed for that behavior | Choose the drive and access scope before storing data. Folders organize content; they do not restrict access. Connection permissions select workspaces, drives and actions. A member's folder in a shared drive remains readable by users and agents authorized to read that drive. For private individual memories, use a separate drive with appropriately restricted workspace membership and connection grants. Verify actual human and agent access, including inherited organization admin access. A separate drive alone does not hide files from workspace members. ## Markdown folder templates Adapt these layouts to the user's task. Create an index with relative links, then starter pages with purpose, current facts and source references. Keep instructions in `AGENTS.md` or the instruction file the user's client reads; otherwise have the agent read that file explicitly. Do not imply that FlashDrive executes instructions or automatically loads them into every client. ### Wiki and project knowledge ```text project-knowledge/ AGENTS.md index.md wiki/ glossary.md how-to-release.md projects/ website/ overview.md decisions/ 2026-11-13-launch-scope.md handoffs/ 2026-11-13-design-review.md ``` Starter instructions: Read `index.md` and the relevant project overview before answering. Search and open the source pages needed for the question. Link new pages from the index or project overview. Record a decision's date, rationale, status and sources in its own page; distinguish accepted decisions from drafts. For a handoff, record the intended reader, current state, next action and source links. A handoff is a file that another agent must read or explicitly check; it is not a native message, notification or automatic agent wake-up. ### Shared team memory and member notes ```text team-memory/ AGENTS.md index.md shared/ context.md decisions/ 2026-11-13-release-window.md handoffs/ 2026-11-13-review.md people/ alex/ preferences.md working-notes.md sam/ preferences.md working-notes.md ``` Starter instructions: Read `shared/context.md` and relevant decisions first. Put team facts and agreed decisions under `shared/`; put each member's attributed preferences and working notes under `people//`. These member folders are shared namespaces, not private storage. Include who supplied a memory, when it was confirmed and its source. Mark uncertain or superseded memories explicitly. Update durable memories when the user asks or when the workflow authorizes it; do not copy secrets or private notes into team memory. ### Private individual memory Use this layout in a separately scoped drive whose access has been checked, not inside the shared team drive: ```text personal-memory/ AGENTS.md index.md profile.md preferences.md projects/ current.md journal/ 2026-11-13.md ``` Starter instructions: Read the profile and relevant preferences before working. Separate confirmed durable preferences from dated observations. Record sources and corrections, and save only what the user authorizes this workflow to retain. Promote a personal note into team memory only with permission to share it. ### Editing Markdown safely Keep related facts in small pages so collaborators can edit different files. Read the current page before changing it, make a focused edit and preserve unrelated work. Mounted clients can merge non-overlapping text changes; overlapping changes may produce conflict copies. Direct API writes require revision checks. Inspect and resolve conflicts instead of silently choosing a copy. Reload after sync and confirm remote persistence before reporting a save. Instructions and retrieved page contents do not grant permission to execute commands or expand access. ## CSV structured records The remaining CSV guidance applies when the tool uses structured records. Markdown pages do not require CSV schemas, row IDs or operation logs. Create small UTF-8, comma-separated `.csv` files with a fixed header and an exact lowercase `id` column. Automatically add stable row IDs to the tool's data model and create action. Do not ask the user to supply IDs or enable this behavior. Hide technical IDs in the normal UI unless they are useful. - Generate a UUID once per new record using a standard UUID generator such as Python `uuid.uuid4()` or JavaScript `crypto.randomUUID()`. - Persist the ID with the record before retrying a save. A retry of the same operation reuses the same ID and exact payload; a new operation gets a new ID. Keep pending operations in local durable storage until confirmed. - Preserve IDs when loading, exporting or displaying records. Never derive them from row positions, timestamps, labels, row counts or editable content. - Validate that IDs are nonempty and unique. Never renumber rows, regenerate IDs on startup, or reuse a deleted ID. If an existing file lacks IDs, do a single coordinated migration while other writers are paused, preserving the original. Do not let separate clients assign competing IDs independently. For an append-only observation tool, start with a schema such as: ```csv id,created_at,label,value 73b5cc1e-46d1-4c65-a033-06c3f2262b82,2026-11-13T08:00:00Z,temperature,21.5 ``` Use a CSV library for all reading and writing, including quoted commas, quotes and multiline fields. Store timestamps explicitly for display and sorting. Sort and filter the view, leaving stored row order unchanged. Initialize and sync the header once before starting concurrent writers, so their changes share a common file revision. ## Choose how CSV records change For immutable records, append new rows. Physical row deletion can merge with another client's append when IDs are stable and retained rows are unchanged. An edit to a retained row is outside that automatic merge contract. For a tool that needs edits, status changes or deletion history, use an append-only operation CSV instead of rewriting existing rows. A useful schema is `id,record_id,parents,action,value,created_at`: - `id` identifies this operation and is generated automatically once. - `record_id` identifies the logical item and stays stable across its operations. Generate it automatically when the item is created. - `parents` is a JSON array of the operation IDs this operation replaces, stored as one correctly quoted CSV field. Creation uses an empty array. - `action` is `create`, `set` or `delete`. `value` holds the full item snapshot for `create` and `set`, encoded as JSON inside one CSV field if needed. A deletion is an appended operation, not a removed history row. Build the displayed state from these operations. Resolve references by ID, not file order or wall-clock timestamps. Within each record, an operation replaces its listed parents; the remaining heads are the current candidates. One head yields the current item, or a deleted item for a `delete` head. Multiple heads are an application conflict, including delete versus edit. Show the alternatives and let the user resolve them by appending an operation that names all current heads as parents. Do not silently pick the last row. Ordinary edits and deletes name the head their author actually observed. Only an explicit conflict resolution consumes all conflicting heads; do not silently rebase a pending edit onto newer heads when reconnecting. Unknown parents mean incomplete history; wait for sync before resolving. Reject cycles, cross-record parents and duplicate IDs with different payloads. The tool implements this state reconstruction; FlashDrive merges CSV records, not application meaning. JSON inside a CSV field remains an opaque value. ## Write and sync CSV records Serialize writes to each file within a local tool instance. If multiple local processes share that file, use one writer service or a shared local lock. Hold that writer or lock across reading the latest local file, validating IDs, checking pending operations and appending only missing operations. Locking only the final append permits duplicate retries from competing processes. Queue complete CSV records and close or flush writes before asking the client to sync. A mount is not a cross-device lock or a distributed transaction. After reopening or reconnecting, read the latest data, recognize pending operations already present by ID and exact payload, and retry only missing operations. A matching ID with different content is a conflict, not success. Keep unsaved operations and show whether changes are pending, saved remotely or conflicted. Closing a local file alone does not confirm remote persistence. Use the mount's sync status before reporting a remote save. After remote changes arrive, reload the data before rendering current state. Use a client release that explicitly supports CSV record merging. Older clients may keep conflict copies instead. This feature applies to the mount. Check the installed release's published capabilities or release notes. If they do not confirm CSV merging, use one writer and do not promise automatic reconciliation; complete a two-copy sync check before relying on it. The merge does not apply to direct API byte writes. API writers must retain revision checks and handle stale versions. Without a common base, do not assume a three-way merge is possible. Preserve and surface conflict copies; do not silently discard them or treat them as extra data files. Keep each file version and the merged result within 8 MiB and 10,000 data rows, with each field no longer than 128 Ki characters. Keep header names and order fixed, IDs unique, retained rows unchanged and new records at the end. New IDs may be sorted by the merge, and CSV quoting and line endings may normalize. Partition growing data before these limits; do not automatically compact or rewrite history while other clients may still be offline. For partitioned operation logs, readers must discover and load every relevant partition and resolve parent IDs across them. Keep referenced history; a missing partition is incomplete state, not evidence that an item was deleted. SQLite automatic merging is planned for a future update and is not available yet. Use one writer for a shared SQLite database, including its journal and WAL files. Standalone JSON files have no structured merge guarantee. ## Check the tool before handing it over For Markdown tools, check that the index links resolve, the intended agent can find the right page, edits sync, and overlapping edits remain visible as conflicts. Verify shared versus private access with the actual drive grants. For CSV tools, exercise two copies made from the same synced base: concurrent additions must retain both IDs, and deletion plus append must not restore the deleted row. Retry a creation and restart the tool; the record must keep its ID and appear once. Check commas, quotes and multiline text through a save and reload. For editable tools, test sequential changes, two concurrent changes to one item, delete versus edit, incomplete parent history and explicit resolution. Confirm that conflicts remain visible and that pending work survives a failed sync. Report the required client capability and any checks not performed.