--- 2md: 1 title: 2.md — read the point, explore the detail reader-style: calm --- 2.md is Markdown with room for depth and comparison. Read the whole story first, then open the explanations that matter to you. This public guide is a standalone reader. Practice comments stay in this browser; no AI session receives them. ## Why it exists {#why} An AI answer can bury its conclusion. A technical document can scatter one idea across several files. 2.md keeps a readable overview and attaches the detail to its subject. [See a before-and-after example](#detail-example "below") ## Read at your own depth {#reading} A **row** holds one topic. A fold opens its supporting explanation. A link can show a preview, open below, open beside the story, or enter a focused view. [Try the reading controls](#detail-controls "below") · [What is a reading path?](#detail-path "preview") ## Compare when it helps {#compare} Columns show different layers of the same topic: what a feature does, how it works, and what the code must do. Start with one column; add more when comparison helps. [Explore a software example](#detail-software "column") · [Write a comparison](#detail-columns "below") ## Discuss the exact passage {#discuss} Select text to comment on it. In a connected workspace, saved threads can become explicit questions or actions for your own AI session. Drafts remain private. [Comments, AI replies and revisions](#detail-comments "below") ## Make one in Markdown {#make} Write a useful overview, keep its important caveats visible, and place supporting details behind meaningful links. The source remains a text file named `something.2.md`. [Copy a starter](#detail-starter "below") · [Links, terms and evidence](#detail-authoring "below") · [Images and other sources](#detail-packages "below") · [Start a connected workspace](#detail-start "below") ## Before and after {#detail-example} **Before:** A long answer lists every implementation detail before explaining what to do. **After:** “Keep the current export format until we test the replacement. The replacement may lose comments.” That sentence carries the decision and its main caveat. The test procedure belongs underneath it. #### What would the test check? Export a document with comments, reopen it, and compare the text and comment anchors. Record failures before changing the default. This is an illustrative example, not a test result for 2.md. --- The principle is simple: shorten the first view without throwing away the explanation. ## Reading controls {#detail-controls} Use a link's view selector to choose how its target opens. The available actions include: - **Expand:** reveal a linked explanation in context. - **Open below:** keep the overview together and show detail underneath its section. - **Column:** put related material beside what you are reading. - **Focus:** give a longer explanation more screen space. - **Preview:** look up a term without leaving the current passage. [Open a definition below](#detail-path "below") · [Preview that definition](#detail-path "preview") Close returns to the surrounding story. Nested detail views can provide Back. The reading-history control stores view states in this browser. #### History, pins and reset The history control offers Back, Forward and a list of previous states. New actions append to that history. Reset returns to the overview. Pins keep useful rows available while you explore. Comments have their own controls; resetting the view does not delete them. Browser storage is local to this browser and site. Do not treat it as a backup or cross-device account sync. --- On a narrow screen, use the column selector to read one layer at a time. If a focus link opens inline, choose Focus from its view selector. ## Reading path {#detail-path} A reading path is the route you choose through an explanation. You might read the overview, open an example, then look up one unfamiliar term. The author provides useful connections. You decide how much detail to read. [Return to the control explanation](#detail-controls "below") ## A software editor {#detail-software} Imagine an editor with search, extensions and a workspace. These are illustrative components, not a description of a specific editor's implementation. #### Search **Behavior:** Find text across project files. **Architecture:** A search service scans allowed files and sends results to the interface. **Code responsibility:** Accept a query, honor exclusions, support cancellation, and return file locations. **Verification:** Check an excluded file never appears and a cancelled query stops updating the screen. #### Extensions **Behavior:** Add commands without changing the editor's core. **Architecture:** An extension host exposes a defined interface to plugins. **Code responsibility:** Register commands, validate inputs, and release resources when a plugin stops. **Verification:** Stop an extension and check that its commands and resources are removed. --- Each topic keeps its behavior, architecture, code responsibility and checks together. A larger guide can compare these as columns. ## Comparison syntax {#detail-columns} Declare columns once, then put each layer in a matching block. The same row ID keeps the topic aligned. ````markdown --- 2md: 1 title: Search — behavior and implementation columns: behavior: Behavior architecture: Architecture --- ## Search {#search} ::: behavior Find matching text across allowed project files. ::: ::: architecture A search service applies exclusions before returning matches. ::: ```` Use a separate comparison document when the main explanation should stay in one column. A missing layer is a gap to fill, not proof that implementation exists. ## Comments, AI and revisions {#detail-comments} **In this public guide:** Select a passage, save a comment, and use Copy comments to bring feedback into an AI conversation. Storage stays in this browser. **In a connected workspace:** Comments and replies belong to the document. An invited author session can answer a question when you explicitly send it. #### Ask, act and revise Ask AI requests an answer. An action request asks the connected session to do work. Saving a comment alone does not send it to AI. Replies stay in their threads. A document revision is a separate proposal. Publishing an approved revision keeps the document identity and its discussion history. An agent must be connected and listening. A saved question is not proof that the agent has received or answered it. #### Drafts and decisions Drafts are unfinished private writing. They are excluded from copied feedback, batch requests and regeneration inputs. Decision forms can collect Agree, Disagree, custom text or checkbox choices. Place each choice beside its explanation. Selecting a choice and sending it are separate actions. Ordinary Markdown task checkboxes describe work; they do not authorize an AI action. --- A copied comment includes the document name, source line, quoted passage and your feedback. Keep that context when you ask AI for the next version. ## Starter Markdown {#detail-starter} Save this as `proposal.2.md`. It contains one visible topic, a portable fold, and a hidden explanation. ````markdown --- 2md: 1 title: Our proposal reader-style: calm --- Start with the recommendation and the caveat that could change it. ## The decision {#decision} Keep the current approach until we test the alternative.
What will we test? Compare the result against the required behavior.
[Why this test?](#detail-test "preview") ## Why this test? {#detail-test} Explain the failure the test must detect and what success means. ```` A `####` heading also creates a fold. A following heading or `---` ends that fold. Native details remain useful in ordinary Markdown viewers. ## Links, terms and evidence {#detail-authoring} Link to a stable section ID. IDs beginning `detail-` stay out of the initial overview, so every hidden row needs an incoming link. ```markdown [Explanation](#detail-example "below") [Definition](#detail-path "preview") [Related layer](#detail-software "column") [Long explanation](#detail-example "modal") ``` The title selects a view; readers can change it through the view selector. Rich views require the 2.md reader. #### Terms Use a preview link for a rich definition. For simple definitions, add a Terms section: ```markdown ## Terms {#terms} - **row** (rows): One topic in the document. ``` Keep each glossary definition on one source line. Put long definitions in hidden detail rows instead. #### Evidence and unfinished work Link sources beside the claims they support. Separate observations, proposals and unknowns. A short summary does not establish that its claims are true. Portable assessment quotes can label a recommendation and its evidence. For example, `Recommend` with `Evidence: Supported` needs named evidence and stated limits. Use `- [ ]` for real unfinished work. Do not hide a qualification that would change the reader's decision. --- ## Images, screens and linked sources {#detail-packages} Images can sit beside the Markdown and use relative paths. Hosted publication requires an explicit asset manifest so the package contains the intended files. A screen preview is a separate HTML/CSS example, opened through a supported screen link. Mock buttons are examples unless a real application implements them. #### Documents and source maps A local collection can link Markdown documents and compare matching section IDs. Hosted packages can contain explicitly declared source documents and pinned passages. An ordinary file link does not upload its target. Live cross-document references are not currently supported by the hosted publication workflow. Keep source passages separate from your interpretation. A pinned source hash identifies the version; it does not prove that the interpretation is correct. --- The authoring skill contains the package and decision-form syntax. Use it when your document needs those features. ## Start a connected workspace {#detail-start} 1. [Sign in with Google](/auth/login). If you used an older account, choose Recover existing account once. 2. Open **Sessions → Connect agent** and follow the invitation instructions. The agent registers the current session; later sessions reuse the approved account. 3. Ask that session to create a 2.md document, publish it through its connection, and listen for requests. 4. Share the document or workspace with the intended readers. [Get the authoring skills](/api/agent/v1/skills) Documents start private. This guide is a separate public example. Signing in does not make your workspace public. You can also render a standalone HTML file from Markdown. That reader can keep browser-local comments without a connected AI session.