pi-weave 0.1.1 → 0.1.3

package/README.md

@@ -1,7 +1,14 @@
 # pi-weave
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/EranYonai/pi-weave/main/docs/logo-high-res.jpg" alt="pi-weave — an agent-native knowledge workspace" width="220"/>
+  <img src="https://raw.githubusercontent.com/EranYonai/pi-weave/main/docs/pi-weave-logo.jpg" alt="pi-weave — an agent-native knowledge workspace" width="220"/>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/pi-weave"><img alt="npm version" src="https://img.shields.io/npm/v/pi-weave?color=blue&logo=npm"></a>
+  <a href="https://github.com/EranYonai/pi-weave/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/EranYonai/pi-weave/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/EranYonai/pi-weave/releases"><img alt="release" src="https://img.shields.io/github/v/release/EranYonai/pi-weave?color=blue&logo=github"></a>
+  <a href="./LICENSE"><img alt="license: MIT" src="https://img.shields.io/npm/l/pi-weave?color=green"></a>
 </p>
 
 **An agent-native knowledge workspace for your life and your code.**
@@ -29,13 +36,17 @@ agents.** No opaque databases. No lock-in formats.
 ## Install
 
 ```bash
-pi install npm:pi-weave             # from npm
+pi install npm:pi-weave             # from npm (recommended)
 pi install git:github.com/EranYonai/pi-weave   # from git
 pi install /path/to/pi-weave       # local path
 ```
 
 Or for development: `pi -e ./src/pi/index.ts`.
 
+The package is [published on npm](https://www.npmjs.com/package/pi-weave);
+releases are cut from `main` and auto-published with provenance attestation
+([Publish workflow](.github/workflows/publish.yml)).
+
 ## What you get
 
 | Surface | Name | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-weave",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "An agent-native knowledge workspace for your life and your code. Smart notepad + repository exploration, readable by humans and agents alike.",
   "type": "module",
   "sideEffects": false,
@@ -41,7 +41,7 @@
     "skills": [
       "./skills"
     ],
-    "image": "https://raw.githubusercontent.com/EranYonai/pi-weave/main/docs/logo-high-res.jpg"
+    "image": "https://raw.githubusercontent.com/EranYonai/pi-weave/main/docs/pi-weave-logo.jpg"
   },
   "scripts": {
     "test": "vitest run",

package/skills/weave-notepad/SKILL.md

@@ -18,23 +18,35 @@ available), operate on the files directly:
 - Each note has YAML front matter: `title`, `created`, `updated` (ISO-8601),
   `tags: [..]`, and `source: human | agent | generated`.
 - `weave_note` actions: `list`, `get`, `add`, `append`, `finalize`, `search`.
-  `finalize` restructures the body *above* the `## Raw notes` tail and preserves
+  `finalize` restructures the body *above* the `## Raw` tail and preserves
   the tail verbatim.
 
-## Dictation mode ("I will write, you expand")
+## Raw Tail Format
 
-When the user is dictating (e.g. "I am in an interview", "I will write, you
-expand on my draft"), behave as notepad + expander:
+Every note maintains a verbatim, append-only raw section at the bottom separated by a horizontal rule (`---`):
 
-1. **Every raw line the user adds MUST be captured.** Append their words
-   verbatim to the active note (`weave_note` action=append).
-2. **Then expand it immediately.** Add `## Raw: "<user's line>"` followed by
-   `**Expand:** <polished, interview-ready passage>` (STAR-style when
-   applicable). Never append without expanding.
-3. **Terse replies.** Acknowledge briefly and show what was written. Do NOT
-   dump long prose in chat — the expansion lives in the note, not the reply.
-4. **Small talk / questions → ask the user.** If you want to chat, clarify,
-   or ask something, pose it to the user directly and briefly, and wait.
+---
+
+## Raw
+<!-- NEVER edit below this line. Verbatim user input preserved here. -->
+
+```
+<Initial verbatim input>
+```
+
+<!-- appended 2026-08-23 08:45 -->
+```
+<Follow-up verbatim user input>
+```
+
+### How to capture and append raw input
+
+1. **Divider and Heading**: The raw section starts with `---` followed by `## Raw` and the notice comment: `<!-- NEVER edit below this line. Verbatim user input preserved here. -->`.
+2. **Code Blocks for Verbatim Input**: Always wrap verbatim user lines inside code blocks (triple backticks).
+3. **Date and Time on Appends**: When appending subsequent snippets, prepend each snippet with: `<!-- appended YYYY-MM-DD HH:MM -->`.
+4. **Finalization (`finalize`)**:
+   - `finalize` replaces or structures content only above the `---` and `## Raw` section.
+   - The `## Raw` block and all verbatim code blocks are never modified or removed.
 
 ## When to take a note
 
@@ -57,11 +69,11 @@ explicit by design.
 2. Title: short noun phrase ("Auth boundary decision", not "Notes").
 3. **Scribble in, verbatim.** When the user is dictating, append their words
    to the note as rough, verbatim scribbles — no silent rewording. Keep them
-   under a `## Raw notes` tail at the end of the note.
+   under the `## Raw` tail format at the end of the note.
 4. **Finalize on request.** When the user says "finalize this" / "clean this
    up", restructure the body *above* the raw tail: front-loaded summary,
    sections, entities, links. Use `weave_note` action=finalize (or edit the
-   file directly in other harnesses). Move nothing out of `## Raw notes` — it
+   file directly in other harnesses). Move nothing out of `## Raw` — it
    is append-only and never rewritten.
 5. Tags: 1–4 lowercase tags; reuse existing tags when possible.
 6. Provenance: notes the user scribbled stay `source: human` (finalization is

package/src/core/vault.ts

@@ -124,15 +124,38 @@ export async function appendToNote(
   return { slug, ...meta, body };
 }
 
-/** The append-only tail where verbatim user scribbles live (docs/notepad.md §4). */
-export const RAW_NOTES_HEADING = "## Raw notes";
+/** Format a verbatim user scribble as an append-only raw block with a timestamp. */
+export function formatRawAppend(rawText: string, date: Date = new Date()): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  const yyyy = date.getFullYear();
+  const mm = pad(date.getMonth() + 1);
+  const dd = pad(date.getDate());
+  const hh = pad(date.getHours());
+  const min = pad(date.getMinutes());
+  const timestamp = `${yyyy}-${mm}-${dd} ${hh}:${min}`;
+
+  return `<!-- appended ${timestamp} -->\n\`\`\`\n${rawText.trim()}\n\`\`\``;
+}
+
+/** The append-only tail where verbatim user scribbles live. */
+export const RAW_NOTES_HEADING = "## Raw";
 
 /**
- * Extract the `## Raw notes` tail (heading + everything after) verbatim, or
- * "" when the note has no raw tail. Used by finalization so the literal
- * record of the user's words is never rewritten.
+ * Extract the raw tail (including separator line, heading, and everything after) verbatim.
  */
 export function extractRawTail(body: string): string {
+  // Check for '---' preceding ## Raw or ## Raw directly
+  const sepIdx = body.indexOf("\n---\n\n## Raw");
+  if (sepIdx !== -1) {
+    return body.slice(sepIdx + 1).trimEnd();
+  }
+  if (body.startsWith("---\n\n## Raw") || body.startsWith("---\n## Raw")) {
+    return body.trimEnd();
+  }
+  const sepIdx2 = body.indexOf("\n---\n## Raw");
+  if (sepIdx2 !== -1) {
+    return body.slice(sepIdx2 + 1).trimEnd();
+  }
   const idx = body.indexOf(RAW_NOTES_HEADING);
   if (idx === -1) return "";
   return body.slice(idx).trimEnd();
@@ -141,7 +164,7 @@ export function extractRawTail(body: string): string {
 export interface FinalizeNoteInput {
   /**
    * The restructured body ABOVE the raw tail (front-loaded summary, sections,
-   * entities, links). The `## Raw notes` tail is preserved verbatim beneath it.
+   * entities, links). The `## Raw` tail is preserved verbatim beneath it.
    */
   body: string;
   /** Injectable clock for tests. */
@@ -149,7 +172,7 @@ export interface FinalizeNoteInput {
 }
 
 /**
- * Finalize a note: replace the body above the `## Raw notes` tail with a
+ * Finalize a note: replace the body above the `## Raw` tail with a
  * restructured version, preserving the raw tail verbatim (append-only).
  * Returns null when the note is missing or the slug is unsafe.
  */

package/src/pi/tools/noteTool.ts

@@ -7,6 +7,7 @@ import {
   appendToNote,
   finalizeNote,
   formatNote,
+  formatRawAppend,
   getNote,
   listNotes,
   NOTES_DIR,
@@ -176,3 +177,5 @@ export function registerNoteTool(pi: ExtensionAPI): void {
     },
   });
 }
+
+export { formatRawAppend };