Hackmd Manage Notes

HackMD Note Manager

Use Microsoft Edge through Playwright for all HackMD operations. Treat the server-saved Markdown as the source of truth and preserve unrelated content.

Required browser workflow

1. Read and use the playwright skill for all browser operations.
2. Open HackMD with headed Microsoft Edge and a persistent profile: --browser msedge --headed --persistent.
3. Prefer the user's existing Edge profile when an authenticated workspace is required. If HackMD is logged out, leave the browser at the login page and ask the user to sign in manually. Never request, read, or enter their password.
4. Take a fresh snapshot before using element references and after navigation, dialogs, folder changes, editor mode changes, or reloads.
5. Use browser navigation, workspace search, and folder views to locate notes. Do not use hackmd-cli.
6. Keep the Edge window open unless the user asks to close it.
7. Do not assume a persistent Playwright CLI browser session can always be reused reliably across separate CLI invocations in every environment. If session reuse is flaky, prefer a single shell flow that performs open, inspection, bounded edit, reload, and post-reload verification in one command sequence.
8. If Playwright reports that the browser is not open while a persistent profile also appears locked or already in use, treat it as stale session state. Clear the stale browser/session state first, then restart the full note-edit flow against the target note URL instead of blindly reusing the previous session name.

Locate the target

• For this user's note-update tasks, only operate on notes inside the Codex folder. If the resolved note is outside Codex, stop and ask the user before making any change.
• In Edge, navigate through the workspace and requested folder rather than relying on a title-only global search when duplicate note names are possible.
• Confirm both the folder and exact note title before editing.
• For an existing note, inspect the relevant surrounding sections and the full document outline. Match its language, heading depth, prose density, code-block style, dates, and attribution conventions.
• If the requested target remains ambiguous after inspecting the workspace, ask the user before changing anything.

Create a note

1. Open the destination folder in Edge before creating the note.
2. Set the exact requested title and permissions.
3. Confirm the note is listed in the intended folder. If it is elsewhere, move it with normal workspace controls in Edge.
4. Write Markdown that follows any nearby project notes when the user requests a matching style.
5. Follow the safe editing and verification procedures below.

Write for the intended reader

• Treat the user's stated audience and technical background as a hard requirement. If they do not specify an audience for technical documentation, default to a beginner who is new to the domain.
• Explain each important code block and the role of its significant declarations, fields, control flow, constants, and function calls. Connect each code fragment to the larger execution or data flow.
• When discussing concrete implementation details, prefer fenced code blocks such as ```c, ```bash, and ```make instead of relying only on inline code spans. Use inline code for short identifiers, but use fenced blocks when the reader needs to parse real control flow, data structures, or command sequences.
• Define domain terms before relying on them, explain why the implementation is needed, and distinguish current behavior from limitations or future work.
• Focus beginner-oriented explanations on the document's actual technical domain. Do not reteach basic programming-language syntax unless the user asks for it or the syntax is essential to understanding the design.
• Include concrete input/output or command examples and a safe way to verify the result. Do not merely list changed files or paste code without explaining it.
• Match the existing note's style without copying its assumed knowledge level when the requested reader needs more foundational explanation.

Update a note safely

Before changing content:

1. Read the current Markdown from CodeMirror.
2. Record its length and identify a unique insertion or replacement marker.
3. Confirm the marker count is exactly one. Do not replace content using a non-unique heading or phrase.
4. Preserve the original source in memory until server verification succeeds.

Choose the narrowest edit:

• Append a new change-log section at the document end when documenting new work.
• For this user's documentation sync or progress updates, default to appending a dated change-log entry instead of rewriting the main body unless the user explicitly asks for a section rewrite.
• Change-log entries should describe technical behavior, interfaces, data flow, constraints, or design intent. Do not use them to record routine README syncing, pushes, tool installation, or the agent's work log.
• Replace only the requested section when revising existing documentation.
• Do not rewrite the entire note merely to add a section.

Do not use playwright-cli type; per-character typing can trigger CodeMirror indentation and auto-completion and corrupt the document. Focus the hidden CodeMirror textarea with eval, then update the CodeMirror document atomically. Derive the new value from the current value and the verified unique boundary. Use setValue only when creating an empty note or when the complete preserved source is included; otherwise prefer a bounded replaceRange.

After the edit, verify in the editor before waiting for sync:

• expected title or heading exists;
• insertion marker appears once;
• required identifiers, dates, links, or commit hashes exist;
• document length is plausible;
• the tail is complete and code fences are balanced;
• unrelated leading content remains unchanged.

Handle synchronization conflicts

If HackMD reports an offline version or merge conflict:

1. Open Merge and sync and compare the offline and current versions.
2. Identify which side contains the complete intended edit and whether the other side has unrelated newer work.
3. Apply the offline changes only when they are the verified complete edit and do not discard unrelated server changes.
4. Discard the offline changes when the server version is authoritative, then reapply the bounded edit to the latest source.
5. If both sides contain independent changes or the correct resolution is not clear, stop and ask the user.
6. Finish the merge dialog and confirm the offline/conflict banner disappears.

Never select a conflict-resolution action merely to dismiss the dialog.

Verify server persistence

1. Wait for HackMD's save state to settle and reload the page so the editor reads the server version again.
2. Re-read the server Markdown from the page and repeat the structural checks.
3. Confirm there is no offline-edit or conflict banner.
4. Report completion only after the post-reload source contains the intended content exactly once.
5. If the reload or verification step is interrupted by Playwright session loss, rerun the entire verification flow against the saved note URL and use the reloaded CodeMirror content as the source of truth.

Safety boundaries

• Do not delete notes or folders unless the user explicitly asks.
• Do not change sharing, publishing, permissions, ownership, or team membership unless explicitly requested.
• Do not expose note contents, authentication state, or private URLs beyond what is necessary for the task.
• Do not resolve ambiguous concurrent edits without user confirmation.