niahere 0.2.13 → 0.2.15

package/skills/llms-txt/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: llms-txt
+description: Expert guidance for creating, improving, and maintaining llms.txt/llms-full.txt for LLM-aware content indexing and AI retrieval.
+argument-hint: "[path] [goal]"
+license: MIT
+metadata:
+  author: aman
+  version: "1.0.0"
+---
+
+# llms.txt Skill
+
+Use this skill when the user asks to create, review, improve, or scale `llms.txt`/`llms-full.txt` for a site, docs portal, or product.
+
+## Goals
+
+- Explain what `llms.txt` is and when to use it.
+- Help write high-signal, low-noise link collections for AI readers.
+- Improve existing files with ranking/order, scope, freshness, and maintainability changes.
+- Provide tooling and review checks to prevent low-quality output.
+
+## Runtime Scope
+
+- Works for any static or dynamic site.
+- Can be used alongside SEO artifacts (`robots.txt`, `sitemap.xml`, `robots` metadata); it is **not** a replacement.
+- Use when the ask is about discoverability for AI systems, docs quality for retrieval, or reducing crawl noise for model context.
+
+## What `llms.txt` Is
+
+- A curated, human-readable index intended for machine readers.
+- A concise map of authoritative pages, organized by topic.
+- A guidance file, not a permission file:
+  - It does not grant permission or block crawling.
+  - It signals what content is high value.
+
+## Who This Helps
+
+- Content/site owners who want AI systems to prioritize reliable pages.
+- Product teams building LLM-powered assistants/crawlers.
+- Internal teams maintaining docs, knowledge bases, and API references.
+- External integrators that consume public docs and need stable entry points.
+
+## Why It Helps
+
+- Reduces ambiguity by exposing intent: what should be read first.
+- Improves consistency of summaries and question-answering quality from your site.
+- Helps new models/tools avoid outdated, low-value, and duplicate pages.
+- Supports faster onboarding for AI agents and copilots that consume your site.
+
+## Core Rules
+
+1. Keep the file short and opinionated.
+2. Use a stable order: high-level entry first, then deeper pages.
+3. Group by purpose (`Overview`, `Getting Started`, `Core`, `API`, `Projects`, etc.).
+4. Use clear one-line descriptions for each link.
+5. Prefer canonical URLs and remove dead/redirected links.
+6. Mark lower-priority links as optional.
+7. Update with every meaningful content change.
+
+## Standard Authoring Pattern
+
+```
+# Site or Product Name
+
+> One-line description of what the site provides.
+
+## Overview
+- [Home](https://example.com/) : What this website is and who it serves.
+- [About](https://example.com/about) : Core context and mission.
+
+## Core documentation
+- [Getting Started](https://example.com/docs/getting-started) : Setup and onboarding path.
+- [Concepts](https://example.com/docs/concepts) : Key ideas and mental models.
+
+## Projects / Products
+- [Project Index](https://example.com/projects) : Curated project list.
+- [Featured Project](https://example.com/projects/featured-project) : High-priority example.
+
+## Optional
+- [Blog](https://example.com/blog) : Current essays; useful but not required for basic understanding.
+```
+
+## Writing `llms.txt` (Step-by-step)
+
+1. Define audience and primary task (e.g., onboarding, evaluation, API usage, portfolio review).
+2. Select 10-30 high-signal URLs only.
+3. Add required top-level sections:
+   - `#` title
+   - `##` grouped headings
+   - bullet list links with short purpose text
+4. Order by usefulness for first-pass understanding.
+5. Mark noisy or secondary pages under `## Optional`.
+6. Validate all links and prune stale pages.
+7. Track version updates in repo changelog or notes.
+
+## Improve Existing `llms.txt`
+
+- Remove dead pages and broken links.
+- Consolidate repeated or overlapping pages.
+- Move outdated material to `llms-full.txt` if too large for primary file.
+- Keep first section reserved for decision-making pages.
+- Add or refresh descriptions when APIs/features move.
+- Add explicit entry for changelogs or release notes if they affect understanding.
+- Re-rank links to surface most important pages first.
+
+## Validation Checklist
+
+- File is plain text/markdown and accessible at `/llms.txt`.
+- No marketing fluff; every bullet is actionable/identifying.
+- Descriptions are factual and specific.
+- URLs are absolute, canonical, and reachable.
+- No duplicate links across sections.
+- Total size is practical (start lean, grow with scale).
+
+## Next.js / Vercel Example
+
+- Add file at `public/llms.txt`.
+- Keep it in git with your content updates.
+- Optional: generate periodically from a docs manifest if your site grows quickly.
+
+## Common Mistakes
+
+- Treating it as SEO replacement.
+- Adding a giant full list of all pages.
+- Using vague descriptions like "click here".
+- Outdated links after page moves.
+- Mixing private/internal URLs with public consumption targets.
+
+## Additional Files
+
+- Optional: `llms-full.txt` for exhaustive references only when needed.
+- Optional: `llms-<area>.txt` variants for domain-specific sections.
+
+## Resources to Explore
+
+- llms.txt proposal: https://llmstxt.org/
+- llms.txt repository: https://github.com/AnswerDotAI/llms-txt
+- llms.txt parser/usage notes: https://github.com/AnswerDotAI/llms-txt/blob/main/README.md
+- AI content discoverability baseline (model context quality): https://www.sitemaps.org/protocol.html
+- Crawling guidance reference: https://developers.google.com/search/docs/crawling-indexing/overview
+- Robots standard: https://developers.google.com/search/docs/crawling-indexing/robots/robots_txt

package/skills/pr-reviewer/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: pr-reviewer
+description: Review pull requests and code diffs for correctness, design, security, performance, and style. Use when asked to "review this PR", "review my changes", "check this diff", or before merging code. Language-aware — adapts to the project's stack, idioms, and conventions.
+---
+
+# PR Reviewer
+
+Structured code review for pull requests and diffs. Adapts to the project's language, framework, and conventions by reading project documentation before reviewing code.
+
+## Quick Start
+
+1. Gather context (project docs, language, conventions).
+2. Read the full diff.
+3. Run the review passes below.
+4. Output structured findings.
+
+## Step 1: Gather Project Context
+
+Before looking at any code, read these files if they exist:
+
+- `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` — project rules, code style, conventions
+- `README.md` — project purpose, architecture overview
+- `.editorconfig`, linter configs (`.eslintrc`, `pyproject.toml`, `rustfmt.toml`, etc.)
+- `CONTRIBUTING.md` — contribution guidelines
+
+From these, extract:
+- **Language & framework** (TypeScript/Bun, Python/Django, Rust, Go, etc.)
+- **Code style rules** (naming, imports, formatting)
+- **Testing expectations** (unit, integration, what framework)
+- **Architecture patterns** (module layout, type organization)
+- **Any explicit review criteria** the project defines
+
+## Step 2: Get the Diff
+
+```bash
+# For uncommitted changes
+git diff
+
+# For staged changes
+git diff --cached
+
+# For a branch vs main
+git diff main...HEAD
+
+# For a specific PR (GitHub)
+gh pr diff <number>
+```
+
+Read all changed files in full (not just the diff) when context is needed to understand the change.
+
+## Step 3: Review Passes
+
+Run these passes in order. Each pass focuses on one concern — don't mix them.
+
+### Pass 1: Intent & Design
+
+- Does the change do what it claims? (PR title/description vs actual diff)
+- Is the approach right? Could this be simpler?
+- Is this the right place for this code? (module boundaries, separation of concerns)
+- Over-engineering check: is code more generic than needed? Solving future problems?
+- Are there unnecessary changes? (unrelated refactors, formatting-only changes mixed in)
+
+### Pass 2: Correctness & Logic
+
+- Off-by-one errors, boundary conditions, null/undefined handling
+- Race conditions in async/concurrent code
+- State mutations — are they safe? Expected?
+- Error paths — what happens when things fail?
+- Data flow — does data transform correctly through the pipeline?
+- Are edge cases handled? (empty inputs, large inputs, unicode, timezone, etc.)
+
+### Pass 3: Language Idioms & Best Practices
+
+Adapt to the project's language. Apply that language's conventions:
+
+**TypeScript/JavaScript:**
+- Proper typing (no unnecessary `any`, correct generics, discriminated unions)
+- Async/await over raw promises, proper error propagation
+- Immutability preferences, const over let
+- Node.js/Bun API usage (streams, buffers, path handling)
+
+**Python:**
+- PEP 8, Pythonic idioms (comprehensions, context managers, generators)
+- Type hints where the project uses them
+- Proper exception hierarchy, avoid bare `except:`
+- f-strings over `.format()` or `%`
+
+**Go:**
+- Error handling patterns (check errors, don't ignore)
+- Naming conventions (exported vs unexported, receiver names)
+- Goroutine safety, channel usage, context propagation
+- Avoid unnecessary interfaces
+
+**Rust:**
+- Ownership and borrowing correctness
+- Error handling (`Result`/`Option`, avoid `.unwrap()` in library code)
+- Clippy-clean idioms, iterator chains over manual loops
+- Lifetime annotations only when needed
+
+**Other languages:** Apply equivalent idiomatic standards. When unsure, check what the existing codebase does.
+
+### Pass 4: Security
+
+- Input validation at system boundaries (user input, API payloads, file uploads)
+- SQL injection, XSS, command injection, path traversal
+- Auth/authz checks — are they in the right place? Can they be bypassed?
+- Secrets — no hardcoded keys, tokens, passwords
+- Dependency changes — are new deps trusted? Pinned versions?
+- OWASP Top 10 for web-facing code
+
+### Pass 5: Performance
+
+- N+1 queries, missing indexes, unbounded queries
+- Unnecessary allocations in hot paths
+- Missing pagination for list endpoints
+- Large payloads loaded into memory
+- Blocking operations in async contexts
+- Caching opportunities (or cache invalidation bugs)
+
+### Pass 6: Testing
+
+- Are new code paths tested?
+- Do tests actually assert behavior (not just "doesn't crash")?
+- Edge cases covered? Error paths?
+- Test names describe the scenario, not the implementation
+- No test pollution (shared mutable state between tests)
+- Missing tests flagged as an issue, not ignored
+
+### Pass 7: Documentation & Naming
+
+- Are names self-documenting? (variables, functions, types)
+- Complex logic has comments explaining *why*, not *what*
+- Public APIs have documentation
+- Misleading names or outdated comments
+- Breaking changes documented
+
+## Step 4: Output Format
+
+Structure the review as:
+
+```markdown
+## PR Review: <title or summary>
+
+### Summary
+<1-2 sentences on what the PR does and overall assessment>
+
+### Critical (must fix)
+- **[file:line]** Description of the issue
+  - Why it matters
+  - Suggested fix
+
+### Important (should fix)
+- **[file:line]** Description
+
+### Suggestions (nice to have)
+- **[file:line]** Description
+
+### Positive
+- Call out good patterns, clean abstractions, solid test coverage
+```
+
+**Severity guide:**
+- **Critical:** Bugs, security issues, data loss risks, broken functionality
+- **Important:** Design issues, missing tests, performance problems, convention violations
+- **Suggestions:** Style improvements, alternative approaches, minor cleanups
+- **Positive:** Things done well — always include at least one
+
+## Decision Points
+
+- If the diff is > 500 lines: split review by file/module, note that the PR might benefit from being broken up
+- If no project docs exist: infer conventions from the existing codebase (read 2-3 similar files)
+- If the PR has no description: note it, then infer intent from the diff
+- If you're unsure about a pattern: flag it as a question, not a demand
+
+## Anti-patterns to Avoid in Reviews
+
+- Don't bikeshed on style that a linter should catch
+- Don't rewrite the PR in your head — review what's there
+- Don't block on personal preference when the code is correct
+- Don't ignore test quality — bad tests are worse than no tests
+- Don't review with only the diff — read surrounding code for context
+
+## References
+
+- [Google Engineering Practices — What to Look For](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+- [Google — The Standard of Code Review](https://google.github.io/eng-practices/review/reviewer/standard.html)
+- [Augment — 40 Questions Before You Approve](https://www.augmentcode.com/guides/code-review-checklist-40-questions-before-you-approve)

package/src/chat/engine.ts

@@ -103,31 +103,88 @@ function truncate(s: string, max: number): string {
 }
 
 function formatToolUse(tool: string, input: any): string {
-  if (!input || typeof input !== "object") return tool;
+  if (!input || typeof input !== "object") return tool.toLowerCase();
 
   switch (tool) {
+    // File operations
     case "Bash":
-      return input.command ? `$ ${truncate(input.command, 50)}` : "running command";
+      return input.description
+        ? truncate(input.description, 60)
+        : input.command ? `$ ${truncate(input.command, 55)}` : "running command";
     case "Read":
       return input.file_path ? `reading ${basename(input.file_path)}` : "reading file";
     case "Edit":
       return input.file_path ? `editing ${basename(input.file_path)}` : "editing file";
     case "Write":
       return input.file_path ? `writing ${basename(input.file_path)}` : "writing file";
+    case "NotebookEdit":
+      return input.file_path ? `editing notebook ${basename(input.file_path)}` : "editing notebook";
+
+    // Search operations
     case "Grep":
-      return input.pattern ? `searching: ${truncate(input.pattern, 40)}` : "searching";
+      return input.pattern ? `searching for "${truncate(input.pattern, 35)}"` : "searching code";
     case "Glob":
-      return input.pattern ? `finding: ${truncate(input.pattern, 40)}` : "finding files";
+      return input.pattern ? `finding ${truncate(input.pattern, 40)}` : "finding files";
+    case "ToolSearch":
+      return input.query ? `looking up tool: ${truncate(input.query, 40)}` : "searching tools";
+
+    // Agent & task operations
     case "Agent":
+      return input.description ? `⟩ ${truncate(input.description, 55)}` : "running agent";
     case "Task":
-      return input.description || input.prompt?.slice(0, 40) || "running agent";
+      return input.description || input.prompt?.slice(0, 50) || "running task";
+    case "TaskCreate":
+      return input.description ? `starting: ${truncate(input.description, 45)}` : "creating task";
+    case "TaskGet":
+    case "TaskOutput":
+      return "checking task progress";
+    case "TaskList":
+      return "listing tasks";
+    case "TaskStop":
+      return "stopping task";
+    case "TaskUpdate":
+      return "updating task";
+    case "SendMessage":
+      return input.to ? `messaging ${truncate(String(input.to), 30)}` : "sending message";
+
+    // Web operations
     case "WebFetch":
-      return input.url ? `fetching ${truncate(input.url, 50)}` : "fetching";
+      return input.url ? `fetching ${truncate(input.url, 50)}` : "fetching url";
     case "WebSearch":
-      return input.query ? `searching: ${truncate(input.query, 40)}` : "searching web";
+      return input.query ? `web search: ${truncate(input.query, 40)}` : "searching the web";
+
+    // Planning & workflow
+    case "EnterPlanMode":
+      return "entering plan mode";
+    case "ExitPlanMode":
+      return "exiting plan mode";
+    case "EnterWorktree":
+      return "creating worktree";
+    case "ExitWorktree":
+      return "leaving worktree";
+
+    // Skill & todo
+    case "Skill":
+      return input.skill ? `using /${truncate(input.skill, 40)}` : "invoking skill";
+    case "TodoWrite":
+    case "TodoRead":
+      return tool === "TodoWrite" ? "updating checklist" : "reading checklist";
+
+    // LSP
+    case "LSP":
+      return input.command ? `lsp: ${truncate(input.command, 50)}` : "querying language server";
+
+    // MCP tools (plugin_name__tool_name pattern)
     default: {
-      const val = input.command || input.pattern || input.query || input.file_path || input.description || "";
-      return val ? `${tool} ${truncate(String(val), 50)}` : tool;
+      // Handle MCP tools like mcp__playwright__browser_navigate
+      if (tool.startsWith("mcp__")) {
+        const parts = tool.split("__");
+        const action = parts[parts.length - 1]?.replace(/_/g, " ") || tool;
+        const val = input.url || input.selector || input.text || input.value || "";
+        return val ? `${action}: ${truncate(String(val), 40)}` : action;
+      }
+      const val = input.description || input.command || input.pattern || input.query || input.file_path || "";
+      return val ? `${tool.toLowerCase()}: ${truncate(String(val), 50)}` : tool.toLowerCase();
     }
   }
 }
@@ -148,7 +205,13 @@ export async function createChatEngine(opts: EngineOptions): Promise<ChatEngine>
   const systemPrompt = buildSystemPrompt("chat", channel);
   const cwd = homedir();
 
-  let sessionId = resume ? await Session.getLatest(room) : null;
+  let sessionId: string | null = null;
+  if (typeof resume === "string") {
+    // Specific session ID provided
+    sessionId = resume;
+  } else if (resume) {
+    sessionId = await Session.getLatest(room);
+  }
 
   // Verify session file exists on disk before attempting resume
   if (sessionId && !sessionFileExists(sessionId, cwd)) {

package/src/chat/repl.ts

@@ -4,8 +4,115 @@ import { runMigrations } from "../db/migrate";
 import { closeDb } from "../db/connection";
 import { getMcpServers, setMcpServers } from "../mcp";
 import { createNiaMcpServer } from "../mcp/server";
+import { Session } from "../db/models";
+import { relativeTime } from "../utils/format";
 
-export async function startRepl(resume = false): Promise<void> {
+// ANSI helpers
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const CYAN = "\x1b[36m";
+const RESET = "\x1b[0m";
+const CLEAR_LINE = "\x1b[2K\r";
+
+// Braille spinner frames
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+class StatusLine {
+  private frame = 0;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private text = "";
+  private active = false;
+
+  start(initialText = "thinking") {
+    this.text = initialText;
+    this.active = true;
+    this.frame = 0;
+    this.render();
+    this.timer = setInterval(() => {
+      this.frame = (this.frame + 1) % SPINNER.length;
+      this.render();
+    }, 80);
+  }
+
+  update(text: string) {
+    this.text = text;
+    if (this.active) this.render();
+  }
+
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.active) {
+      process.stderr.write(CLEAR_LINE);
+    }
+    this.active = false;
+  }
+
+  private render() {
+    const spinner = SPINNER[this.frame];
+    process.stderr.write(`${CLEAR_LINE}${DIM}  ${spinner} ${this.text}${RESET}`);
+  }
+}
+
+function truncatePreview(text: string, max: number): string {
+  const oneline = text.replace(/\n/g, " ").trim();
+  return oneline.length > max ? oneline.slice(0, max) + "…" : oneline;
+}
+
+async function pickSession(): Promise<string | null> {
+  const sessions = await Session.getRecent("terminal", 10);
+  if (sessions.length === 0) {
+    console.log(`${DIM}no previous sessions${RESET}\n`);
+    return null;
+  }
+
+  const now = new Date();
+  console.log(`\n${DIM}recent sessions:${RESET}\n`);
+
+  for (let i = 0; i < sessions.length; i++) {
+    const s = sessions[i];
+    const age = relativeTime(new Date(s.updatedAt), now);
+    const preview = s.preview ? truncatePreview(s.preview, 50) : "empty session";
+    const msgs = `${s.messageCount} msg${s.messageCount !== 1 ? "s" : ""}`;
+    console.log(`  ${BOLD}${i + 1}${RESET}  ${preview}  ${DIM}${msgs} · ${age}${RESET}`);
+  }
+
+  console.log(`\n  ${DIM}n${RESET}  start new session`);
+  console.log();
+
+  return new Promise<string | null>((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question(`${DIM}select [1-${sessions.length}, n]:${RESET} `, (answer) => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+
+      if (trimmed === "n" || trimmed === "new") {
+        resolve(null);
+        return;
+      }
+
+      const idx = parseInt(trimmed, 10);
+      if (idx >= 1 && idx <= sessions.length) {
+        resolve(sessions[idx - 1].id);
+      } else if (trimmed === "" && sessions.length > 0) {
+        // Default: most recent session
+        resolve(sessions[0].id);
+      } else {
+        resolve(null);
+      }
+    });
+  });
+}
+
+export type ChatMode = "continue" | "new" | "pick";
+
+export async function startRepl(mode: ChatMode = "continue"): Promise<void> {
   try {
     await runMigrations();
   } catch (err) {
@@ -23,15 +130,30 @@ export async function startRepl(resume = false): Promise<void> {
     } catch {}
   }
 
+  // Determine session to use
+  let resume: boolean | string = false;
+
+  if (mode === "pick") {
+    const picked = await pickSession();
+    if (picked) {
+      resume = picked;
+    }
+  } else if (mode === "continue") {
+    resume = true;
+  }
+
   const engine = await createChatEngine({ room: "terminal", channel: "terminal", resume, mcpServers: getMcpServers() });
 
-  console.log(resume && engine.sessionId ? "Resumed previous session." : "New chat session started.");
-  console.log('Type your message and press Enter. Type "exit" or Ctrl+C to quit.\n');
+  // Welcome
+  const isResumed = engine.sessionId && resume;
+  const sessionNote = isResumed ? "resumed" : "new session";
+  console.log(`\n${DIM}nia chat${RESET} ${DIM}(${sessionNote})${RESET}`);
+  console.log(`${DIM}type /exit to quit${RESET}\n`);
 
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
-    prompt: "you > ",
+    prompt: `${BOLD}>${RESET} `,
   });
 
   rl.prompt();
@@ -44,31 +166,74 @@ export async function startRepl(resume = false): Promise<void> {
       return;
     }
 
-    const exitCommands = [".exit", ".quit", "exit", "quit"];
+    const exitCommands = ["/exit", "/quit", ".exit", ".quit", "exit", "quit"];
     if (exitCommands.includes(input.toLowerCase())) {
       rl.close();
       return;
     }
 
-    process.stdout.write("\n");
+    const status = new StatusLine();
+    status.start("thinking");
+
+    let streamedLength = 0;
+    let responseStarted = false;
 
     try {
       const { result, costUsd, turns } = await engine.send(input, {
-        onActivity(status) {
-          process.stdout.write(`\x1b[2m  ${status}\x1b[0m\n`);
+        onStream(textSoFar) {
+          // Stream response text as it arrives
+          if (!responseStarted) {
+            status.stop();
+            process.stdout.write("\n");
+            responseStarted = true;
+          }
+          const newText = textSoFar.slice(streamedLength);
+          if (newText) {
+            process.stdout.write(newText);
+            streamedLength = textSoFar.length;
+          }
+        },
+        onActivity(activityText) {
+          if (!responseStarted) {
+            status.update(activityText);
+          }
         },
       });
-      console.log(`nia > ${result.trim()}\n`);
+
+      // If streaming didn't fire (e.g. tool-only turns), print the result
+      if (!responseStarted && result.trim()) {
+        status.stop();
+        process.stdout.write(`\n${result.trim()}`);
+      } else if (responseStarted) {
+        // Print any remaining text that wasn't streamed
+        const remaining = result.slice(streamedLength);
+        if (remaining.trim()) {
+          process.stdout.write(remaining);
+        }
+      } else {
+        status.stop();
+      }
+
+      // Cost line
+      const costStr = costUsd > 0 ? `$${costUsd.toFixed(4)}` : "";
+      const turnsStr = turns > 0 ? `${turns} turn${turns !== 1 ? "s" : ""}` : "";
+      const meta = [costStr, turnsStr].filter(Boolean).join(" · ");
+      if (meta) {
+        process.stdout.write(`\n${DIM}${meta}${RESET}`);
+      }
+
+      process.stdout.write("\n\n");
     } catch (err) {
+      status.stop();
       const msg = err instanceof Error ? err.message : String(err);
-      console.error(`[error] ${msg}\n`);
+      console.error(`\n${DIM}error:${RESET} ${msg}\n`);
     }
 
     rl.prompt();
   });
 
   rl.on("close", async () => {
-    console.log("\nBye!");
+    console.log(`\n${DIM}bye${RESET}`);
     engine.close();
     await closeDb();
     process.exit(0);