@xopcai/xopc 0.0.172 → 0.0.174

package/dist/src/work-discovery/thread-service.d.ts

@@ -1,4 +1,9 @@
 import type { WorkContextSnapshot, WorkDiscoveryResult, WorkUnderstandingEvidenceItem, WorkUnderstandingThread } from './types.js';
+/**
+ * Discovery produces suggestions only. The user turns a suggestion into a Focus explicitly.
+ * The legacy thread-shaped return value remains local to the discovery result renderer; it is
+ * not a second persisted domain model.
+ */
 export declare function persistWorkThreadsFromDiscovery(input: {
     projectId: string;
     result: WorkDiscoveryResult;

package/dist/src/work-discovery/thread-service.js

@@ -1,104 +1,52 @@
-import { listWorkUnderstandingThreads, upsertWorkUnderstandingThread } from "./thread-repository.js";
+import { upsertFocusCandidate } from "../focuses/candidate-repository.js";
 //#region src/work-discovery/thread-service.ts
 function confidenceValue(value) {
 	return value === "high" ? .9 : value === "medium" ? .72 : .55;
 }
-function recencyPoints(observedAt, nowMs) {
-	if (!observedAt) return 8;
-	const days = Math.max(0, (nowMs - observedAt) / 864e5);
-	if (days <= 2) return 40;
-	if (days <= 7) return 32;
-	if (days <= 14) return 24;
-	if (days <= 30) return 14;
-	return 5;
-}
-function focusScore(input) {
-	const latest = input.evidence.reduce((value, item) => item.observedAt != null && (value == null || item.observedAt > value) ? item.observedAt : value, void 0);
-	const commitDays = new Set((input.snapshot.git?.recentCommits ?? []).flatMap((commit) => commit.committedAt ? [new Date(commit.committedAt).toISOString().slice(0, 10)] : []));
-	const sourceTypes = new Set(input.evidence.map((item) => item.sourceType));
-	const continuity = Math.min(20, commitDays.size * 5);
-	const corroboration = Math.min(15, input.evidence.length * 3 + Math.max(0, sourceTypes.size - 1) * 5);
-	const unfinished = input.candidate.status === "active" ? 15 : input.candidate.status === "blocked" ? 12 : 3;
-	const confidence = Math.round(confidenceValue(input.candidate.confidence) * 10);
-	const horizonAdjustment = input.candidate.horizon === "current" ? 0 : input.candidate.horizon === "ongoing" ? -4 : -8;
-	return Math.max(0, Math.min(100, Math.round(recencyPoints(latest, input.nowMs) + continuity + corroboration + unfinished + confidence + horizonAdjustment)));
-}
-function fallbackCandidate(result, evidence) {
-	return {
-		topicKey: "current-project-work",
-		title: result.projectSummary.slice(0, 200),
-		summary: result.currentState.slice(0, 2e3),
-		status: result.lowConfidence ? "uncertain" : "active",
-		horizon: "current",
-		confidence: result.lowConfidence ? "low" : "medium",
-		evidenceRefs: evidence.slice(0, 6).map((item) => item.sourceRef)
-	};
-}
-function titleTokens(value) {
-	return new Set(value.toLocaleLowerCase().match(/[\p{L}\p{N}]{2,}/gu)?.filter((token) => ![
-		"the",
-		"and",
-		"for",
-		"with",
-		"from",
-		"this",
-		"that"
-	].includes(token)).slice(0, 30) ?? []);
-}
-function titleSimilarity(left, right) {
-	const leftTokens = titleTokens(left);
-	const rightTokens = titleTokens(right);
-	if (!leftTokens.size || !rightTokens.size) return 0;
-	return [...leftTokens].filter((token) => rightTokens.has(token)).length / Math.max(leftTokens.size, rightTokens.size);
-}
-function canonicalKeyForCandidate(input) {
-	const proposed = `${input.projectId}:${input.candidate.horizon}:${input.candidate.topicKey}`.slice(0, 300);
-	const existing = listWorkUnderstandingThreads({
-		projectId: input.projectId,
-		includeRejected: true,
-		limit: 100
-	});
-	const exact = existing.find((thread) => thread.canonicalKey === proposed);
-	if (exact) return exact.canonicalKey;
-	return existing.filter((thread) => thread.horizon === input.candidate.horizon && thread.userStatus !== "rejected").map((thread) => ({
-		thread,
-		similarity: titleSimilarity(thread.title, input.candidate.title)
-	})).filter((item) => item.similarity >= .5).sort((left, right) => right.similarity - left.similarity)[0]?.thread.canonicalKey ?? proposed;
-}
+/**
+* Discovery produces suggestions only. The user turns a suggestion into a Focus explicitly.
+* The legacy thread-shaped return value remains local to the discovery result renderer; it is
+* not a second persisted domain model.
+*/
 function persistWorkThreadsFromDiscovery(input) {
 	const nowMs = input.nowMs ?? Date.now();
-	const candidates = input.result.workThreadCandidates?.length ? input.result.workThreadCandidates : input.evidence.length ? [fallbackCandidate(input.result, input.evidence)] : [];
-	const persist = (candidate) => {
+	return (input.result.workThreadCandidates ?? []).flatMap((candidate) => {
 		const evidence = candidate.evidenceRefs.flatMap((ref) => {
-			const match = input.evidence.find((item) => item.sourceRef === ref);
-			return match ? [match] : [];
+			const item = input.evidence.find((entry) => entry.sourceRef === ref);
+			return item ? [{
+				label: item.observation.slice(0, 300),
+				source: item.sourceRef
+			}] : [];
 		});
-		if (!evidence.length) return [];
-		return [upsertWorkUnderstandingThread({
-			canonicalKey: canonicalKeyForCandidate({
-				projectId: input.projectId,
-				candidate
-			}),
+		if (evidence.length === 0) return [];
+		const canonicalKey = `${input.projectId}:${candidate.horizon}:${candidate.topicKey}`.slice(0, 300);
+		const stored = upsertFocusCandidate({
+			canonicalKey,
 			title: candidate.title,
 			summary: candidate.summary,
-			status: candidate.status,
-			horizon: candidate.horizon,
-			focusScore: focusScore({
-				candidate,
-				evidence,
-				snapshot: input.snapshot,
-				nowMs
-			}),
 			confidence: confidenceValue(candidate.confidence),
+			evidence,
 			projectIds: [input.projectId],
-			evidenceIds: evidence.map((item) => item.id),
-			observedAt: evidence.reduce((latest, item) => Math.max(latest, item.observedAt ?? nowMs), 0) || nowMs,
 			nowMs
-		})];
-	};
-	const persisted = candidates.flatMap(persist);
-	if (persisted.length || !input.evidence.length || !input.result.workThreadCandidates?.length) return persisted;
-	return persist(fallbackCandidate(input.result, input.evidence));
+		});
+		return [{
+			id: stored.id,
+			canonicalKey,
+			title: stored.title,
+			summary: stored.summary,
+			status: candidate.status,
+			horizon: candidate.horizon,
+			focusScore: Math.round(stored.confidence * 100),
+			confidence: stored.confidence,
+			userStatus: "unreviewed",
+			projectIds: stored.projectIds,
+			evidenceIds: [],
+			firstObservedAt: stored.discoveredAt,
+			lastObservedAt: stored.updatedAt,
+			createdAt: stored.discoveredAt,
+			updatedAt: stored.updatedAt
+		}];
+	});
 }
 //#endregion
 export { persistWorkThreadsFromDiscovery };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xopcai/xopc",
-  "version": "0.0.172",
+  "version": "0.0.174",
   "description": "Local-first AI system that remembers context, coordinates AI, and sustains long-term progress.",
   "type": "module",
   "main": "dist/src/index.js",

package/skills/tools/find-skills/SKILL.md

@@ -1,440 +1,30 @@
 ---
 name: find-skills
-description: Helps users discover, install, and manage agent skills in XOPC workspace
-license: MIT
+description: Find and evaluate installable agent skills across the XOPC Store, ClawHub, and skills.sh. Use when a user asks whether a skill exists, wants capability recommendations, or wants help choosing a high-value skill.
 ---
 
 # Find Skills
 
-This skill helps you discover, install, and manage skills in the XOPC ecosystem.
+Use `skills_marketplace_search` for discovery. It is an internal read-only Tool, so it works in Electron without an `xopc` executable or renderer bearer token. It searches XOPC Store and ClawHub directly; skills.sh results are obtained through ClawHub's federation with their original provenance preserved.
 
-## When to Use This Skill
+## Workflow
 
-Use this skill when the user:
+1. Turn the requested capability, stack, and constraints into two to four concise queries. Include useful ecosystem synonyms.
+2. Call `skills_marketplace_search` for the best query. Broaden once only when results are weak.
+3. Prefer an already-installed skill when it fits well. Do not favor a marketplace duplicate solely because it has more downloads.
+4. Compare at most five plausible candidates using this priority:
+   - direct task and environment fit;
+   - trustworthy provenance and acceptable security posture;
+   - specific, usable instructions and understandable scripts;
+   - recent maintenance and coherent versioning;
+   - downloads and stars as supporting evidence only;
+   - low overlap, dependency cost, and privilege requirements.
+5. Return three to five candidates at most. Include source, installed status, why it fits, evidence, caveats, and canonical link or full install reference. Label one **Recommended** only when there is a clear winner.
 
-- Asks "how do I do X" where X might be a common task with an existing skill
-- Says "find a skill for X" or "is there a skill for X"
-- Asks "can you do X" where X is a specialized capability
-- Wants to install a skill from GitHub or skills.sh
-- Needs to manage installed skills (enable, disable, configure)
-- Wants to browse available skills
+Treat `valueScore` as heuristic ordering, not proof of quality. Never collapse ClawHub or skills.sh entries by slug alone; retain `source`, stable `id`, `canonicalUrl`, and `install.reference`. Surface `security.scanners` warnings and failures as caveats; do not recommend a scanner-failing candidate. Disclose any source whose status is not `ok`.
 
-## XOPC Skills CLI Commands
+## Installation boundary
 
-XOPC provides built-in commands for skill management:
+Search does not install anything. If installation was not explicitly requested, ask first. When the user explicitly requests a Store or native ClawHub result, call `skill_install` with its `provider` and full `install.reference` as `name`; omit `target` for the default global install under `~/.xopc/skills`, and pass `target: workspace` only when the user explicitly requests current-agent workspace scope. Never shorten an owner-scoped ClawHub reference to its slug. Use `source` only for an explicit Git, archive, file URL, or local-path installation. A skills.sh page URL is not automatically an installable source, so use the product Skills UI when no repository or archive source is available. Never extract or print Gateway credentials, and never set `force` or overwrite an existing skill without explicit approval.
 
-### List Available Skills
-
-```bash
-# List all skills (builtin + workspace + global)
-xopc skills list
-
-# Show detailed information
-xopc skills list -v
-
-# JSON format
-xopc skills list --json
-```
-
-### Install Skills
-
-**From GitHub:**
-
-```bash
-# Clone a skill repository to workspace
-git clone <repo-url> ~/.xopc/workspace/main/skills/<skill-name>
-
-# Example: Install vercel-react-best-practices
-git clone https://github.com/vercel-labs/agent-skills.git ~/.xopc/workspace/main/skills/vercel-react-best-practices-temp
-mv ~/.xopc/workspace/main/skills/vercel-react-best-practices-temp/SKILL.md ~/.xopc/workspace/main/skills/vercel-react-best-practices/SKILL.md
-rm -rf ~/.xopc/workspace/main/skills/vercel-react-best-practices-temp
-```
-
-**Using `xopc skills install` (for skills with install specs):**
-
-```bash
-# Install skill dependencies
-xopc skills install <skill-name>
-
-# Specify install method
-xopc skills install <skill-name> -i <install-id>
-
-# Dry run (preview)
-xopc skills install <skill-name> --dry-run
-```
-
-### Enable/Disable Skills
-
-```bash
-# Enable a skill
-xopc skills enable <skill-name>
-
-# Disable a skill
-xopc skills disable <skill-name>
-```
-
-### Check Skill Status
-
-```bash
-# Show all skills status
-xopc skills status
-
-# Show specific skill details
-xopc skills status <skill-name>
-
-# JSON format
-xopc skills status --json
-```
-
-### Configure Skills
-
-```bash
-# Show current configuration
-xopc skills config <skill-name> --show
-
-# Set API key
-xopc skills config <skill-name> --api-key=YOUR_API_KEY
-
-# Set environment variables
-xopc skills config <skill-name> --env API_KEY=value --env DEBUG=true
-```
-
-### Test Skills
-
-```bash
-# Test all skills
-xopc skills test
-
-# Test specific skill
-xopc skills test <skill-name>
-
-# Validate SKILL.md file
-xopc skills test validate ./skills/weather/SKILL.md
-
-# Security audit
-xopc skills test security --deep
-```
-
-## How to Help Users Find and Install Skills
-
-### Step 1: Understand What They Need
-
-When a user asks for help with something, identify:
-
-1. **The domain** (e.g., React, testing, design, deployment)
-2. **The specific task** (e.g., writing tests, creating animations, reviewing PRs)
-3. **Whether a skill likely exists** for this common task
-
-### Step 2: Search for Skills
-
-**Option A: Check installed skills first**
-
-```bash
-xopc skills list -v
-```
-
-**Option B: Search online skill repositories**
-
-Use your browsing capabilities to search:
-- https://skills.sh/ - Official skills marketplace
-- GitHub: Search for "agent-skills" or "claude-skills"
-- Popular repos:
-  - `vercel-labs/agent-skills`
-  - `ComposioHQ/awesome-claude-skills`
-
-### Step 3: Install the Skill
-
-**For XOPC-compatible skills:**
-
-1. **Check if skill has install specs** in SKILL.md:
-   ```bash
-   xopc skills status <skill-name>
-   ```
-
-2. **Install dependencies** (if any):
-   ```bash
-   xopc skills install <skill-name>
-   ```
-
-**For GitHub skills (manual installation):**
-
-1. **Create skill directory** in workspace:
-   ```bash
-   mkdir -p ~/.xopc/workspace/main/skills/<skill-name>
-   ```
-
-2. **Download SKILL.md**:
-   ```bash
-   # From GitHub
-   curl -L https://raw.githubusercontent.com/<owner>/<repo>/main/skills/<skill-name>/SKILL.md \
-     -o ~/.xopc/workspace/main/skills/<skill-name>/SKILL.md
-   
-   # Or clone and copy
-   git clone <repo-url> /tmp/skill-temp
-   cp /tmp/skill-temp/skills/<skill-name>/SKILL.md ~/.xopc/workspace/main/skills/<skill-name>/
-   rm -rf /tmp/skill-temp
-   ```
-
-3. **Verify installation**:
-   ```bash
-   xopc skills list | grep <skill-name>
-   ```
-
-### Step 4: Present Results to User
-
-When you find relevant skills, present them with:
-
-1. **Skill name and description**
-2. **Installation status** (already installed / needs installation)
-3. **Install command** (if not installed)
-4. **Link to learn more**
-
-**Example response:**
-
-```
-I found a skill that might help!
-
-📦 vercel-react-best-practices
-   React and Next.js performance optimization guidelines from Vercel Engineering.
-
-Status: ✅ Already installed
-
-You can start using it immediately! Just ask me to help with React optimization tasks.
-```
-
-**Or if not installed:**
-
-```
-I found a skill that might help!
-
-📦 vercel-react-best-practices
-   React and Next.js performance optimization guidelines from Vercel Engineering.
-
-To install it, run:
-  xopc skills install vercel-react-best-practices
-
-Or manually:
-  mkdir -p ~/.xopc/workspace/main/skills/vercel-react-best-practices
-  curl -L https://raw.githubusercontent.com/vercel-labs/agent-skills/main/skills/vercel-react-best-practices/SKILL.md \
-    -o ~/.xopc/workspace/main/skills/vercel-react-best-practices/SKILL.md
-
-Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 5: Offer to Install
-
-If the user wants to proceed, you can help them install:
-
-```bash
-# For XOPC skills with install specs
-xopc skills install <skill-name> -y
-
-# For GitHub skills (automated)
-mkdir -p ~/.xopc/workspace/main/skills/<skill-name>
-curl -L <skill-url>/SKILL.md -o ~/.xopc/workspace/main/skills/<skill-name>/SKILL.md
-```
-
-## Common Skill Categories
-
-| Category        | Example Queries                          | Popular Skills                    |
-| --------------- | ---------------------------------------- | --------------------------------- |
-| Web Development | react, nextjs, typescript, css, tailwind | vercel-react-best-practices       |
-| Testing         | testing, jest, playwright, e2e           | playwright-testing                |
-| DevOps          | deploy, docker, kubernetes, ci-cd        | docker-compose, github-actions    |
-| Documentation   | docs, readme, changelog, api-docs        | api-documentation                 |
-| Code Quality    | review, lint, refactor, best-practices   | code-review-checklist             |
-| Design          | ui, ux, design-system, accessibility     | accessibility-checklist           |
-| Productivity    | workflow, automation, git                | git-workflow                      |
-
-## Skill Directory Structure
-
-Skills must be installed in the correct directory structure:
-
-```
-~/.xopc/workspace/main/skills/
-├── <skill-name>/           ← Each skill needs its own directory
-│   ├── SKILL.md            ← Required: Skill metadata and instructions
-│   ├── config.json         ← Optional: Default configuration
-│   └── scripts/            ← Optional: Helper scripts
-├── another-skill/
-│   └── SKILL.md
-└── ...
-```
-
-**⚠️ Common Mistake:** Don't put SKILL.md directly in `skills/` directory!
-
-**Correct:**
-```
-~/.xopc/workspace/main/skills/my-skill/SKILL.md
-```
-
-**Incorrect:**
-```
-~/.xopc/workspace/main/skills/SKILL.md  ← Won't be loaded!
-```
-
-## Skill Installation Methods
-
-### Method 1: XOPC Built-in Install (Recommended)
-
-For skills that declare install dependencies:
-
-```bash
-# Check what will be installed
-xopc skills install <skill-name> --dry-run
-
-# Install
-xopc skills install <skill-name>
-```
-
-This method:
-- ✅ Automatically installs dependencies (brew, pnpm, go, etc.)
-- ✅ Performs security scanning
-- ✅ Validates the skill
-- ✅ Reports any issues
-
-### Method 2: Manual GitHub Installation
-
-For skills without install specs:
-
-```bash
-# 1. Create directory
-mkdir -p ~/.xopc/workspace/main/skills/<skill-name>
-
-# 2. Download SKILL.md
-curl -L https://raw.githubusercontent.com/<owner>/<repo>/main/skills/<skill-name>/SKILL.md \
-  -o ~/.xopc/workspace/main/skills/<skill-name>/SKILL.md
-
-# 3. Verify
-xopc skills list | grep <skill-name>
-```
-
-### Method 3: Git Clone
-
-For complex skills with multiple files:
-
-```bash
-# Clone to temp location
-git clone <repo-url> /tmp/skill-clone
-
-# Copy skill directory
-cp -r /tmp/skill-clone/skills/<skill-name> ~/.xopc/workspace/main/skills/
-
-# Clean up
-rm -rf /tmp/skill-clone
-
-# Verify
-xopc skills status <skill-name>
-```
-
-## Troubleshooting
-
-### Skill Not Loading
-
-**Check directory structure:**
-```bash
-# Should show SKILL.md in a subdirectory
-ls -la ~/.xopc/workspace/main/skills/<skill-name>/
-```
-
-**Validate SKILL.md format:**
-```bash
-xopc skills test validate ~/.xopc/workspace/main/skills/<skill-name>/SKILL.md
-```
-
-**Check for errors:**
-```bash
-xopc skills list --json | jq '.diagnostics'
-```
-
-### Installation Failed
-
-**Check dependencies:**
-```bash
-xopc skills status <skill-name>
-```
-
-**Manual installation:**
-```bash
-# If skill requires 'curl'
-brew install curl  # macOS
-sudo apt-get install curl  # Linux
-```
-
-**Retry:**
-```bash
-xopc skills install <skill-name>
-```
-
-### Skill Not Working
-
-1. **Check if enabled:**
-   ```bash
-   xopc skills status <skill-name>
-   ```
-
-2. **Enable if needed:**
-   ```bash
-   xopc skills enable <skill-name>
-   ```
-
-3. **Check configuration:**
-   ```bash
-   xopc skills config <skill-name> --show
-   ```
-
-4. **Set API key if required:**
-   ```bash
-   xopc skills config <skill-name> --api-key=YOUR_KEY
-   ```
-
-## Examples
-
-### Example 1: User asks about React performance
-
-**User:** "How can I make my React app faster?"
-
-**You:**
-1. Check installed skills: `xopc skills list | grep -i react`
-2. If found: "You have the vercel-react-best-practices skill installed!"
-3. If not found: Offer to install it
-
-### Example 2: User wants to add testing capability
-
-**User:** "Can you help me write Playwright tests?"
-
-**You:**
-1. Search for testing skills
-2. Found: `playwright-testing`
-3. Install:
-   ```bash
-   mkdir -p ~/.xopc/workspace/main/skills/playwright-testing
-   curl -L <url>/SKILL.md -o ~/.xopc/workspace/main/skills/playwright-testing/SKILL.md
-   ```
-4. Verify: `xopc skills status playwright-testing`
-
-### Example 3: User wants to browse all skills
-
-**User:** "What skills do you have?"
-
-**You:**
-```bash
-xopc skills list -v
-```
-
-Then present the list with descriptions.
-
-## Tips for Effective Skill Management
-
-1. **Always verify installation**: Run `xopc skills list` after installing
-2. **Check skill status**: Use `xopc skills status <name>` for details
-3. **Keep skills updated**: Periodically check for skill updates
-4. **Review security**: Run `xopc skills test security` for audits
-5. **Organize workspace**: Keep only needed skills to reduce clutter
-
-## References
-
-- **Skills Marketplace**: https://skills.sh/
-- **XOPC Skills CLI**: `xopc skills --help`
-- **Skill Format**: SKILL.md frontmatter specification
-- **GitHub Skills**: Search "agent-skills" on GitHub
+If no candidate clears the quality bar, say so and propose creating a focused skill instead of padding the recommendation.