portable-agent-layer 0.41.1 → 0.43.0

package/assets/skills/entities/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: entities
+description: Maintain the personal knowledge graph of people and companies. Detect named entities in any content (article, video, paste, conversation), upsert them to ~/.pal/memory/knowledge/, and surface what's already known. Use proactively whenever named entities appear — don't wait to be asked.
+argument-hint: <content, URL, or pasted text>
+---
+
+Detect, persist, and query people and companies referenced in $ARGUMENTS.
+
+The default workflow is **extract → save → show summary**, in that order. Saving is not optional: persistence is the point of the skill. Skip the save step only if the user explicitly said "don't save", "just look", or similar.
+
+## 1. Extract
+
+Read/fetch the content and extract ALL people and companies mentioned.
+
+### People
+
+For each person, extract:
+- **name**: Full name
+- **role**: author | subject | mentioned | quoted | expert | interviewer | interviewee
+- **title**: Job title (null if unknown)
+- **company**: Company affiliation (null if unknown)
+- **social**: twitter (@handle), linkedin (URL), email, website — null if unknown
+- **context**: Why this person is mentioned and their relevance
+- **importance**: primary (central to content) | secondary (supporting) | minor (brief mention)
+
+### Companies
+
+For each company/organization, extract:
+- **name**: Official name
+- **domain**: Primary website domain (e.g. "anthropic.com", null if unknown)
+- **industry**: Classification (AI, security, fintech, healthcare, etc.)
+- **context**: How and why mentioned
+- **mentioned_as**: subject | source | example | competitor | partner | acquisition | product | other
+- **sentiment**: positive | neutral | negative | mixed
+
+### Extraction guidelines
+
+- Accuracy over quantity — use null for unknown fields, never guess
+- Include authors, subjects, quoted individuals, and anyone significantly mentioned
+- For research papers: all authors get "author" role
+- For interviews: distinguish interviewer vs interviewee
+- Universities and research institutions count as companies
+- Extract social handles from bios, signatures, or text body
+- Context fields should explain relevance, not just repeat the mention
+
+### Output shape
+
+```json
+{
+  "people": [...],
+  "companies": [...]
+}
+```
+
+## 2. Save (default)
+
+Immediately persist the extracted JSON. Do not ask first — saving is the default:
+
+```bash
+echo '<the JSON output>' | pal cli knowledge ingest --source "<URL or content origin>"
+```
+
+The CLI writes one markdown file per entity under `~/.pal/memory/knowledge/{People,Companies}/<slug>.md`, preserving every extracted field (role, title, social, context, importance for people; domain, industry, sentiment, mentioned_as for companies) as frontmatter. When a person record includes a `company`, a `part-of` typed edge is auto-created from the person to the company (the company is stub-created if it doesn't exist yet). Each ingestion appends a per-source log section to the entity's body so the same source can be re-ingested safely (idempotent on `--source`).
+
+The CLI prints a JSON summary of `{created, updated, slugs}` counts per domain.
+
+**Opt-out:** if the user explicitly said not to save (e.g. "who's mentioned in this email — don't store anything"), skip step 2 entirely and just show the extracted JSON.
+
+## 3. Query (read-back)
+
+Before scraping a known source, or after saving, surface what's already on file:
+
+```bash
+pal cli knowledge search "<name>"   # substring across title, tags, body
+pal cli knowledge show <slug>       # full entity (frontmatter + body)
+pal cli knowledge graph <slug>      # related entities (BFS, default 2 hops)
+pal cli knowledge ls People         # list a domain
+pal cli knowledge stats             # counts, hubs, isolated nodes
+pal cli knowledge find <tag>        # entities tagged with <tag> (topic: prefix transparent)
+```
+
+Use `search` before extracting to detect duplicates; use `show` to confirm a save landed correctly; use `graph` to surface relationships the user may have forgotten.
+
+## Tag conventions (important)
+
+Tags do two different jobs in the store, and PAL keeps them separated so the graph stays meaningful:
+
+| Tag form | Purpose | Example | Generates graph edges? |
+|---|---|---|---|
+| `topic:<token>` | **Facet** — for filtering / `find` | `topic:ai`, `topic:consulting` | **No** — two entities sharing `topic:ai` do NOT get linked |
+| Unprefixed | **Structural** — for navigation | `acme-labs`, `customer` | Yes — co-occurrence creates tag edges |
+
+**Industry inheritance.** When ingest sees a company `industry`, it splits the string on whitespace and `/` and writes `topic:<token>` tags for each piece. When a person is linked to a company, the person inherits **only** the company's `topic:*` tags — never structural ones. This keeps `find ai` useful (it surfaces every AI-industry company + their employees) without creating phantom graph edges between unrelated entities that merely share an industry word.
+
+Users can query with or without the prefix — `find ai` and `find topic:ai` are equivalent.

package/assets/skills/telos/SKILL.md

@@ -4,7 +4,7 @@ description: Personal context management. Use when discussing goals, beliefs, ch
 argument-hint: [area to view or update]
 ---
 
-Manage the user's TELOS files — the persistent personal context that drives PAL.
+Manage the user's TELOS files — from Greek τέλος (télos), meaning end/purpose/goal. The persistent personal context that orients PAL around who the user is and what they're working toward.
 
 ## TELOS Files
 

package/assets/templates/PAL/ALGORITHM.md

@@ -38,7 +38,7 @@ Thinking-only. No tool calls except context recovery (Grep/Glob/Read).
 **0.5. ISA context** — before reverse engineering, orient against the ISA:
 
 ```bash
-# If cwd matches a registered project — read its open ISCs:
+# If cwd matches a registered project — read its open ISCs (Ideal State Criteria):
 bun ~/.pal/tools/project.ts list-isc <project-name>
 
 # If this is ad-hoc work with no registered project — scaffold a task ISA:

package/assets/templates/PAL/README.md

@@ -82,10 +82,10 @@ Persistent storage across sessions:
 - **state/** — Session registry, counts cache, debug logs
 
 ### Tools (`src/tools/`)
-CLI utilities: `tool:opinion` (manage opinions), `tool:reflect` (relationship reflection), `tool:analyze` (learning analysis), `pal cli usage` (token usage tracking), `tool:export` / `tool:import` (state portability).
+CLI utilities: `tool:opinion` (manage opinions), `tool:reflect` (relationship reflection), `tool:analyze` (learning analysis), `pal cli usage` (token usage tracking), `pal cli export` / `pal cli import` (state portability).
 
 ### TELOS (`telos/`)
-Personal context system — mission, goals, projects, beliefs, challenges, strategies, ideas, learnings, mental models, narratives. Managed via the telos skill.
+From Greek τέλος (télos) — end, purpose, goal. The persistent personal context that orients PAL around who the user is and what they're working toward: mission, goals, beliefs, challenges, strategies, ideas, learnings, mental models, narratives. Managed via the telos skill.
 
 ### Security (`SecurityValidator.ts`)
 Hook-based security: validates Bash commands and file operations against dangerous patterns. Fail-open design — blocks known-dangerous operations without breaking legitimate work.

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -41,7 +41,7 @@ AI agents come and go. Your accumulated knowledge, preferences, and workflows sh
 **What portability means in practice:**
 - No agent-specific assumptions in core logic
 - Agent-specific code isolated in `src/targets/`
-- Skills, memory, and TELOS are agent-agnostic
+- Skills, memory, and TELOS (Greek: τέλος — end/purpose/goal; the user's persistent life context) are agent-agnostic
 - A single `pal cli install --<agent>` registers everything
 
 ### 2. Cross-Platform by Default

package/assets/templates/rules.codex.rules

@@ -0,0 +1,64 @@
+# BEGIN PAL MANAGED CODEX RULES
+# Managed by PAL. Install replaces this block; uninstall removes only this block.
+prefix_rule(
+    pattern = ["bun", "~/.pal/tools/project.ts"],
+    decision = "allow",
+    justification = "PAL project state commands are part of the installed PAL workflow",
+    match = [
+        "bun ~/.pal/tools/project.ts resume portable-agent-layer",
+        "bun ~/.pal/tools/project.ts list-isc portable-agent-layer",
+        "bun ~/.pal/tools/project.ts add-next portable-agent-layer note",
+    ],
+    not_match = [
+        "bun ~/.pal/tools/other.ts",
+    ],
+)
+
+prefix_rule(
+    pattern = ["bun", "~/.pal/tools/algorithm-reflect.ts"],
+    decision = "allow",
+    justification = "PAL Algorithm reflection logging is part of the installed PAL workflow",
+    match = [
+        "bun ~/.pal/tools/algorithm-reflect.ts --task work --criteria 1 --passed 1 --failed 0 --sentiment 8",
+    ],
+    not_match = [
+        "bun ~/.pal/tools/project.ts list",
+    ],
+)
+
+prefix_rule(
+    pattern = [
+        "bun",
+        [
+            "~/.pal/tools/analyze.ts",
+            "~/.pal/tools/handoff-note.ts",
+            "~/.pal/tools/relationship-note.ts",
+            "~/.pal/tools/synthesize.ts",
+            "~/.pal/tools/thread.ts",
+            "~/.pal/tools/wisdom-frame.ts",
+        ],
+    ],
+    decision = "allow",
+    justification = "PAL installed agent tools are safe to run without repeated approval",
+    match = [
+        "bun ~/.pal/tools/thread.ts --list",
+        "bun ~/.pal/tools/wisdom-frame.ts --help",
+    ],
+    not_match = [
+        "bun ~/.pal/tools/project.ts list",
+        "bun ./local-script.ts",
+    ],
+)
+
+prefix_rule(
+    pattern = ["node", "--experimental-strip-types", "~/.pal/skills/consulting-report/tools/generate-pdf.ts"],
+    decision = "allow",
+    justification = "PAL consulting-report PDF generation requires Node for Playwright compatibility",
+    match = [
+        "node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts ./report",
+    ],
+    not_match = [
+        "node ~/.pal/skills/consulting-report/tools/generate-pdf.ts ./report",
+    ],
+)
+# END PAL MANAGED CODEX RULES

package/assets/templates/settings.claude.json

@@ -20,7 +20,8 @@
       "Bash(stat //*)",
       "Bash(readlink //*)",
       "Bash(bun ~/.pal/skills/*/tools/*.ts *)",
-      "Bash(bun ~/.pal/tools/*.ts *)"
+      "Bash(bun ~/.pal/tools/*.ts *)",
+      "Bash(node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts *)"
     ]
   },
   "hooks": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.41.1",
+  "version": "0.43.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "src/",
     "assets/",
+    ".husky/install.mjs",
     "README.md",
     "LICENSE"
   ],
@@ -42,8 +43,7 @@
     "check-write": "biome check --write",
     "knip": "knip-bun",
     "klint": "klint",
-    "jscpd": "jscpd src --noTips --silent",
-    "jscpd:report": "jscpd src --noTips",
+    "jscpd": "jscpd --noTips",
     "lint-staged": "lint-staged",
     "prepare": "bun .husky/install.mjs",
     "install:all": "bun run src/cli/index.ts cli install",
@@ -52,9 +52,7 @@
     "tool:thread": "bun run src/tools/agent/thread.ts",
     "tool:analyze": "bun run src/tools/agent/analyze.ts",
     "tool:wisdom-frame": "bun run src/tools/agent/wisdom-frame.ts",
-    "tool:reflect": "bun run src/tools/relationship-reflect.ts",
-    "tool:export": "bun run src/tools/export.ts",
-    "tool:import": "bun run src/tools/import.ts"
+    "tool:reflect": "bun run src/tools/relationship-reflect.ts"
   },
   "lint-staged": {
     "*.ts": [
@@ -62,9 +60,9 @@
     ]
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.7",
-    "@commitlint/cli": "^20.5.3",
-    "@commitlint/config-conventional": "^20.5.3",
+    "@biomejs/biome": "2.4.15",
+    "@commitlint/cli": "21.0.1",
+    "@commitlint/config-conventional": "21.0.1",
     "@opencode-ai/plugin": "latest",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
@@ -75,15 +73,16 @@
     "husky": "^9.1.7",
     "jscpd": "^4.2.3",
     "knip": "^6.14.1",
-    "lint-staged": "^15.5.2",
+    "lint-staged": "17.0.5",
     "semantic-release": "^25.0.3",
     "typescript": "^5.9.3"
   },
   "dependencies": {
     "@clack/prompts": "^1.4.0",
-    "@konvert7/klint": "^0.2.0",
+    "@konvert7/klint": "0.4.0",
     "adm-zip": "^0.5.17",
-    "marked": "^15.0.12",
+    "marked": "18.0.4",
+    "pdf-lib": "1.17.1",
     "playwright": "^1.60.0"
   }
 }

package/src/cli/index.ts

@@ -186,6 +186,12 @@ async function runCli(command: string | undefined, args: string[]) {
       usage();
       break;
     }
+    case "knowledge": {
+      const { runKnowledge } = await import("./knowledge");
+      const code = await runKnowledge(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
     case "--help":
     case "-h":
     case "help":
@@ -226,6 +232,8 @@ function showHelp() {
     pal cli doctor [--probe-inference]      Check prerequisites and health (--probe fires real inference per route)
     pal cli migrate [--list] [--dry-run]    Run pending data migrations
     pal cli usage                           Summarize token usage and cost
+    pal cli knowledge <sub> [args]          Query & manage the knowledge store
+                                            (search · graph · stats · hubs · find · show · add · ls)
 
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)