@velinussage/locus-agent-skill 0.1.0

package/bin/locus-agent-skill.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import { cp, mkdir, readFile, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const bundledSkillDir = path.join(packageRoot, "skill", "locus-agent-tools");
+const skillName = "locus-agent-tools";
+
+function usage() {
+  return `Usage:
+  npx @velinussage/locus-agent-skill add [--target <skills-root>] [--force]
+  npx @velinussage/locus-agent-skill install [--target <skills-root>] [--force]
+  npx @velinussage/locus-agent-skill --print
+
+Options:
+  --target <dir>  Skills root to install into. Defaults to $CODEX_HOME/skills or ~/.codex/skills.
+  --force         Replace an existing locus-agent-tools skill directory.
+  --print         Print the bundled SKILL.md to stdout without writing files.
+  --help          Show this help.
+`;
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const parsed = {
+    command: "add",
+    force: false,
+    print: false,
+    target: undefined,
+  };
+
+  if (args[0] && !args[0].startsWith("-")) {
+    parsed.command = args.shift();
+  }
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") parsed.command = "help";
+    else if (arg === "--force") parsed.force = true;
+    else if (arg === "--print") parsed.print = true;
+    else if (arg === "--target") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("--target requires a directory path.");
+      }
+      parsed.target = value;
+      index += 1;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return parsed;
+}
+
+function defaultSkillsRoot() {
+  if (process.env.CODEX_HOME) return path.join(process.env.CODEX_HOME, "skills");
+  return path.join(os.homedir(), ".codex", "skills");
+}
+
+async function printSkill() {
+  process.stdout.write(await readFile(path.join(bundledSkillDir, "SKILL.md"), "utf8"));
+}
+
+async function installSkill({ target, force }) {
+  const skillsRoot = path.resolve(target || defaultSkillsRoot());
+  const destination = path.join(skillsRoot, skillName);
+
+  if (existsSync(destination)) {
+    if (!force) {
+      console.log(`Locus skill already exists at ${destination}`);
+      console.log("Use --force to replace it.");
+      return;
+    }
+    await rm(destination, { recursive: true, force: true });
+  }
+
+  await mkdir(skillsRoot, { recursive: true });
+  await cp(bundledSkillDir, destination, { recursive: true });
+  console.log(`Installed ${skillName} to ${destination}`);
+  console.log("Next: restart or refresh your agent skill catalog, then ask for Locus MCP/free-tool help.");
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+
+  if (parsed.command === "help") {
+    process.stdout.write(usage());
+    return;
+  }
+
+  if (parsed.print) {
+    await printSkill();
+    return;
+  }
+
+  if (parsed.command !== "add" && parsed.command !== "install") {
+    throw new Error(`Unknown command: ${parsed.command}\n\n${usage()}`);
+  }
+
+  await installSkill(parsed);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@velinussage/locus-agent-skill",
+  "version": "0.1.0",
+  "description": "Install the Locus agent skill for MCP, free tools, and x402-paid property-context workflows.",
+  "type": "module",
+  "bin": {
+    "locus-agent-skill": "bin/locus-agent-skill.js"
+  },
+  "files": [
+    "bin/",
+    "skill/"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "locus",
+    "mcp",
+    "x402",
+    "real-estate",
+    "agent-tools",
+    "public-records"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/locus-agent-tools/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: locus-agent-tools
+description: Use when an agent needs to connect to Locus over MCP, REST, A2A, AgentCash, x402, or free tools for cited property and local-government context. Triggers include Locus MCP, mcp.locus.report, locus free tools, locus_execute, locus_search_tools, x402 Locus reports, real-estate due diligence, coverage preflight, lane availability, source-card checks, parcel/zoning/flood/permit/tax/policy context, and address-first public-record workflows.
+---
+
+# Locus Agent Tools
+
+Use Locus when a place-based workflow needs cited public-record context: taxes, parcels, zoning, flood, environmental records, permits, development activity, transportation projects, local policy, source coverage, or monitoring. Locus returns awareness and verification steps, not a verdict.
+
+Do not use Locus to score, rank, screen, value, predict, or label a person, property, block, or neighborhood as safe or unsafe.
+
+## Quick connect
+
+Install this skill in Codex-style agents with:
+
+```bash
+npx @velinussage/locus-agent-skill add
+```
+
+Remote MCP server:
+
+```json
+{
+  "mcpServers": {
+    "locus": {
+      "type": "http",
+      "url": "https://mcp.locus.report/mcp"
+    }
+  }
+}
+```
+
+Authoritative live discovery:
+
+- MCP catalog: <https://mcp.locus.report/catalog>
+- Free REST catalog: <https://api.locus.report/tools/list>
+- Paid tool index: <https://api.locus.report/.well-known/ai-tool/index.json>
+- A2A Agent Card: <https://api.locus.report/.well-known/agent-card.json>
+- API base: <https://api.locus.report>
+
+The live catalogs are authoritative for tool names, schemas, prices, and endpoints. Do not copy stale tool definitions into prompts.
+
+## MCP tool pattern
+
+The remote MCP server exposes two tools:
+
+1. `locus_search_tools` — search the live catalog across free and paid capabilities.
+2. `locus_execute` — run one selected catalog tool by exact name.
+
+Use this loop:
+
+```text
+place + user goal
+-> search the live catalog
+-> choose the smallest useful tool
+-> run free coverage/source diagnostics before paid analysis
+-> execute one tool
+-> answer only from returned artifacts
+-> show caveats and verify-next steps
+```
+
+Example discovery call:
+
+```json
+{
+  "query": "coverage parcel flood zoning permits Raleigh address",
+  "tier": "all",
+  "limit": 8
+}
+```
+
+Example execution call:
+
+```json
+{
+  "name": "locus_lane_availability",
+  "arguments": {
+    "place": "1 E Edenton St, Raleigh, NC 27601"
+  }
+}
+```
+
+## Free tools first
+
+Prefer free tools for discovery, coverage, source-card status, citation provenance, policy-source checks, parcel diagnostics, environmental preflights, and not-covered responses. Useful starting points:
+
+- `locus_lane_availability` — per-address preflight showing which lanes and paid tools can return data here, with buy signals.
+- `locus_coverage_check` — coverage status for one place.
+- `locus_coverage_map` — registry-level coverage map.
+- `locus_source_card_status` / citation and provenance tools — source health and evidence diagnostics.
+
+Free REST fallback:
+
+```bash
+curl https://api.locus.report/tools/list
+
+curl -X POST https://api.locus.report/tools/call \
+  -H 'content-type: application/json' \
+  -d '{"name":"locus_lane_availability","arguments":{"place":"1 E Edenton St, Raleigh, NC 27601"}}'
+```
+
+Free tools are read-only or bounded participation endpoints. They do not return full paid briefs or compiled place reports.
+
+## Paid tools and x402
+
+Paid tools include place reports, local trend briefs, local policy briefs, before-you-sign bundles, and environmental context products. Use the paid tool index for current names, schemas, prices, and manifests.
+
+When a paid call returns an x402 challenge:
+
+- Show the user the tool name, price, chain/network, asset, recipient, and what will be generated.
+- Do not auto-pay or retry automatically.
+- Retry only after explicit user authorization and wallet/payment context.
+- Preserve settlement proof and any returned report headers or artifact URLs.
+
+Unsupported or discovery-only places should return free diagnostics instead of a silent charge.
+
+## Answer boundaries
+
+Keep answers in this shape:
+
+- What Locus returned from cited artifacts.
+- Why it may matter for the property question.
+- Source names, official URLs or locators, fetched timestamps, and caveats when returned.
+- What to verify next with an agency, landlord, insurer, contractor, seller, property manager, counsel, or another relevant source.
+
+Redirect these asks back to records plus verification questions:
+
+- Safe/unsafe, dangerous, good/bad, score, ranking, prediction, valuation, or investment conclusions.
+- Tenant, employment, lending, insurance, background-check, or eligibility recommendations.
+- Named-person dossiers, mugshots, exact victim/suspect addresses, or scraped personal profiles.
+- Legal advice or claims that a user must or should take a legal action.
+
+## Failure handling
+
+- Unsupported place: return the diagnostic and name coverage or source gaps.
+- Empty result: say no matching records were returned by that source, not that no records exist.
+- Source conflict: show both records and name the agency/source to verify with.
+- Payment challenge: ask for authorization before retrying.
+- User asks for a verdict: decline that part and offer property-context records plus verification questions.

package/skill/locus-agent-tools/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Locus Agent Tools"
+  short_description: "Use Locus MCP, free tools, and paid x402 property-context APIs."
+  default_prompt: "Use Locus to discover current property-context tools, check free coverage, and call the smallest cited tool for the user goal."