fuli-context 0.2.0

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "fuli-context",
+  "version": "0.2.0",
+  "description": "Local-first context graph for AI agents.",
+  "type": "module",
+  "files": [
+    "npm-shrinkwrap.json",
+    "src/",
+    "dist/web/",
+    "graph-provider/Dockerfile",
+    "graph-provider/pyproject.toml",
+    "graph-provider/fuli_graph/*.py",
+    "graph-provider/fuli_graph/**/*.py",
+    "skills/",
+    "compose.graphiti.yml"
+  ],
+  "bin": {
+    "fl": "./src/cli.js",
+    "fuli": "./src/cli.js"
+  },
+  "keywords": [
+    "ai-agent",
+    "mcp",
+    "context",
+    "knowledge-graph",
+    "local-first",
+    "codex",
+    "claude-code"
+  ],
+  "scripts": {
+    "mcp": "node src/mcp-server.js",
+    "dev": "run-p dev:server dev:web",
+    "dev:server": "node src/server.js",
+    "dev:web": "vite",
+    "build": "run-s typecheck:web build:web",
+    "build:web": "vite build",
+    "typecheck:web": "vue-tsc --noEmit -p tsconfig.app.json",
+    "test:node": "node --test",
+    "test:web": "vitest run --config vitest.config.ts",
+    "test:package": "node scripts/package-smoke.js",
+    "test:knowledge:live": "node acceptance/knowledge-live.js",
+    "start": "node src/server.js",
+    "graph:setup": "node src/graphiti/setup.js",
+    "graph:up": "docker compose -f compose.graphiti.yml up -d --build",
+    "graph:down": "docker compose -f compose.graphiti.yml down",
+    "test:structure": "node --test test/source-structure.test.js",
+    "pretest": "npm run build:web",
+    "test": "run-s typecheck:web test:node test:web",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=24.12"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JevonsCode/fuli.git"
+  },
+  "homepage": "https://github.com/JevonsCode/fuli#readme",
+  "bugs": {
+    "url": "https://github.com/JevonsCode/fuli/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@hono/node-server": "2.0.12",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.11.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/d3": "^7.4.3",
+    "@types/node": "^24.13.3",
+    "@vitejs/plugin-vue": "^6.0.8",
+    "@vue/test-utils": "^2.4.11",
+    "brace-expansion": "5.0.8",
+    "d3": "^7.9.0",
+    "gsap": "^3.15.0",
+    "jsdom": "^29.1.1",
+    "linkedom": "^0.18.12",
+    "npm-run-all2": "^9.0.2",
+    "pinia": "^4.0.2",
+    "typescript": "~6.0.0",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10",
+    "vue": "^3.5.40",
+    "vue-router": "^5.2.0",
+    "vue-tsc": "^3.3.8"
+  },
+  "overrides": {
+    "@modelcontextprotocol/sdk": {
+      "@hono/node-server": "2.0.12"
+    },
+    "brace-expansion": "$brace-expansion",
+    "fast-uri": "3.1.4"
+  }
+}

package/skills/capturing-session-knowledge/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: capturing-session-knowledge
+description: Use when Fuli tools are available and a task may depend on remembered personal preferences or durable project facts such as URLs, routes, requirements, architecture, prior decisions, runbooks, or rationale, or when ordinary work produces reusable knowledge worth retaining.
+---
+
+# Capturing Session Knowledge
+
+Accumulate reusable knowledge without interrupting the user's normal work. Keep an internal session buffer and flush focused batches at a natural task boundary or before the session ends.
+
+## Load Collaboration Preferences
+
+At the start of every user task, before any other tool or answer, call
+`get_collaboration_preferences`. Pass `projectPath` as the current working directory. Fuli uses
+that path only for this local MCP call, never stores or returns it, and resolves the exact local
+personal project itself. Do not infer or guess `personalProjectId` in the Agent.
+
+Apply only `effective_preferences`. Personal-global preferences apply in every user task;
+project-scoped preferences layer on only for the exact selected project. Do not apply items
+listed as conflicts, and do not borrow preferences from a related, similarly named, or guessed
+project. Human or authoritative-source confirmation outranks explicitly marked
+`agent_confirmed` preferences. Pending preferences remain search-only; invalid and
+unrelated-project preferences are intentionally excluded. Automatic preference injection is
+not usage evidence.
+When `get_collaboration_preferences` returns a `deferred_conflict`, leave it untouched unless
+the current task would use either side. Before using a relevant deferred conflict, compare both
+sides and call `resolve_deferred_preference_conflict`; apply only the successfully resolved
+result. The resolution record must remain marked as previously conflicted and AI-resolved.
+Before any write tool call, enforce every applicable preference in the actual payload.
+Mentioning a preference only in the final answer is not compliance.
+
+## Retrieve Context
+
+Call `search_knowledge_graph` when prior durable context can materially improve the task.
+Before saying that a stable fact is unknown or asking the user to provide it again, search
+Fuli if it may have been learned earlier. Strong triggers include URLs, deployment routes,
+requirements, terminology, architecture, prior decisions, runbooks, rationale, and remembered
+personal preferences. Do not search for a fully self-contained task or use Fuli as proof of live
+external state.
+
+Pending knowledge is eligible for on-demand retrieval and must remain visibly marked.
+`agent_confirmed` knowledge is usable but ranks below user or authoritative-source
+confirmation.
+
+Treat an obvious content-location request specially: examples include asking for a named page,
+URL, route, deployment, document, file, or where a durable artifact is located.
+
+1. Run one bounded search that preserves distinctive names, identifiers, and quoted phrases from
+   the user's wording. Do not dilute them with generic expansion. An unrelated result is no
+   evidence even if the tool labels it matched.
+2. If there is no supporting result, ask whether to widen this one read-only lookup to all
+   registered local personal projects and, if still unresolved, the current repository or
+   workspace files. Explain that it applies only to this lookup, excludes public projects and
+   paths outside the current workspace, then stop and wait for the user's answer.
+3. Only after explicit confirmation, call `search_knowledge_graph` again with
+   `personalProjectScope: all_local_confirmed`. Never infer consent from the lookup intent itself.
+4. This expanded scope does not expand any public project or subscription and must not become a
+   persistent default. If it still has no supporting result, continue with a local file fallback:
+   - When the current directory is inside one repository, search only that repository.
+   - When it is an intentional multi-repository workspace root, search only that workspace.
+   - When it is the user home, filesystem root, or otherwise too broad or ambiguous, ask for an
+     exact safe repository/workspace root and stop. Never recursively scan a home or system root.
+   - Within the safe root, use read-only `Grep`/`Glob`/`Read` or `rg`. Preserve the exact quoted
+     name first, respect ignore rules, and inspect only relevant matches and routing/deployment
+     context. Do not inspect credential stores, browser data, secrets, or paths outside the root.
+   - A route string alone is not a live URL. Require deployment-domain or equivalent evidence.
+     If local files still provide no supporting evidence, ask for a project, document, or source
+     clue.
+
+Personal retrieval always includes the bounded personal-global profile. For a local personal
+project, pass its exact `personalProjectId`; if the user explicitly names another personal
+project, resolve it with `list_personal_projects` and add only that exact ID through
+`contextPersonalProjectIds`. Without an active local project, search only the personal-global
+profile. For public context, pass only the active or explicitly named subscribed public project
+IDs; never search every personal project, every subscription, or the whole graph by default.
+Use the current repository, the user's wording, and `list_knowledge_spaces` to resolve scope.
+Ask if the active project remains ambiguous.
+
+The active project may also retrieve only knowledge explicitly marked inheritable from projects
+reached through outgoing `PART_OF` or `USES_KNOWLEDGE_FROM` relations. Never inherit
+project-scoped personal preferences, never traverse `RELATED_TO`, stop after two hops, and retain
+the returned scope path. Exact active-project knowledge with the same stable key overrides an
+inherited item.
+
+After a retrieved personal item materially affects the final answer or a completed action, call
+`record_knowledge_usage` once for that task and item with `cited` or `applied`. Do not record
+retrieval, inspection, automatic preference injection, or unused context. Usage evidence can
+promote only to `agent_confirmed`; it never substitutes for human confirmation or makes an item
+eligible for public publication. Use the current user task's caller-stable identifier as
+`taskId` and reuse it on retries; never generate another ID to recount the same task.
+
+The current `agent-usage-v1` policy requires at least five idempotent material-use events across
+at least three distinct tasks in the current content generation, with no open knowledge or
+preference conflict. It maintains utility and confidence as separate scores and caps
+Agent-confirmed confidence below human/source confirmation. Agents report qualifying use; they
+do not calculate, override, or claim the promotion themselves.
+
+For “why was this code written?” questions, use stored evidence relationships and a separately configured Git MCP together. Never invent a commit, PRD link, or missing history. For “what errors happened today?” questions, obtain current data from a monitoring/log MCP; use Fuli only for runbooks, architecture, prior causes, and other durable context.
+
+Every `search_knowledge_graph` response provides two terminal-safe Markdown choices:
+`sourceMarker` for returned items that support the answer, and `noMatchSourceMarker`
+for a search with no supporting result. A tool-labelled match that is irrelevant to
+the answer still requires `noMatchSourceMarker`.
+
+For the chosen marker, the final answer must begin with its `leadMarkdown` unchanged,
+before any heading or prose, and append its `markdown` unchanged after the answer. If
+any search supports the answer, choose `sourceMarker` from one supporting search. If
+none do, choose `noMatchSourceMarker`. Never show either marker when no search was
+called. Never fabricate, rewrite, omit, or wrap markers in HTML. A capture or write
+result is not a read citation.
+
+## Decide What Persists
+
+Capture confirmed, stable information:
+
+- Personal: the user's enduring preferences, boundaries, habits, and working methods. Project-specific personal rules must explicitly link to that project instead of becoming global defaults.
+- Project: PRD facts, requirements, terminology, decisions, constraints, architecture, routes, APIs, metrics, and document-derived knowledge.
+
+Do not capture credentials, tokens, cookies, private keys, raw transcripts, temporary logs, command output, speculative conclusions, or disposable implementation details. Treat a correction as a replacement, not an additional conflicting fact.
+
+## Classify Knowledge State
+
+Every entity and relationship needs an `originQuadrant`, `confirmationBasis`, and
+`confirmationStatus`. These fields answer three separate questions:
+
+1. `originQuadrant` records how the item was discovered. It is not a truth score and does
+   not change merely because the item is later confirmed.
+2. `confirmationBasis` explains why the item exists, why it belongs to that quadrant,
+   who proposed it, and—when confirmed—who confirmed it and when.
+3. `confirmationStatus` is `pending`, `agent_confirmed`, or `confirmed`.
+
+Keep the canonical quadrant names:
+
+- `known_known`: knowledge or a conclusion that was explicitly expressed when captured.
+- `known_unknown`: an unresolved question or tradeoff that was explicitly recognized.
+- `unknown_known`: tacit knowledge inferred from behaviour, examples, prototypes, or
+  reactions.
+- `unknown_unknown`: a potential blind spot surfaced during open exploration. A truly
+  unknown item cannot be stored; this label describes how the recorded candidate arose.
+
+Every `confirmationBasis` must contain:
+
+- `existenceReason`: why this item was created;
+- `quadrantReason`: why it was assigned to this quadrant;
+- `proposedBy`: `{ kind, label }`, where kind is `user`, `agent`,
+  `authoritative_source`, or `import`;
+- `confirmedBy` and `confirmedAt` together when confirmed.
+
+An Agent may propose and explain knowledge. A user or authoritative source creates
+`confirmed`; a deterministic Fuli usage policy may create only `agent_confirmed`, with an Agent
+confirmer, timestamp, and policy version. Agent confirmation is lower-authority, never
+public-eligible, and must not be produced by retrieval alone. Confirmation covers the content
+and its classification. If either changes, return the item to `pending` and start a new usage
+generation unless the same revision explicitly records a new valid human/source confirmer and
+confirmation time. Legacy items without that audit record are `pending`, even if an old
+`epistemicStatus` said `confirmed`.
+
+`currentQuadrant` and `epistemicStatus` are legacy compatibility fields. Do not use them
+for new product logic and do not treat them as confirmation evidence.
+
+Agent retrieval includes pending items on demand and returns their status so the caller can
+calibrate claims. Only user or authoritative-source `confirmed` project knowledge may enter
+public review, regardless of how it was originally discovered; normal personal preview and
+Maintainer review gates still apply.
+
+## Grow The Personal Profile Separately
+
+Durable facts about the person's collaboration style use `profileAspect`. They default to
+the personal-global graph without `personalProjectId`:
+
+- `taste`: aesthetic, writing, product, architecture, or engineering outcomes the user
+  likes or rejects.
+- `personality`: stable self-described collaboration or working traits. Agent-inferred
+  personality stays `pending` and must never be silently promoted to confirmed.
+- `judgment_preference`: repeated decision criteria, tradeoff priorities, risk posture,
+  and conditions that change how the user chooses.
+
+When the user explicitly limits one preference to a project, keep `profileAspect` and capture
+it with that exact `personalProjectId`; this makes the preference project-scoped without
+turning it into public project knowledge. Use `set_personal_preference_scope` when the user
+later changes the scope. Never put any personal-profile item into a public proposal.
+For a preference that may have both global and project-specific forms, store a stable
+`attributes.preferenceKey` on each form so the project value can explicitly override the same
+global decision without hiding unrelated preferences.
+
+## Route by Ownership
+
+- Route global personal knowledge to `targetKind: personal` without `personalProjectId`; it is written directly to the local personal graph.
+- Route knowledge for a local personal project, including an explicitly project-scoped personal preference, to `targetKind: personal` with that project's exact `personalProjectId`. This is private local knowledge, not a public submission.
+- Route knowledge to `targetKind: project` only when the target is an explicitly selected subscribed public project. It becomes a team-shared Provider Proposal and must remain pending until a Maintainer reviews it.
+- Never treat a project as public merely because the current repository or conversation has a project name. Only an active subscription makes it eligible for public project routing.
+- Never omit `personalProjectId` when the current repository or conversation has already resolved one local personal project; doing so would leak project-specific facts into the personal-global scope.
+- Never add another personal project to `contextPersonalProjectIds` merely because it is related, similarly named, or referenced by the active project. Automatic borrowing is limited to item-level inheritable knowledge reached through `PART_OF` or `USES_KNOWLEDGE_FROM`; all other cross-project borrowing requires an explicit user request or selection and applies only to the current search context.
+- Never route project facts through the personal graph to bypass review.
+- Never auto-approve a project Proposal.
+- If ownership is genuinely ambiguous and changes who can see the knowledge, ask one concise question instead of guessing.
+
+## Resolve Or Create The Local Project
+
+Before the first project-scoped capture in a repository:
+
+1. Call `list_knowledge_spaces`, then `list_personal_projects` for the active personal space.
+2. Resolve the repository root from the current working directory and repo-local manifests. Use a stable, human-readable project ID derived from the repository or manifest name. Never store an absolute path, local username, hostname, credential, or private remote URL as the project ID or public profile evidence.
+3. Match an existing personal project by exact project ID, publication mapping, or confirmed repository identity. Do not merge projects from similar names.
+4. When one previously unseen repository has an unambiguous identity, immediately create a minimal private personal project with `upsert_personal_project`. Use lifecycle `active`, a private repository source with no URI, and an evidence-coverage summary containing only facts visible in the current repository. Do not generate a generic list of information the project supposedly lacks.
+5. Ask one project-identity question only when the working directory contains multiple plausible projects or the repository identity conflicts with an existing project.
+
+Creating a personal project is local classification, not public publication. Never create or subscribe to a public project automatically.
+
+## Structure and Flush
+
+Use `capture_session_knowledge` with a small, coherent batch:
+
+1. List spaces when the target IDs are not already known.
+2. Summarize the durable facts; do not submit the entire source document or conversation.
+3. Create stable entity keys, typed entities, and explicit uppercase relationships. When relevant, model `GitCommit`, `CodeSymbol`, `PRDSection`, `Runbook`, and `Incident` entities and connect them with relationships such as `IMPLEMENTED_IN`, `DEFINED_BY`, `MOTIVATED_BY`, `APPLIES_TO`, and `INVESTIGATED_WITH`.
+4. Include source kind, source application, a non-sensitive source description, reference time, session ID, and a retry-safe idempotency key. When available, include a stable source turn ID and only the smallest relevant excerpt needed to understand the evidence; never include a full transcript.
+5. Use `supersedes` when replacing a known relationship and set confidence below `1` only when the source itself expresses uncertainty.
+6. Flush silently at the boundary. Continue the user's task without narrating routine capture.
+
+If `capture_session_knowledge` or automatic project creation returns `capture_disabled`, the
+user has disabled automatic capture. Do not retry, do not create a fallback record elsewhere,
+and do not describe the skipped batch as stored. Existing knowledge may still be queried.
+
+Before sending the final response, perform one checkpoint: either flush the durable batch or determine that this turn produced no reusable knowledge. Do not finish a reusable project decision with an unflushed batch.
+
+Only notify the user when capture fails, conflicts with existing knowledge, or requires an ownership decision. If project knowledge was proposed successfully, do not interrupt merely to announce the pending review item.

package/skills/capturing-session-knowledge/agents/openai.yaml

@@ -0,0 +1,13 @@
+interface:
+  display_name: "Capturing Session Knowledge"
+  short_description: "Recall and retain durable personal and project context"
+  default_prompt: "Use $capturing-session-knowledge to load effective collaboration preferences, retrieve relevant durable context, and retain reusable knowledge in Fuli."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "fuli"
+      description: "Local Fuli Graphiti knowledge tools"
+
+policy:
+  allow_implicit_invocation: true

package/skills/grilling-project/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: grilling-project
+description: Use when creating, clarifying, updating, assessing, or publishing a Fuli project profile, especially when the user has only a partial project description or asks to add PRDs, technical documents, frontend/backend repositories, runbooks, monitoring, scope, or public-project metadata. Interview one question at a time, discover repository facts first, record confirmed personal project information progressively, and never publish before a final public-boundary preview is confirmed.
+---
+
+# Grilling Project
+
+Turn incomplete project knowledge into an evidence-backed Fuli personal project profile, then optionally publish it. Keep the interview light: discover what can be discovered, ask one useful question, recommend an answer, and wait.
+
+Read [project-profile.md](references/project-profile.md) before assessing evidence coverage or constructing a project profile.
+
+## Non-negotiable behavior
+
+- During the interview, ask exactly one question in each question-bearing message. Pure status or failure notifications do not need a synthetic question.
+- Before asking, use read-only repository inspection to discover relevant facts that are already available.
+- State the current inference separately from confirmed facts.
+- Include a recommended answer and explain its consequence briefly.
+- Do not publish a public project until the user confirms a final publication preview.
+- Evidence coverage is display-only. Never block publication because the score is low.
+- Record confirmed information in the personal graph as the interview progresses. Personal recording is not public publication.
+- Do not silently turn a related project into a subscription. Subscription is always explicit.
+
+## Start with Fuli state
+
+1. Call `list_knowledge_spaces` to learn the active personal space, public Provider state, subscriptions, and public projects.
+2. Call `list_personal_projects` for the active personal space.
+3. Match by stable project ID or an existing publication mapping first. Use repository evidence second. Never merge projects from name similarity alone; ask one identity question when the match is ambiguous.
+4. If a public project already corresponds to it, treat publication as a profile sync, not a second project.
+
+Use a stable, human-readable `projectId` derived from the repository/project name. Do not derive it from a local absolute path, username, hostname, or confidential identifier.
+
+## Discover before asking
+
+Inspect only the current project and directly relevant files. Typical evidence includes:
+
+- README and project documentation indexes
+- package or build manifests
+- architecture and deployment documents
+- repository-local Git remotes
+- frontend/backend directory layout
+- run, test, deployment, rollback, monitoring, and incident instructions
+
+Do not read global Git configuration, credential helpers, SSH configuration, tokens, unrelated repositories, browser data, or secret stores. Treat internal URLs and repository remotes as private evidence until the user explicitly approves public inclusion.
+
+Label every proposed fact as one of:
+
+- **confirmed** — directly stated by the user or supported by inspected evidence
+- **inferred** — plausible but not yet confirmed
+
+Summarize only information and evidence that currently exist. Do not present a generated
+list of “missing items”; absence from a generic checklist is not evidence that the project
+actually needs that item.
+
+Do not ask the user for a fact that can be verified safely from the current repository.
+
+## Interview loop
+
+Choose the highest-impact clarification that follows from the user's goal or current
+evidence. Do not manufacture questions solely to fill a generic checklist. In each turn:
+
+1. Summarize newly confirmed facts in one or two sentences.
+2. State any relevant inference and its evidence.
+3. Ask one question only.
+4. Put the recommended answer first and explain the tradeoff.
+5. Wait for the answer.
+
+Prefer project identity, purpose, scope, and privacy boundary before lower-impact metadata. Skip resolved categories. If the user rejects a recommendation, record their choice without repeatedly arguing.
+
+After a meaningful confirmed update, call `upsert_personal_project` with the complete current profile, not a partial patch. Preserve earlier confirmed fields and sources. Routine successful updates stay quiet.
+
+## Evidence coverage assessment
+
+Recompute the assessment when evidence changes. Follow the dimensions and scoring guidance in the reference.
+
+The assessment must contain:
+
+- an overall score and label
+- confirmed facts
+- clearly marked inferences
+- dimension-level evidence already present
+- `analyzedAt` set to the current time
+
+Never inflate the score from a filename alone. A discovered link confirms that a source exists, not that its content is current or complete. Never present inference as confirmed.
+
+## Publication gate
+
+When the profile is useful enough for the user to review—or the user asks to publish—show one final preview containing:
+
+- project name, purpose, scope, and lifecycle
+- public sources and links
+- excluded private or restricted sources
+- confirmed and inferred existing information
+- evidence coverage score with the sentence “资料覆盖仅用于展示，不影响发布”
+- the selected public Provider
+- the consequences: publisher becomes Owner and Maintainer, and the personal space is automatically subscribed
+
+Ask one final question: whether to publish this exact preview. Recommend publishing when the public boundary is clear; sparse evidence does not block publication.
+
+If more than one public Provider is ready and no existing project mapping determines the target, ask one Provider-selection question before the final preview. Do not select the first Provider implicitly.
+
+Confirmation approves only the public sources and links individually listed in that preview. Unlisted sources remain private or restricted.
+
+Only after explicit confirmation, call `publish_personal_project` with `personalSpaceId`, `localProjectId`, and `providerUrl` from the preview.
+
+If no public Provider is connected:
+
+- continue building the personal project profile normally
+- do not offer a fake or queued publication
+- explain once, when relevant, that public publication is unavailable until a Provider is connected
+- do not automatically replay publication later
+
+## Project relationships
+
+Use `create_project_relation` only after both public projects are identified and the user confirms the relationship type.
+
+- `PART_OF` means a real hierarchy and requires confirmation by a Maintainer of the parent project.
+- `DEPENDS_ON` means a runtime, delivery, or development dependency.
+- `PROVIDES_TO` means one project supplies a capability to another.
+- `SHARES_CAPABILITY_WITH` means reusable capability overlap without hierarchy.
+- `SUCCESSOR_OF` means replacement or evolution.
+- `RELATED_TO` is the fallback when no stronger semantics are confirmed.
+
+Do not use `PART_OF` merely because two projects are in the same business domain. Do not subscribe to the related project unless the user separately asks.
+
+## Safety
+
+Never record or publish credentials, tokens, cookies, private keys, personal/personnel information, or unrelated machine details. Keep confidential material out of names, summaries, source titles, URIs, assessment evidence, and publication previews.
+
+Sources marked `private` or `restricted` may remain in the personal profile but cannot be sent to the public Provider. If the public profile would reveal company-confidential information, stop and ask one boundary question before proceeding.

package/skills/grilling-project/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Grilling Project"
+  short_description: "一次一问地澄清项目资料、已有证据覆盖与公共发布边界"
+  default_prompt: "Use $grilling-project to clarify this project one question at a time before recording or publishing it."

package/skills/grilling-project/references/project-profile.md

@@ -0,0 +1,105 @@
+# Fuli project profile reference
+
+Use this reference to construct the complete payload for `upsert_personal_project`.
+Optional fields may be absent. Publication is never blocked by this guidance.
+
+## Profile fields
+
+- `name`: confirmed user-facing project name
+- `purpose`: problem solved, primary users, and intended outcome
+- `scope`: included and excluded product or technical boundaries
+- `technicalSummary`: architecture, important modules, runtimes, and constraints
+- `lifecycle`: `planned`, `active`, `maintenance`, or `archived`
+- `sources`: evidence records described below
+- `boundaries`: durable development, ownership, privacy, and operational rules
+- `assessment`: evidence-backed summary of information currently recorded
+
+## Source records
+
+Every source needs a stable `key`, `kind`, and `title`. Add `uri` and `summary` only when supported by evidence.
+
+Supported kinds:
+
+- `prd`
+- `product_document`
+- `technical_document`
+- `frontend_repository`
+- `backend_repository`
+- `repository`
+- `design`
+- `runbook`
+- `monitoring`
+- `issue_tracker`
+- `other`
+
+Set sensitivity to:
+
+- `normal` only when the source is approved for public inclusion
+- `private` for personal or non-public project evidence
+- `restricted` for highly controlled evidence that must never reach a public Provider
+
+Do not store credentials at any sensitivity.
+
+## Evidence coverage dimensions
+
+Use these dimensions only to summarize evidence already present, not to declare what a
+project is missing. Each dimension has a 0–100 coverage score. The overall score should
+be a reasoned weighted average of supported evidence, not an unexamined count of links.
+
+1. `identity` — purpose, users, lifecycle, scope, and exclusions
+2. `product` — PRD or equivalent product evidence and current requirements
+3. `technical` — architecture, key modules, interfaces, and constraints
+4. `code` — confirmed frontend/backend repositories and ownership boundaries
+5. `operations` — run, deploy, rollback, monitoring, and incident evidence
+6. `governance` — privacy boundary, contribution rules, maintainership, and durable development rules
+
+Suggested weighting:
+
+- identity: 20%
+- product: 20%
+- technical: 20%
+- code: 20%
+- operations: 10%
+- governance: 10%
+
+Scoring evidence:
+
+- 80–100: current, direct, and sufficiently detailed evidence
+- 50–79: partial evidence with material gaps
+- 20–49: mainly user statements or weak/inferred evidence
+- 0–19: no usable evidence currently recorded or evidence is contradicted
+
+Overall labels:
+
+- `needs_clarification`: 0–39
+- `partially_documented`: 40–74
+- `well_documented`: 75–100
+
+Each dimension contains:
+
+- `key`
+- `label`
+- `score`
+- `state`: `confirmed` or `inferred`
+- `evidence`: short statements pointing to the evidence
+
+The assessment contains `confirmed` and `inferred` summaries only. It does not contain a
+generated `missing` list. A zero score means Fuli currently has no usable evidence for
+that dimension; it does not claim the project must add a particular artifact.
+
+## Publication checklist
+
+Before asking for final confirmation, verify the preview explicitly covers:
+
+- project purpose and scope
+- PRD/product documentation
+- technical documentation
+- frontend and backend repository evidence
+- runbook or local run/deployment instructions
+- monitoring and error-diagnosis instructions
+- privacy and public-sharing boundary
+- durable project development rules
+- confirmed and inferred existing information
+- Owner/automatic-subscription consequence
+
+Sparse evidence never prevents publication.

package/src/agent/candidate-read-service.js

@@ -0,0 +1,53 @@
+import { SpaceKind } from '../models.js';
+import { isSafeAgentText } from './public-read-policy.js';
+import { requirePersonalSpace } from './space-boundary.js';
+
+export class AgentCandidateReadService {
+  constructor(store) {
+    this.store = store;
+  }
+
+  list(personalSpaceId) {
+    requirePersonalSpace(this.store, personalSpaceId);
+    return this.store.pendingCandidates(personalSpaceId)
+      .map((candidate) => this.#project(candidate, personalSpaceId));
+  }
+
+  listForSpace(personalSpaceId, spaceId) {
+    return this.list(personalSpaceId)
+      .filter((candidate) => !candidate.targetSpaceId || candidate.targetSpaceId === spaceId);
+  }
+
+  #project(candidate, personalSpaceId) {
+    const resolvedTarget = candidate.targetSpaceId
+      ? this.store.getSpace(candidate.targetSpaceId)
+      : null;
+    const target = resolvedTarget?.kind === SpaceKind.PUBLIC ? resolvedTarget : null;
+    return {
+      id: candidate.id,
+      reason: isSafeAgentText(candidate.reason) ? candidate.reason : null,
+      status: candidate.status,
+      createdAt: candidate.createdAt,
+      targetSpaceId: target?.id ?? null,
+      targetSpaceName: target?.name ?? null,
+      source: this.#source(candidate.episodeId, personalSpaceId)
+    };
+  }
+
+  #source(episodeId, personalSpaceId) {
+    const episode = this.store.getEpisode(episodeId);
+    if (!episode || episode.spaceId !== personalSpaceId) return null;
+    if (![
+      episode.sourceKind,
+      episode.sourceUri,
+      episode.body,
+      JSON.stringify(episode.metadata)
+    ].every(isSafeAgentText)) return null;
+    return {
+      id: episode.id,
+      kind: episode.sourceKind,
+      uri: episode.sourceUri,
+      createdAt: episode.createdAt
+    };
+  }
+}