drafted 1.18.1 → 1.18.3

package/README.md

@@ -1,32 +1,44 @@
 # Drafted
 
-Shared surface for AI-human collaboration. MCP server and CLI for organizing agent work into projects, skills, and durable knowledge.
+Multi-tenant shared surface for AI-human collaboration. Drafted organizes agent-produced work into **projects** (frames on a zoomable real-time surface), **skills** (reusable operating procedures agents load), and a **wiki** (durable org knowledge) — with MCP tools for agents and a browser UI for humans.
 
-## Install
+- Product vision and positioning: [PRODUCT.md](PRODUCT.md)
+- Architecture, development, and operations: [AGENTS.md](AGENTS.md)
+- Live: [drafted.live](https://drafted.live)
 
-```bash
-npm install -g drafted
-```
+## OKF-native
+
+Drafted is a native producer and consumer of the **Open Knowledge Format (OKF) v0.1** ([GoogleCloudPlatform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)):
 
-## Usage
+- **The org wiki is an OKF v0.1 bundle.** Every page carries conformant YAML frontmatter (required `type`, one-line `description`, `tags`, synthesized `timestamp`; unknown keys preserved). `index.md` at every level is synthesized, `log.md` keeps the date-grouped change history, links resolve with or without `.md`, and broken links are legal. The wiki UI shows a live OKF conformance badge.
+- **Bundle exchange everywhere.** Export/import the wiki (`GET /api/wiki/export.tar.gz`, `POST /api/wiki/import`), the skill library (`skills/<slug>/SKILL.md` layout), and whole projects (`<layer>/<lane>/<file>.md` concepts; markdown links round-trip as connectors) — via HTTP or the MCP `wiki`, `skill`, and `project` tools, with dry-run reports.
 
-### As an MCP server (for Claude Desktop, Claude Code, Codex, Cursor)
+## Install
 
-The MCP server is automatically available after install:
+**Claude Code, Codex, or any MCP client** — installs the MCP server, the Drafted skill, *and* the eight slash commands (into `~/.claude/commands/drafted/` and `~/.codex/prompts/drafted/`):
 
 ```bash
-drafted-mcp
+curl -fsSL https://drafted.live/install.sh | bash        # macOS / Linux
+irm https://drafted.live/install.ps1 | iex               # Windows
 ```
 
-### As a CLI
+> Adding the MCP server on its own (e.g. `claude mcp add`) gives you the tools without the skill or the commands.
+
+**Claude on the web (claude.ai) and Cowork** — install the plugin, not the bare connector. The plugin bundles the Drafted connector *plus* the Drafted skill and the eight slash commands (`/drafted:onboard-drafted`, `/drafted:create-project`, `/drafted:create-skill`, `/drafted:ingest`, `/drafted:extract`, `/drafted:improve-wiki`, `/drafted:improve-skill`, `/drafted:improve-project-harness`); adding the connector URL on its own gives you the tools with none of the guidance.
+
+> 1. Settings → Customize plugins → Add → Add marketplace → `https://github.com/ddfourtwo/drafted-web` → install **Drafted**.
+> 2. Settings → Connectors → find **Drafted** → **Connect**, then approve the sign-in.
+>
+> Both halves matter: the plugin carries the skill and commands, the connector carries the tools. Installing the plugin does not sign you in to the connector.
+
+## Quick start (developing Drafted itself)
 
 ```bash
-drafted login
-drafted ls
-drafted write designs/default/hero.html < design.html
+npm install && npm run dev   # Docker services + schema + server with hot reload
 ```
 
-## Links
+- App: http://localhost:3477
+- Email inbox (magic links): http://localhost:8025
+- MinIO console: http://localhost:9001
 
-- **App**: https://drafted.live
-- **Docs**: https://drafted.live
+Sign in with any email and grab the magic link from Mailpit.

package/agent-instructions/global.md

@@ -0,0 +1,3 @@
+<drafted>
+You have Drafted MCP tools — a shared surface for durable, reviewable work: produce substantive output as frames on the surface (not only in chat), put knowledge in the org wiki, and encode repeatable methods as skills. The full operating manual is the `drafted` skill installed with the plugin — follow it when working with Drafted. Address orgs by path: `fs(ls, path="/")` lists them, and `/o/<org>/<root>/...` (root ∈ wiki, skills, projects) is the canonical path form — the org is part of the path, never a separate switch. Before writing, verify the org/project echoed in the response is the one you intend.
+</drafted>

package/cli/drafted.mjs

@@ -1679,7 +1679,7 @@ function emitSkillResult(format, obj) {
 
 skillCmd
   .command('add')
-  .description('Create a skill in Drafted from stdin JSON {name,description,content,readme,tags?,triggerPatterns?} — a README.md (readme field) is required (Phase 1 gate)')
+  .description('Create a skill in Drafted from stdin JSON {name,description,content,readme?,tags?,triggerPatterns?} — readme is optional; omitting it returns the skill with a warning, not an error')
   .option('--format <fmt>', 'output format: json or text', 'text')
   .action(async (opts) => {
     requireLogin();

package/cli/repo-scan.mjs

@@ -0,0 +1,156 @@
+// Repo `.agents/` scanner (org substrate normalization, Move C).
+//
+// Pure filesystem scan — no network, no DB. The CLI runs this against a repo
+// checkout (cloned to a temp dir for a URL, or a local path directly) and POSTs
+// the catalog to /api/repos. Content stays in git; only metadata + pointers are
+// sent. Mirrors the Agent Skills open format: `.agents/skills/<name>/SKILL.md`
+// (name + description frontmatter) and `.agents/identities/<slug>/identity.yaml`
+// (slug + name). See docs/plans/org-substrate-normalization.md.
+
+import { readFileSync, readdirSync, existsSync, mkdtempSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { execSync } from 'child_process';
+import { parse as parseYaml } from 'yaml';
+
+// ── Frontmatter ────────────────────────────────────────────────────
+
+/** Parse a YAML frontmatter block (`---\n...\n---`) from text. null if absent/invalid. */
+export function parseFrontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  try {
+    const parsed = parseYaml(m[1]);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// ── Scan ────────────────────────────────────────────────────────────
+
+/**
+ * Scan <dir>/.agents/skills/<name>/SKILL.md and <dir>/.agents/identities/<slug>/
+ * identity.yaml. Returns { skills, identities } catalog entries (metadata +
+ * pointers only — no file content). A skill with no frontmatter still indexes
+ * (name falls back to the dir). Identities index {slug, name} from identity.yaml.
+ */
+export function scanRepoAgents(dir) {
+  const skills = [];
+  const identities = [];
+  const agentsDir = join(dir, '.agents');
+
+  const skillsDir = join(agentsDir, 'skills');
+  if (existsSync(skillsDir)) {
+    for (const name of readdirSafe(skillsDir)) {
+      const skillMd = join(skillsDir, name, 'SKILL.md');
+      if (!existsSync(skillMd)) continue;
+      const fm = parseFrontmatter(readFileSync(skillMd, 'utf8')) || {};
+      // README gate (Phase 1): a skill with no README.md still imports (foreign
+      // skills in the open Agent Skills format may legitimately omit one), but
+      // is flagged warn so the gap is visible. Never dropped.
+      const hasReadme = existsSync(join(skillsDir, name, 'README.md'));
+      skills.push({
+        kind: 'skill',
+        name: String(fm.name || name),
+        slug: name,
+        description: fm.description != null ? String(fm.description) : '',
+        sourcePath: `.agents/skills/${name}`,
+        readmePath: hasReadme ? `.agents/skills/${name}/README.md` : null,
+        status: hasReadme ? 'ok' : 'warn',
+        statusReason: hasReadme ? null : 'no README',
+      });
+    }
+  }
+
+  const identDir = join(agentsDir, 'identities');
+  if (existsSync(identDir)) {
+    for (const name of readdirSafe(identDir)) {
+      const idYaml = join(identDir, name, 'identity.yaml');
+      if (!existsSync(idYaml)) continue;
+      let fm = null;
+      try {
+        fm = parseYaml(readFileSync(idYaml, 'utf8')) || {};
+      } catch {
+        fm = {};
+      }
+      identities.push({
+        kind: 'identity',
+        name: String(fm.name || fm.slug || name),
+        slug: String(fm.slug || name),
+        description: null,
+        sourcePath: `.agents/identities/${name}`,
+      });
+    }
+  }
+
+  return { skills, identities };
+}
+
+function readdirSafe(dir) {
+  try {
+    return readdirSync(dir).filter((n) => !n.startsWith('.'));
+  } catch {
+    return [];
+  }
+}
+
+/** Best-effort default branch of a git checkout. 'main' if git is unavailable. */
+export function detectDefaultBranch(dir) {
+  try {
+    const out = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: dir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+    });
+    const branch = out.trim();
+    return branch || 'main';
+  } catch {
+    return 'main';
+  }
+}
+
+/** Remote origin URL of a git checkout, or null. */
+export function detectRemoteUrl(dir) {
+  try {
+    const out = execSync('git config --get remote.origin.url', {
+      cwd: dir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+    });
+    const url = out.trim();
+    return url || null;
+  } catch {
+    return null;
+  }
+}
+
+/** True if the argument looks like a git URL (not a local path). */
+export function isGitUrl(s) {
+  return /^(https?:|git@|ssh:\/\/|git:\/\/)/.test(s);
+}
+
+/** Clone a git URL into a fresh temp dir, returning { dir, cleanup }.
+ *  When `branch` is given, clone that branch only (--branch --single-branch) so a
+ *  missing branch fails loudly instead of silently landing on the default. */
+export function cloneToTemp(url, branch) {
+  const dir = mkdtempSync(join(tmpdir(), 'drafted-repo-'));
+  const branchArgs = branch ? `--branch ${shquote(branch)} --single-branch` : '';
+  execSync(`git clone --depth 1 ${branchArgs} ${shquote(url)} ${shquote(dir)}`, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+  return {
+    dir,
+    cleanup: () => {
+      try { execSync(`rm -rf ${shquote(dir)}`, { stdio: 'ignore' }); } catch { /* best effort */ }
+    },
+  };
+}
+
+// Minimal shell quoting — clone targets are user-supplied URLs. We only pass
+// them to git as a single argv via execSync through a shell string, so quote to
+// avoid metacharacter injection. (The URL is also validated by git itself.)
+function shquote(s) {
+  return `'${String(s).replace(/'/g, "'\\''")}'`;
+}