@foldspace_npm/harness 0.1.6 → 0.1.8

package/README.md

@@ -93,7 +93,7 @@ npx --yes @foldspace_npm/harness init
 Non-interactive / CI form:
 
 ```bash
-npx --yes @foldspace_npm/harness init my-agent \
+npx --yes @foldspace_npm/harness init foldspace-agent \
   --product-id FR8JUQZAQRZB \
   --agent-key my-agent \
   --domain app.example.com \
@@ -103,24 +103,25 @@ npx --yes @foldspace_npm/harness init my-agent \
 When running directly from a harness checkout during development:
 
 ```bash
-node bin/cli.mjs init ../my-agent \
+node bin/cli.mjs init ../foldspace-agent \
   --product-id FR8JUQZAQRZB \
   --agent-key my-agent \
   --domain app.example.com
 ```
 
-The Agent Key is the value shown in Agent Studio, such as `my-agent`.
-`--agent-api-name` remains a deprecated alias for `--agent-key`. `--name` is
-optional and defaults to the target directory name. The product ID must be the
-bare ID, not the `EU-…-1-1` SDK loader key. The domain may be a hostname or an
-HTTP(S) URL without a port or path.
+The Agent Key is the value shown in Agent Studio, such as `my-agent`. It is
+not the sidecar directory name. `--agent-api-name` remains a deprecated alias
+for `--agent-key`. `--name` is optional and defaults to the target directory
+name (`foldspace-agent` unless you pass a directory). The product ID must be
+the bare ID, not the `EU-…-1-1` SDK loader key. The domain may be a hostname
+or an HTTP(S) URL without a port or path.
 
 For safety, `init` requires a target path that does not exist. It does not
 initialize Git or overwrite files. On a TTY it can offer
 `npm install --ignore-scripts` after scaffolding. After creation:
 
 ```bash
-cd my-agent
+cd foldspace-agent
 npm install --ignore-scripts   # if you skipped the install prompt
 npm run build
 npm run inject
@@ -130,6 +131,25 @@ npm run attach
 The generated npm scripts intentionally remain the normal project interface;
 `foldspace init` is the one-time project creation command.
 
+### Lint handlers before they ship
+
+`foldspace build` runs `foldspace lint` first. Errors skip bundling; warnings
+print and still produce `dist/index.js`.
+
+```bash
+foldspace lint
+foldspace lint --json
+```
+
+v1 flags:
+
+- **error** `no-static-agent-prompt` — `execute` / chatterblock `callback` returning copilot instructions (`directive`, “tell the user”, …)
+- **error** `no-runtask-prompt` — `runTask({ data: { prompt } })` and the same keys; a customer API field named `prompt` is allowed
+- **warning** `no-emoji` — emoji in handler or `agent/views` string literals
+- **warning** `registry-integrity` — duplicate keys, `{ execute }` not registered, registry value missing `execute`
+
+Put action instructions in Agent Studio or MCP. `foldspace lint` cannot see that copy.
+
 ### Choose an attach mode
 
 - **Swap (default):** the page already uses the configured product and agent.

package/bin/build.ts

@@ -2,6 +2,7 @@ import * as esbuild from "esbuild";
 import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
+import { lintProject, printLint } from "../src/lint/index.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const projectDir = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
@@ -10,6 +11,14 @@ const agentActionsEntry = path.join(projectDir, "agent", "actions", "index.ts");
 
 const watchMode = process.argv.includes("--watch");
 
+function gateLint(): void {
+  const result = lintProject(projectDir);
+  printLint(result);
+  if (result.errorCount > 0) {
+    process.exit(1);
+  }
+}
+
 function buildOptions(): esbuild.BuildOptions {
   return {
     entryPoints: [agentActionsEntry],
@@ -27,6 +36,13 @@ function rebuildPlugin(): esbuild.Plugin {
   return {
     name: "rebuild-notify",
     setup(build) {
+      build.onStart(() => {
+        const result = lintProject(projectDir);
+        printLint(result);
+        if (result.errorCount > 0) {
+          throw new Error("foldspace lint failed");
+        }
+      });
       build.onEnd((result) => {
         const time = new Date().toLocaleTimeString();
         if (result.errors.length === 0) {
@@ -47,6 +63,10 @@ async function build() {
     process.exit(1);
   }
 
+  if (!watchMode) {
+    gateLint();
+  }
+
   if (!fs.existsSync(distDir)) {
     fs.mkdirSync(distDir, { recursive: true });
   }

package/bin/lint.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { lintProject, printLint } from "../src/lint/index.mjs";
+
+const projectDir = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
+const json = process.argv.includes("--json");
+const result = lintProject(projectDir);
+printLint(result, { json });
+process.exit(result.errorCount > 0 ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
   ],
   "dependencies": {
     "esbuild": "^0.20.0",
-    "tsx": "^4.7.0"
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
   },
   "engines": {
     "node": ">=20"

package/src/cli-registry.mjs

@@ -74,9 +74,33 @@ export const CLI_COMMANDS = Object.freeze([
     positionals: [],
     options: [flag("--watch", "Rebuild when action source changes")],
     prerequisites: ["agent/actions/index.ts"],
-    effects: ["Writes dist/index.js"],
+    effects: [
+      "Runs foldspace lint first; errors skip bundling",
+      "Writes dist/index.js when lint has no errors",
+    ],
     next: ["Run foldspace inject", "Run foldspace attach"],
   }),
+  Object.freeze({
+    name: "lint",
+    entry: "lint.mjs",
+    group: "develop",
+    summary: "Check action handlers for prompt, registry, and copy issues",
+    usage: "foldspace lint [--json]",
+    risk: "local-write",
+    environment: "node",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR"],
+    capabilities: ["artifact.build"],
+    positionals: [],
+    options: [
+      flag("--json", "Print findings as machine-readable JSON"),
+    ],
+    prerequisites: ["agent/actions/index.ts"],
+    effects: [
+      "Reads agent/actions (and agent/views when present); writes nothing",
+      "Errors fail the process; warnings print and still exit 0",
+    ],
+    next: ["Fix reported findings", "Run foldspace build"],
+  }),
   Object.freeze({
     name: "inject",
     entry: "inject.mjs",

package/src/init.mjs

@@ -16,7 +16,7 @@ const allowedFlags = new Set([
   "domain",
 ]);
 const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
-const defaultDirectory = "my-agent";
+const defaultDirectory = "foldspace-agent";
 
 export const initUsage = commandByName("init").usage;
 
@@ -306,7 +306,9 @@ function createTemplateValues(config, harnessVersion) {
     PACKAGE_DESCRIPTION_JSON: JSON.stringify(`Foldspace browser actions for ${displayName}.`),
     PRODUCT_ID_JSON: JSON.stringify(productId),
     AGENT_API_NAME_JSON: JSON.stringify(agentApiName),
+    APP_DOMAIN: target.domain,
     APP_DOMAIN_JSON: JSON.stringify(target.domain),
+    START_URL: target.startUrl,
     START_URL_JSON: JSON.stringify(target.startUrl),
     HOSTS_JSON: JSON.stringify(hosts),
     HARNESS_VERSION: harnessVersion,

package/src/lint/ast.mjs

@@ -0,0 +1,237 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ts } from "./ts.mjs";
+
+export function listSourceFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...listSourceFiles(full));
+      continue;
+    }
+    if (entry.isFile() && /\.(ts|js)$/.test(entry.name) && !entry.name.endsWith(".d.ts")) {
+      out.push(full);
+    }
+  }
+  return out.sort();
+}
+
+export function shouldSkipActionFile(filePath) {
+  const base = path.basename(filePath);
+  return base.startsWith("_example") || /\.test\./.test(base);
+}
+
+export function parseFile(filePath) {
+  const text = fs.readFileSync(filePath, "utf8");
+  const kind = filePath.endsWith(".ts") ? ts.ScriptKind.TS : ts.ScriptKind.JS;
+  return ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, kind);
+}
+
+export function loc(sourceFile, node) {
+  const start = node.getStart(sourceFile);
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(start);
+  return { line: line + 1, column: character + 1 };
+}
+
+export function propertyName(node) {
+  if (!node?.name) return null;
+  if (ts.isIdentifier(node.name) || ts.isPrivateIdentifier(node.name)) {
+    return node.name.text;
+  }
+  if (ts.isStringLiteral(node.name) || ts.isNumericLiteral(node.name)) {
+    return node.name.text;
+  }
+  return null;
+}
+
+export function normalizeKey(name) {
+  return String(name || "")
+    .replace(/_/g, "")
+    .toLowerCase();
+}
+
+export function isFunctionLike(node) {
+  return (
+    node &&
+    (ts.isFunctionDeclaration(node) ||
+      ts.isFunctionExpression(node) ||
+      ts.isArrowFunction(node) ||
+      ts.isMethodDeclaration(node) ||
+      ts.isConstructorDeclaration(node))
+  );
+}
+
+function initializerOf(node) {
+  if (ts.isPropertyAssignment(node)) return node.initializer;
+  if (ts.isMethodDeclaration(node)) return node;
+  if (ts.isPropertyDeclaration(node)) return node.initializer;
+  return null;
+}
+
+/**
+ * Call `visit(fn, name)` for execute / render / callback function-likes.
+ */
+export function forEachNamedFunction(sourceFile, names, visit) {
+  const wanted = names instanceof Set ? names : new Set(names);
+
+  function walk(node) {
+    if (
+      ts.isPropertyAssignment(node) ||
+      ts.isMethodDeclaration(node) ||
+      ts.isPropertyDeclaration(node)
+    ) {
+      const name = propertyName(node);
+      if (name && wanted.has(name)) {
+        const target = initializerOf(node);
+        if (isFunctionLike(target)) visit(target, name, node);
+      }
+    }
+    ts.forEachChild(node, walk);
+  }
+
+  walk(sourceFile);
+}
+
+export function callbackParamName(fn) {
+  const params = fn.parameters || [];
+  if (params.length >= 4 && ts.isIdentifier(params[3].name)) {
+    return params[3].name.text;
+  }
+  return "callback";
+}
+
+export function collectConstBindings(scopeNode) {
+  const map = new Map();
+
+  function visit(node) {
+    if (node !== scopeNode && isFunctionLike(node)) return;
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+      map.set(node.name.text, node.initializer);
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(scopeNode);
+  return map;
+}
+
+export function collectModuleBindings(sourceFile) {
+  const map = new Map();
+  for (const stmt of sourceFile.statements) {
+    if (!ts.isVariableStatement(stmt)) continue;
+    for (const decl of stmt.declarationList.declarations) {
+      if (ts.isIdentifier(decl.name) && decl.initializer) {
+        map.set(decl.name.text, decl.initializer);
+      }
+    }
+  }
+  return map;
+}
+
+export function resolveNode(node, bindings, depth = 0) {
+  if (!node || depth > 8) return node;
+  if (ts.isIdentifier(node)) {
+    const next = bindings.get(node.text);
+    if (!next) return node;
+    return resolveNode(next, bindings, depth + 1);
+  }
+  if (ts.isAsExpression(node) || ts.isParenthesizedExpression(node) || ts.isSatisfiesExpression(node)) {
+    return resolveNode(node.expression, bindings, depth + 1);
+  }
+  return node;
+}
+
+export function stringText(node) {
+  if (!node) return null;
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text;
+  }
+  if (ts.isTemplateExpression(node)) {
+    return [
+      node.head.text,
+      ...node.templateSpans.map((span) => span.literal.text),
+    ].join("");
+  }
+  return null;
+}
+
+export function forEachStringLiteral(node, visit, { skipNestedFunctions = false, root = node } = {}) {
+  function walk(current) {
+    if (skipNestedFunctions && current !== root && isFunctionLike(current)) return;
+    if (
+      ts.isStringLiteral(current) ||
+      ts.isNoSubstitutionTemplateLiteral(current) ||
+      ts.isTemplateExpression(current)
+    ) {
+      visit(current);
+    }
+    ts.forEachChild(current, walk);
+  }
+  walk(node);
+}
+
+export function forEachReturn(fn, visit) {
+  if (ts.isArrowFunction(fn) && fn.body && !ts.isBlock(fn.body)) {
+    visit(fn.body, fn);
+    return;
+  }
+  function walk(node) {
+    if (node !== fn && isFunctionLike(node)) return;
+    if (ts.isReturnStatement(node) && node.expression) visit(node.expression, node);
+    ts.forEachChild(node, walk);
+  }
+  walk(fn);
+}
+
+export function forEachCallNamed(fn, name, visit) {
+  function walk(node) {
+    if (node !== fn && isFunctionLike(node)) return;
+    if (ts.isCallExpression(node)) {
+      if (ts.isIdentifier(node.expression) && node.expression.text === name) {
+        visit(node);
+      }
+    }
+    ts.forEachChild(node, walk);
+  }
+  walk(fn);
+}
+
+export function objectProperties(obj) {
+  if (!obj || !ts.isObjectLiteralExpression(obj)) return [];
+  return obj.properties.filter(
+    (prop) => ts.isPropertyAssignment(prop) || ts.isShorthandPropertyAssignment(prop),
+  );
+}
+
+export function propertyValue(prop) {
+  if (ts.isShorthandPropertyAssignment(prop)) return prop.name;
+  return prop.initializer;
+}
+
+export function resolveModulePath(fromFile, specifier) {
+  if (!specifier || !specifier.startsWith(".")) return null;
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.js`,
+    path.join(base, "index.ts"),
+    path.join(base, "index.js"),
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile()) || null;
+}
+
+export function finding({ rule, severity, sourceFile, node, message, fix, file }) {
+  const position = loc(sourceFile, node);
+  return {
+    rule,
+    severity,
+    file,
+    line: position.line,
+    column: position.column,
+    message,
+    fix,
+  };
+}

package/src/lint/index.mjs

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+import { listSourceFiles, parseFile, shouldSkipActionFile } from "./ast.mjs";
+import { lintActionFile, lintViewsFile, ruleRegistryIntegrity } from "./rules.mjs";
+
+export const LINT_SCHEMA_VERSION = 1;
+
+export function lintProject(projectDir) {
+  const actionsDir = path.join(projectDir, "agent", "actions");
+  const indexFile = path.join(actionsDir, "index.ts");
+  const indexJs = path.join(actionsDir, "index.js");
+  const entry = fs.existsSync(indexFile) ? indexFile : fs.existsSync(indexJs) ? indexJs : null;
+
+  if (!entry) {
+    return {
+      ok: false,
+      errorCount: 1,
+      warningCount: 0,
+      findings: [
+        {
+          rule: "registry-integrity",
+          severity: "error",
+          file: "agent/actions/index.ts",
+          line: 1,
+          column: 1,
+          message: "Entry point not found: agent/actions/index.ts",
+          fix: "Create agent/actions/index.ts and register handlers there.",
+        },
+      ],
+    };
+  }
+
+  const findings = [];
+  const actionFiles = listSourceFiles(actionsDir);
+
+  for (const filePath of actionFiles) {
+    lintActionFile(filePath, path.relative(projectDir, filePath), findings);
+  }
+
+  const viewsDir = path.join(projectDir, "agent", "views");
+  if (fs.existsSync(viewsDir)) {
+    for (const filePath of listSourceFiles(viewsDir)) {
+      lintViewsFile(filePath, path.relative(projectDir, filePath), findings);
+    }
+  }
+
+  ruleRegistryIntegrity({
+    indexFile: entry,
+    indexSource: parseFile(entry),
+    actionFiles,
+    projectDir,
+    findings,
+  });
+
+  const errorCount = findings.filter((item) => item.severity === "error").length;
+  const warningCount = findings.filter((item) => item.severity === "warning").length;
+  return {
+    ok: errorCount === 0,
+    errorCount,
+    warningCount,
+    findings,
+  };
+}
+
+function formatFinding(item) {
+  return `${item.file}:${item.line}:${item.column}  ${item.severity}  ${item.rule}  ${item.message}\n  Fix: ${item.fix}`;
+}
+
+export function renderLintText(result) {
+  if (!result.findings.length) {
+    return "foldspace lint: no issues";
+  }
+  const body = result.findings.map(formatFinding).join("\n");
+  const summary = `${result.errorCount} error${result.errorCount === 1 ? "" : "s"}, ${result.warningCount} warning${result.warningCount === 1 ? "" : "s"}`;
+  return `${body}\n\n${summary}`;
+}
+
+export function renderLintJson(result) {
+  return {
+    kind: "foldspace.lint",
+    schemaVersion: LINT_SCHEMA_VERSION,
+    ok: result.ok,
+    errorCount: result.errorCount,
+    warningCount: result.warningCount,
+    findings: result.findings,
+  };
+}
+
+export function printLint(result, { json = false, stdout = console.log, stderr = console.error } = {}) {
+  if (json) {
+    stdout(JSON.stringify(renderLintJson(result), null, 2));
+    return;
+  }
+  const text = renderLintText(result);
+  if (result.errorCount > 0) stderr(text);
+  else stdout(text);
+}
+
+export function shouldSkipFile(filePath) {
+  return shouldSkipActionFile(filePath);
+}

package/src/lint/rules.mjs

@@ -0,0 +1,464 @@
+import path from "node:path";
+import {
+  callbackParamName,
+  collectConstBindings,
+  collectModuleBindings,
+  finding,
+  forEachCallNamed,
+  forEachNamedFunction,
+  forEachReturn,
+  forEachStringLiteral,
+  isFunctionLike,
+  normalizeKey,
+  objectProperties,
+  parseFile,
+  propertyName,
+  propertyValue,
+  resolveModulePath,
+  resolveNode,
+  shouldSkipActionFile,
+  stringText,
+} from "./ast.mjs";
+import { ts } from "./ts.mjs";
+
+/*
+  Backlog, not this slice:
+  - no-hardcoded-secrets
+  - no-unsafe-return (stack / cookies / Authorization / ApiResult.detail)
+  - snake_case action keys
+  - credentials: "include" on every fetch
+  - _gen2 vs _v2 taskKey
+*/
+
+const BANNED_PROMPT_KEYS = new Set([
+  "directive",
+  "instructions",
+  "guidance",
+  "systemprompt",
+  "agentinstructions",
+  "nextprompt",
+]);
+
+const RUNTASK_PROMPT_KEYS = new Set(["prompt", "instructions", "systemprompt"]);
+
+const IMPERATIVE_PATTERNS = [
+  /\btell the user\b/i,
+  /\bask the user\b/i,
+  /\bask if they(?:'d| would)\b/i,
+  /\bdo not (?:repeat|call|summarize)\b/i,
+  /\bdon't (?:repeat|call|summarize)\b/i,
+  /\bsummarize the following\b/i,
+  /\brun the [\w-]+ action\b/i,
+  /\bwalk the user through\b/i,
+  /\bproceed to the next step\b/i,
+  /\blet the user know\b/i,
+];
+
+const EMOJI_PATTERN = /\p{Extended_Pictographic}/u;
+
+const PROMPT_FIX =
+  "Put the wording in the action or agent instructions via MCP or Agent Studio; return data only.";
+
+function mergeBindings(fn, sourceFile) {
+  return new Map([
+    ...collectModuleBindings(sourceFile),
+    ...collectConstBindings(fn),
+  ]);
+}
+
+function inspectReturnedObject(obj, bindings, sourceFile, relative, findings, origin) {
+  if (!obj || !ts.isObjectLiteralExpression(obj)) return;
+
+  for (const prop of objectProperties(obj)) {
+    const name = propertyName(prop);
+    const normalized = normalizeKey(name);
+    const valueNode = resolveNode(propertyValue(prop), bindings);
+    const at = prop.name || prop;
+
+    if (BANNED_PROMPT_KEYS.has(normalized)) {
+      findings.push(
+        finding({
+          rule: "no-static-agent-prompt",
+          severity: "error",
+          sourceFile,
+          node: at,
+          file: relative,
+          message: `Do not return '${name}' — that is a second instruction channel besides Agent Studio.`,
+          fix: PROMPT_FIX,
+        }),
+      );
+    }
+
+    const text = stringText(valueNode);
+    if (text && IMPERATIVE_PATTERNS.some((pattern) => pattern.test(text))) {
+      findings.push(
+        finding({
+          rule: "no-static-agent-prompt",
+          severity: "error",
+          sourceFile,
+          node: at,
+          file: relative,
+          message: `${origin} sends the copilot operating instructions ('${text.slice(0, 80)}').`,
+          fix: PROMPT_FIX,
+        }),
+      );
+    }
+
+    if (valueNode && ts.isObjectLiteralExpression(valueNode)) {
+      inspectReturnedObject(valueNode, bindings, sourceFile, relative, findings, origin);
+    }
+  }
+}
+
+export function ruleNoStaticAgentPrompt(sourceFile, relative, findings) {
+  forEachNamedFunction(sourceFile, ["execute", "render", "callback"], (fn, name) => {
+    const bindings = mergeBindings(fn, sourceFile);
+
+    if (name === "execute" || name === "callback") {
+      forEachReturn(fn, (expression) => {
+        inspectReturnedObject(
+          resolveNode(expression, bindings),
+          bindings,
+          sourceFile,
+          relative,
+          findings,
+          name,
+        );
+      });
+    }
+
+    if (name === "render") {
+      const cbName = callbackParamName(fn);
+      forEachCallNamed(fn, cbName, (call) => {
+        const arg = call.arguments[0];
+        if (!arg) return;
+        inspectReturnedObject(
+          resolveNode(arg, bindings),
+          bindings,
+          sourceFile,
+          relative,
+          findings,
+          "callback",
+        );
+      });
+    }
+  });
+}
+
+function inspectRunTaskData(dataNode, bindings, sourceFile, relative, findings, call) {
+  const resolved = resolveNode(dataNode, bindings);
+  if (!resolved || !ts.isObjectLiteralExpression(resolved)) return;
+
+  for (const prop of objectProperties(resolved)) {
+    const name = propertyName(prop);
+    if (!RUNTASK_PROMPT_KEYS.has(normalizeKey(name))) continue;
+    const value = resolveNode(propertyValue(prop), bindings);
+    if (stringText(value) === null) continue;
+    findings.push(
+      finding({
+        rule: "no-runtask-prompt",
+        severity: "error",
+        sourceFile,
+        node: prop.name || call,
+        file: relative,
+        message: `runTask data.${name} is a prompt. Task-agent instructions belong in Agent Studio.`,
+        fix: "Keep task-agent instructions in Agent Studio; pass only extracted facts in data.",
+      }),
+    );
+  }
+}
+
+export function ruleNoRunTaskPrompt(sourceFile, relative, findings) {
+  const moduleBindings = collectModuleBindings(sourceFile);
+
+  function walk(node, fnBindings) {
+    if (isFunctionLike(node) && node !== sourceFile) {
+      const nested = mergeBindings(node, sourceFile);
+      ts.forEachChild(node, (child) => walk(child, nested));
+      return;
+    }
+
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+      if (node.expression.name.text === "runTask") {
+        const arg = node.arguments[0];
+        const bindings = fnBindings || moduleBindings;
+        const config = resolveNode(arg, bindings);
+        if (config && ts.isObjectLiteralExpression(config)) {
+          for (const prop of objectProperties(config)) {
+            if (propertyName(prop) !== "data") continue;
+            inspectRunTaskData(propertyValue(prop), bindings, sourceFile, relative, findings, node);
+          }
+        }
+      }
+    }
+
+    ts.forEachChild(node, (child) => walk(child, fnBindings));
+  }
+
+  walk(sourceFile, moduleBindings);
+}
+
+function reportEmoji(node, sourceFile, relative, findings) {
+  const text = stringText(node);
+  if (!text || !EMOJI_PATTERN.test(text)) return;
+  findings.push(
+    finding({
+      rule: "no-emoji",
+      severity: "warning",
+      sourceFile,
+      node,
+      file: relative,
+      message: "Emoji in handler or widget copy reads as off-brand in a product UI that has none.",
+      fix: "Strip the glyph from handler/render copy. Put “no emoji” in the agent's Behavior instructions; the MCP cannot write that field, so each new action's Studio instructions must carry the line too.",
+    }),
+  );
+}
+
+export function ruleNoEmoji(sourceFile, relative, findings, { wholeFile = false } = {}) {
+  if (wholeFile) {
+    forEachStringLiteral(sourceFile, (node) => {
+      if (ts.isImportDeclaration(node.parent) || ts.isExportDeclaration(node.parent)) return;
+      reportEmoji(node, sourceFile, relative, findings);
+    });
+    return;
+  }
+
+  forEachNamedFunction(sourceFile, ["execute", "render", "callback"], (fn) => {
+    const bindings = mergeBindings(fn, sourceFile);
+    forEachStringLiteral(
+      fn,
+      (node) => reportEmoji(node, sourceFile, relative, findings),
+      { skipNestedFunctions: true, root: fn },
+    );
+
+    function walk(current) {
+      if (current !== fn && isFunctionLike(current)) return;
+      if (ts.isIdentifier(current)) {
+        const resolved = resolveNode(current, bindings);
+        if (
+          resolved &&
+          resolved !== current &&
+          (resolved.getStart(sourceFile) < fn.getStart(sourceFile) ||
+            resolved.getEnd() > fn.getEnd())
+        ) {
+          reportEmoji(resolved, sourceFile, relative, findings);
+        }
+      }
+      ts.forEachChild(current, walk);
+    }
+    walk(fn);
+  });
+}
+
+function exportedBindings(sourceFile) {
+  const exports = [];
+
+  function objectHasExecute(node) {
+    if (!node || !ts.isObjectLiteralExpression(node)) return false;
+    return objectProperties(node).some((prop) => propertyName(prop) === "execute");
+  }
+
+  for (const stmt of sourceFile.statements) {
+    if (ts.isVariableStatement(stmt) && stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+      for (const decl of stmt.declarationList.declarations) {
+        if (!ts.isIdentifier(decl.name)) continue;
+        const init = decl.initializer;
+        exports.push({
+          name: decl.name.text,
+          node: decl.name,
+          hasExecute: objectHasExecute(init),
+          isFunction: isFunctionLike(init),
+        });
+      }
+    }
+    if (ts.isFunctionDeclaration(stmt) && stmt.name && stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+      exports.push({
+        name: stmt.name.text,
+        node: stmt.name,
+        hasExecute: false,
+        isFunction: true,
+      });
+    }
+  }
+  return exports;
+}
+
+function collectImports(sourceFile, filePath) {
+  const map = new Map();
+  for (const stmt of sourceFile.statements) {
+    if (!ts.isImportDeclaration(stmt) || !stmt.importClause) continue;
+    if (!ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    const resolved = resolveModulePath(filePath, stmt.moduleSpecifier.text);
+    if (!resolved) continue;
+    const clause = stmt.importClause;
+    if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+      for (const spec of clause.namedBindings.elements) {
+        const imported = (spec.propertyName || spec.name).text;
+        map.set(spec.name.text, { file: resolved, imported });
+      }
+    }
+    if (clause.name) {
+      map.set(clause.name.text, { file: resolved, imported: "default" });
+    }
+  }
+  return map;
+}
+
+function findRegistryObject(sourceFile) {
+  let found = null;
+
+  function consider(node) {
+    if (node && ts.isObjectLiteralExpression(node)) found = found || node;
+  }
+
+  function walk(node) {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === "actions") {
+      consider(node.initializer);
+    }
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+      const left = node.left.getText(sourceFile);
+      if (left.includes("__FOLDSPACE_REMOTE_ACTIONS__") || left.endsWith(".actions")) {
+        if (ts.isIdentifier(node.right) && node.right.text === "actions") {
+          // resolved via variable declaration
+        } else {
+          consider(node.right);
+        }
+      }
+    }
+    ts.forEachChild(node, walk);
+  }
+
+  walk(sourceFile);
+  return found;
+}
+
+export function ruleRegistryIntegrity({ indexFile, indexSource, actionFiles, projectDir, findings }) {
+  const relativeIndex = path.relative(projectDir, indexFile);
+  const registry = findRegistryObject(indexSource);
+  const imports = collectImports(indexSource, indexFile);
+  const seenKeys = new Map();
+  const registeredNames = new Set();
+
+  if (registry) {
+    for (const prop of objectProperties(registry)) {
+      const key = propertyName(prop);
+      if (!key) continue;
+      if (seenKeys.has(key)) {
+        findings.push(
+          finding({
+            rule: "registry-integrity",
+            severity: "warning",
+            sourceFile: indexSource,
+            node: prop.name || prop,
+            file: relativeIndex,
+            message: `Duplicate registry key '${key}'. The second entry silently wins.`,
+            fix: "Give each registered action a unique key that matches Agent Studio.",
+          }),
+        );
+      }
+      seenKeys.set(key, prop);
+
+      const value = propertyValue(prop);
+      if (isFunctionLike(value)) {
+        findings.push(
+          finding({
+            rule: "registry-integrity",
+            severity: "warning",
+            sourceFile: indexSource,
+            node: prop.name || prop,
+            file: relativeIndex,
+            message: `Registry entry '${key}' is a function. The SDK expects { execute }.`,
+            fix: "Register an object with an execute function.",
+          }),
+        );
+        continue;
+      }
+      if (ts.isObjectLiteralExpression(value)) {
+        const hasExecute = objectProperties(value).some((entry) => propertyName(entry) === "execute");
+        if (!hasExecute) {
+          findings.push(
+            finding({
+              rule: "registry-integrity",
+              severity: "warning",
+              sourceFile: indexSource,
+              node: prop.name || prop,
+              file: relativeIndex,
+              message: `Registry entry '${key}' is an object without execute.`,
+              fix: "Register an object with an execute function.",
+            }),
+          );
+        }
+        continue;
+      }
+      if (ts.isIdentifier(value)) {
+        registeredNames.add(value.text);
+        const imported = imports.get(value.text);
+        if (imported) {
+          const exported = exportedBindings(parseFile(imported.file)).find(
+            (item) => item.name === imported.imported || item.name === value.text,
+          );
+          if (exported?.isFunction && !exported.hasExecute) {
+            findings.push(
+              finding({
+                rule: "registry-integrity",
+                severity: "warning",
+                sourceFile: indexSource,
+                node: prop.name || prop,
+                file: relativeIndex,
+                message: `Registry entry '${key}' points at a bare function, not { execute }.`,
+                fix: "Export and register an object with an execute function.",
+              }),
+            );
+          } else if (exported && !exported.hasExecute && !exported.isFunction) {
+            findings.push(
+              finding({
+                rule: "registry-integrity",
+                severity: "warning",
+                sourceFile: indexSource,
+                node: prop.name || prop,
+                file: relativeIndex,
+                message: `Registry entry '${key}' points at an object without execute.`,
+                fix: "Export and register an object with an execute function.",
+              }),
+            );
+          }
+        }
+      }
+    }
+  }
+
+  for (const filePath of actionFiles) {
+    if (filePath === indexFile) continue;
+    if (shouldSkipActionFile(filePath)) continue;
+    const sourceFile = parseFile(filePath);
+    const relative = path.relative(projectDir, filePath);
+    for (const exported of exportedBindings(sourceFile)) {
+      if (!exported.hasExecute) continue;
+      if (registeredNames.has(exported.name) || seenKeys.has(exported.name)) continue;
+      findings.push(
+        finding({
+          rule: "registry-integrity",
+          severity: "warning",
+          sourceFile,
+          node: exported.node,
+          file: relative,
+          message: `'${exported.name}' exports { execute } but is not registered in agent/actions/index.ts.`,
+          fix: "Import it and add it to the actions object. An unregistered handler never fires.",
+        }),
+      );
+    }
+  }
+}
+
+export function lintActionFile(filePath, relative, findings) {
+  if (shouldSkipActionFile(filePath)) return;
+  const sourceFile = parseFile(filePath);
+  ruleNoStaticAgentPrompt(sourceFile, relative, findings);
+  ruleNoRunTaskPrompt(sourceFile, relative, findings);
+  ruleNoEmoji(sourceFile, relative, findings);
+}
+
+export function lintViewsFile(filePath, relative, findings) {
+  const sourceFile = parseFile(filePath);
+  ruleNoEmoji(sourceFile, relative, findings, { wholeFile: true });
+}

package/src/lint/ts.mjs

@@ -0,0 +1,6 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+/** TypeScript compiler API, resolved from this package — not the tenant. */
+export const ts = require("typescript");

package/templates/agent-starter/CLAUDE.md

@@ -29,11 +29,13 @@ from actions that read or mutate a selected resource.
 3. Capture at least one real HTTP 200 for the data the action needs. Use
    chrome-devtools MCP against the inject Chrome, or a page-context `fetch`,
    **before** `attach` owns the debug port. If there is no 200,
-   pivot; do not create Foldspace resources.
+   pivot; do not create Foldspace resources. Write what you establish into
+   `docs/app-profile.md` with **how you know it**. Do not promote an assumption
+   by quoting that file.
 4. Create action metadata as a draft. `generate_action_handler` works from the
    draft schema; do not publish yet.
 5. Implement the handler using the observed request and response shapes.
-6. Register the handler in `agent/actions/index.ts` and build.
+6. Register the handler in `agent/actions/index.ts` and build (`foldspace build` lints first).
 7. Run `npx foldspace attach --daemon` (add `--bootstrap` or `--replace` when
    the page requires it). An empty local registry is valid if you only want to
    see how the agent works.
@@ -52,7 +54,36 @@ Actions execute in the user's signed-in browser session.
 - Verify that the user is signed in before observing a workflow.
 - Do not substitute a public developer API when the browser session is missing;
   ask the user to sign in.
-- Validate parameters and return sanitized errors.
+- Validate parameters and return sanitized errors. Return **data only** — never
+  `directive`, `instructions`, or a paragraph telling the copilot what to say.
+  Action and agent instructions live in Agent Studio / MCP.
+- Actions that return data the user will inspect should include a `render`
+  function for in-chat UI (a chatterblock). If it makes more sense to output the data
+  in a UI component instead of text then consider using render to show a component.
+   - `render` receives **`execute`'s return value**, not the action's input params.
+     Returning anything that lacks the ids the card needs is why widgets pass in
+     isolation and fail in the real chat.
+   - `runAction` refuses render actions (`cannot be executed silently`). Driving
+     `render()` yourself never runs `execute()`, so it does not test that contract.
+   - Check https://docs.foldspace.ai/guides/in-chat-ui/ for more information
+
+## Task agents
+
+Use a Task Agent when the handler needs a one-time LLM subtask that
+deterministic code cannot do well: extraction, summarization,
+classification, normalization, enrichment, or generation.
+
+Do not use a Task Agent for API calls, CRUD, routing, or parsing a
+known response shape. Those stay in `execute`.
+
+Task agents are created in Agent Studio, not in this repo. Ask before
+creating or publishing one. Call a published task agent from the
+handler with `runTask({ taskKey, data })` (if not published the runTask won't work).
+`data` carries extracted facts only — not `prompt` / `instructions` strings.
+Prefer JSON output when the handler must consume the result.
+
+See https://docs.foldspace.ai/user-guides/task-agents/ and
+https://docs.foldspace.ai/reference/task-agent-api/
 
 ## Local harness loop
 
@@ -93,41 +124,58 @@ execute/render lines; do not invoke the handler directly. Those lines record
 names, statuses, durations, and parameter keys only — not results or error
 bodies.
 
+## Product defaults
+
+These are not Joist-specific. Lint can catch some of them in handler code;
+Agent Studio copy is on you.
+
+- **No emoji** in copilot replies, cards, or handler strings. Put that in the
+  agent's Behavior instructions (MCP cannot write that field, so each new
+  action's Studio `instructions` must carry the line too).
+- **Never send the user out of the host app.** No "open in <product>"
+  button and no pasted URLs — navigate with a navigation route, same tab.
+- **Check row counts before choosing the experience.** On an empty account the
+  useful first action is one that creates data.
+
 ## Verification gates
 
 Do not report success without all six:
 
-1. TypeScript compiles with `npx tsc --noEmit -p tsconfig.json`.
-2. The expected handler appears in `dist/index.js`.
-3. The browser reports `inspect_registration:registration_ok`. For a named
+1. TypeScript compiles with `npm run typecheck` (`tsc --noEmit -p tsconfig.json`).
+   Do not run `npx tsc` — that can install the wrong package.
+2. `foldspace lint` reports no errors (`foldspace build` runs this first).
+3. The expected handler appears in `dist/index.js`.
+4. The browser reports `inspect_registration:registration_ok`. For a named
    action, the captured registry includes that handler.
-4. The action behaves correctly against the real target workflow. Confirm
+5. The action behaves correctly against the real target workflow. Confirm
    `[actions] local-handler:execute` in the attach log after the user exercises
-   the visible agent.
-5. Existing neighbouring action fixtures still pass when fixtures exist.
+   the visible agent. For a widget, that log must include `local-handler:render`
+   from a real chat turn — not a hand-built `render()` call.
 6. Browser evidence came from the live target, not from hand-authored examples.
+   Neighbour fixtures still pass when they exist.
 
 ## Layout
 
-- `agent/actions/` — one handler per action, registered in `index.ts`
+- `agent/actions/` — one handler per action (`execute`, optional `render`),
+  registered in `index.ts`
 - `agent/api/` — one HTTP helper per endpoint
 - `agent/constants.ts` — agent, product, and domain identifiers
 - `agent/utils.ts` — Foldspace agent lookup
 - `foldspace.dev.json` — local harness target configuration
-- `docs/` — optional coding-agent learnings; create on demand
+- `docs/app-profile.md` — what is known about this app, and how it was established
 
 Do not introduce another bundler or bundle format.
 
 ## Agent learnings
 
-Use `docs/` to record durable, repository-specific lessons so later sessions do
-not repeat the same mistakes.
+`docs/app-profile.md` is the durable record of this app. Fill it as you probe,
+not afterwards. Other notes in `docs/` are fine for session-specific lessons.
 
-- Before similar work, read any relevant notes already in `docs/`.
-- After non-obvious discoveries, add a short note covering verified gotchas,
-  failed approaches, design rationale, or useful verification commands.
-- Keep notes concise and evidence-based. Create `docs/` when the first note is
-  useful; do not leave an empty directory.
+- Before similar work, read `docs/app-profile.md` and any other notes in `docs/`.
+- After non-obvious discoveries, add them to the profile (or a short extra
+  note) covering verified gotchas, failed approaches, and how they were
+  established.
+- Keep notes concise and evidence-based.
 - Do not store secrets, cookies, HAR files, browser storage, or other transient
   session data in `docs/`.
 

package/templates/agent-starter/agent/actions/_example.ts

@@ -15,4 +15,19 @@ export const example_action = {
       return { ok: false, error: detail };
     }
   },
+
+  // Optional chatterblock: uncomment to render in-chat UI instead of
+  // returning text-only data. See https://docs.foldspace.ai/guides/in-chat-ui/ for more information. Set
+  // awaitUserInput: true for forms and confirmations.
+  //
+  // render: (data, host, header, callback, cancel) => {
+  //   host.replaceChildren();
+  //   if (data?.ok === false) {
+  //     host.textContent = data.error;
+  //     return;
+  //   }
+  //   const card = document.createElement("div");
+  //   card.textContent = data.echo;
+  //   host.append(card);
+  // },
 };

package/templates/agent-starter/docs/app-profile.md

@@ -0,0 +1,109 @@
+# {{DISPLAY_NAME}} — app profile
+
+Durable facts about `{{APP_DOMAIN}}` and its API, established by observing the
+running app on **<date>** from a logged-in session.
+
+**Everything here should be observed.** Each entry says how. Where something is
+only believed, say so in the same breath — do not promote an assumption by
+quoting this file. Re-run the probe before trusting an entry that matters.
+
+Do not store secrets, cookies, HAR files, tokens, or session data here. Record
+*where* the token lives and *what a redacted value looks like*, never the value.
+
+How to re-run any probe below:
+
+```bash
+npm run inject
+# Sign in. Capture from chrome-devtools MCP, or a page-context fetch,
+# before foldspace attach owns the debug port.
+```
+
+Start URL: `{{START_URL}}`
+
+---
+
+## Auth
+
+- Where the token lives (cookie name, `localStorage` key, custom header), and
+  how you know — wrapping XHR/`fetch` on the live page beats guessing.
+- Its lifetime, measured. (One app's expired in ~52 minutes and killed three
+  probing sessions.)
+- What an expired or refused response looks like, verbatim. A CORS-less refusal
+  often surfaces as `TypeError: Failed to fetch` with no status — that is not
+  "host down".
+- Anything inherited but never exercised — mark it **assumed**.
+
+## API base
+
+- The exact base, including any explicit port. Note if omitting `:443` fails
+  CORS, and whether the API is a **different host** from the app (a relative
+  path then returns the HTML shell).
+
+## Account contents
+
+Row counts from the signed-in account **before** choosing the experience. On an
+empty account the only useful first action is one that creates data.
+
+| Resource | Count | How established |
+|---|---|---|
+| | | |
+
+## Endpoints called and observed
+
+For each: the path, the **envelope**, the row keys you actually read, and how
+you established them.
+
+> Watch for endpoints on the same host that wrap the same resource
+> differently (`{data}` vs `{contacts}` vs `{items}`). Reaching for the wrong
+> key yields `undefined`, not an empty array — it throws downstream rather
+> than returning nothing.
+
+| Path | Method | Envelope | Verified |
+|---|---|---|---|
+| | | | |
+
+## Verified behaviour
+
+A table of probe → result. Paging, search, sort, filters. One row per call you
+actually made.
+
+**What the search matches.** Test prefix, mid-word, case, digits, across spaces,
+and one transposed letter. Most app search is a plain case-insensitive substring
+with no tolerance.
+
+> A probe using values no record has proves nothing. If a filter returns zero,
+> confirm a matching record exists before concluding anything.
+
+| Probe | Result |
+|---|---|
+| | |
+
+## Vocabulary observed
+
+Real enum values seen on live records — not the generic ones you would expect.
+Mark which you verified and which came from reading the app bundle.
+
+## Identifiers
+
+| Identifier | Produced by | Example |
+|---|---|---|
+| | | |
+
+## Brand (sampled, not guessed)
+
+Colour, typeface, greys, base size and radii from the running app's computed
+styles — not from a screenshot. Re-sample per tenant; do not carry values
+across.
+
+## Endpoints seen in the bundle but NOT called
+
+Listed so the next person knows they exist **and knows they are unverified**.
+
+## Failures observed
+
+| Call | Result | What it means |
+|---|---|---|
+| | | |
+
+Record inconclusive results as inconclusive. A 401 on a dead session says
+nothing about whether the endpoint works.

package/templates/agent-starter/package.json

@@ -7,6 +7,8 @@
   "scripts": {
     "dev": "foldspace build --watch",
     "build": "foldspace build",
+    "lint": "foldspace lint",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
     "inject": "foldspace inject",
     "attach": "foldspace attach",
     "attach:daemon": "foldspace attach --daemon"