@xevy/skills 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/.claude-plugin/plugin.json +23 -0
  2. package/README.md +133 -0
  3. package/bin/cli.mjs +387 -0
  4. package/bin/version.mjs +120 -0
  5. package/bin/xevy-creds.mjs +81 -0
  6. package/bin/xevy-link-repo.mjs +47 -0
  7. package/bin/xevy-sync-env.mjs +102 -0
  8. package/package.json +33 -0
  9. package/skills/analyze/SKILL.md +26 -0
  10. package/skills/analyze-here/SKILL.md +30 -0
  11. package/skills/create-document/SKILL.md +32 -0
  12. package/skills/create-report/SKILL.md +169 -0
  13. package/skills/create-report/examples.md +134 -0
  14. package/skills/create-xevy-task/SKILL.md +68 -0
  15. package/skills/deploy/SKILL.md +25 -0
  16. package/skills/execute/SKILL.md +29 -0
  17. package/skills/execute-here/SKILL.md +35 -0
  18. package/skills/fix/SKILL.md +26 -0
  19. package/skills/fix-here/SKILL.md +23 -0
  20. package/skills/generate-image/SKILL.md +31 -0
  21. package/skills/investigate/SKILL.md +218 -0
  22. package/skills/investigate/examples.md +170 -0
  23. package/skills/manage-documents/SKILL.md +39 -0
  24. package/skills/mark-ready/SKILL.md +29 -0
  25. package/skills/merge/SKILL.md +24 -0
  26. package/skills/merge-here/SKILL.md +22 -0
  27. package/skills/move-to-qa/SKILL.md +21 -0
  28. package/skills/move-to-qa-here/SKILL.md +21 -0
  29. package/skills/plan/SKILL.md +24 -0
  30. package/skills/plan-here/SKILL.md +26 -0
  31. package/skills/xevy-design/SKILL.md +103 -0
  32. package/skills/xevy-design/reference/craft.md +69 -0
  33. package/skills/xevy-design/reference/critique.md +33 -0
  34. package/skills/xevy-design/reference/polish.md +25 -0
  35. package/skills/xevy-design/reference/setup.md +82 -0
  36. package/skills/xevy-design/reference/shape.md +40 -0
  37. package/skills/xevy-setup/SKILL.md +56 -0
@@ -0,0 +1,81 @@
1
+ /**
2
+ * Shared credential + arg helpers for the Xevy plugin bin scripts.
3
+ *
4
+ * Resolves the API key + base URL from (in order) env vars, then
5
+ * ~/.config/xevy/credentials (the file setup.sh / the pi extension write).
6
+ * The key is NEVER printed by these helpers or their callers.
7
+ */
8
+ import fs from "node:fs";
9
+ import os from "node:os";
10
+ import path from "node:path";
11
+
12
+ export function resolveCreds() {
13
+ let baseUrl = process.env.XEVY_BASE;
14
+ let token = process.env.XEVY_API_KEY;
15
+
16
+ const credFile = path.join(
17
+ process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"),
18
+ "xevy",
19
+ "credentials",
20
+ );
21
+ if ((!baseUrl || !token) && fs.existsSync(credFile)) {
22
+ for (const line of fs.readFileSync(credFile, "utf8").split(/\r?\n/)) {
23
+ const m = line.match(/^\s*(\w+)\s*=\s*(.*)$/);
24
+ if (!m) continue;
25
+ if (m[1] === "baseUrl" && !baseUrl) baseUrl = m[2].trim();
26
+ if (m[1] === "token" && !token) token = m[2].trim();
27
+ }
28
+ }
29
+
30
+ baseUrl = (baseUrl || "https://xevy.ai").replace(/\/+$/, "");
31
+ if (!token) {
32
+ console.error(
33
+ "No Xevy API key found. Set XEVY_API_KEY (and optionally XEVY_BASE), " +
34
+ "or create ~/.config/xevy/credentials with token=… and baseUrl=…",
35
+ );
36
+ process.exit(2);
37
+ }
38
+ return { baseUrl, token };
39
+ }
40
+
41
+ /** Minimal --flag value parser. Returns a plain object. */
42
+ export function parseArgs(argv) {
43
+ const out = {};
44
+ for (let i = 0; i < argv.length; i++) {
45
+ const a = argv[i];
46
+ if (a.startsWith("--")) {
47
+ const key = a.slice(2);
48
+ const next = argv[i + 1];
49
+ if (next === undefined || next.startsWith("--")) {
50
+ out[key] = true;
51
+ } else {
52
+ out[key] = next;
53
+ i++;
54
+ }
55
+ }
56
+ }
57
+ return out;
58
+ }
59
+
60
+ export async function apiFetch(creds, method, routePath, body) {
61
+ const res = await fetch(`${creds.baseUrl}${routePath}`, {
62
+ method,
63
+ headers: {
64
+ Authorization: `Bearer ${creds.token}`,
65
+ ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
66
+ },
67
+ body: body !== undefined ? JSON.stringify(body) : undefined,
68
+ });
69
+ const text = await res.text();
70
+ let json;
71
+ try {
72
+ json = text ? JSON.parse(text) : null;
73
+ } catch {
74
+ json = text;
75
+ }
76
+ if (!res.ok) {
77
+ const msg = json && typeof json === "object" && json.error ? json.error : `HTTP ${res.status}`;
78
+ throw new Error(`${method} ${routePath} → ${msg}`);
79
+ }
80
+ return json;
81
+ }
@@ -0,0 +1,47 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Link the current git repository to an Xevy project.
4
+ * Wraps POST /api/projects/:ws/:proj/repositories with the stored API key.
5
+ * Prints only the outcome — no secrets.
6
+ *
7
+ * Usage:
8
+ * node xevy-link-repo.mjs --workspace <ws> --project <proj> --remote <git-url> [--role app]
9
+ */
10
+ import { resolveCreds, parseArgs, apiFetch } from "./xevy-creds.mjs";
11
+
12
+ async function main() {
13
+ const args = parseArgs(process.argv.slice(2));
14
+ const ws = args.workspace || args.w;
15
+ const proj = args.project || args.p;
16
+ const gitUrl = args.remote || args.gitUrl;
17
+ const role = typeof args.role === "string" ? args.role : "app";
18
+ if (!ws || !proj || !gitUrl) {
19
+ console.error("Usage: xevy-link-repo.mjs --workspace <ws> --project <proj> --remote <git-url> [--role app]");
20
+ process.exit(2);
21
+ }
22
+
23
+ const creds = resolveCreds();
24
+
25
+ // Check existing link first so re-runs are idempotent.
26
+ const lookup = await apiFetch(
27
+ creds,
28
+ "GET",
29
+ `/api/repositories/lookup?gitUrl=${encodeURIComponent(gitUrl)}&workspaceIdentifier=${encodeURIComponent(ws)}&projectIdentifier=${encodeURIComponent(proj)}`,
30
+ ).catch(() => null);
31
+ if (lookup && lookup.sameProject) {
32
+ console.log("Repository already linked to this project — no change.");
33
+ return;
34
+ }
35
+
36
+ const result = await apiFetch(creds, "POST", `/api/projects/${ws}/${proj}/repositories`, {
37
+ gitUrl,
38
+ role,
39
+ });
40
+ const outcome = result?.linkOutcome || (result?.repository ? "linked" : "unknown");
41
+ console.log(`Repo link outcome: ${outcome} (role=${role}).`);
42
+ }
43
+
44
+ main().catch((err) => {
45
+ console.error(`link-repo failed: ${err instanceof Error ? err.message : err}`);
46
+ process.exit(1);
47
+ });
@@ -0,0 +1,102 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Copy MISSING env keys from the repo's local .env into the project's Xevy
4
+ * deploy config (mainEnvVars). Adds only keys not already configured; never
5
+ * overwrites existing values. Reads the file in-process and prints ONLY key
6
+ * names — values are never logged or emitted.
7
+ *
8
+ * Usage:
9
+ * node xevy-sync-env.mjs --workspace <ws> --project <proj> [--env-path .env] [--cwd <dir>]
10
+ */
11
+ import fs from "node:fs";
12
+ import path from "node:path";
13
+ import { resolveCreds, parseArgs, apiFetch } from "./xevy-creds.mjs";
14
+
15
+ const PREVIEW_ENV_KEY_PATTERN = /^[A-Z][A-Z0-9_]*$/;
16
+ const PREVIEW_MAX_ENV_VARS = 100;
17
+
18
+ function parseDotEnv(content) {
19
+ const out = {};
20
+ for (const raw of content.split(/\r?\n/)) {
21
+ const line = raw.trim();
22
+ if (!line || line.startsWith("#")) continue;
23
+ const body = line.startsWith("export ") ? line.slice(7).trim() : line;
24
+ const eq = body.indexOf("=");
25
+ if (eq <= 0) continue;
26
+ const key = body.slice(0, eq).trim();
27
+ let value = body.slice(eq + 1).trim();
28
+ if (
29
+ value.length >= 2 &&
30
+ ((value.startsWith('"') && value.endsWith('"')) ||
31
+ (value.startsWith("'") && value.endsWith("'")))
32
+ ) {
33
+ value = value.slice(1, -1);
34
+ }
35
+ out[key] = value;
36
+ }
37
+ return out;
38
+ }
39
+
40
+ async function main() {
41
+ const args = parseArgs(process.argv.slice(2));
42
+ const ws = args.workspace || args.w;
43
+ const proj = args.project || args.p;
44
+ if (!ws || !proj) {
45
+ console.error("Usage: xevy-sync-env.mjs --workspace <ws> --project <proj> [--env-path .env] [--cwd <dir>]");
46
+ process.exit(2);
47
+ }
48
+ const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
49
+ const envRel = typeof args["env-path"] === "string" ? args["env-path"] : ".env";
50
+ const envFile = path.resolve(cwd, envRel);
51
+ if (!fs.existsSync(envFile)) {
52
+ console.log(`No env file at ${envRel} — nothing to sync.`);
53
+ return;
54
+ }
55
+
56
+ const creds = resolveCreds();
57
+ const parsed = parseDotEnv(fs.readFileSync(envFile, "utf8"));
58
+
59
+ const settingsResp = await apiFetch(creds, "GET", `/api/projects/${ws}/${proj}/preview/settings`);
60
+ const existing = Array.isArray(settingsResp?.settings?.mainEnvVars) ? settingsResp.settings.mainEnvVars : [];
61
+ const existingKeys = new Set(existing.map((e) => e?.key).filter((k) => typeof k === "string"));
62
+
63
+ const added = [];
64
+ const invalid = [];
65
+ let skipped = 0;
66
+ const toAdd = [];
67
+ for (const [key, value] of Object.entries(parsed)) {
68
+ if (!PREVIEW_ENV_KEY_PATTERN.test(key)) { invalid.push(key); continue; }
69
+ if (existingKeys.has(key)) { skipped++; continue; }
70
+ toAdd.push({ key, value });
71
+ added.push(key);
72
+ }
73
+
74
+ if (toAdd.length === 0) {
75
+ console.log(`No missing env vars to add (${skipped} already present${invalid.length ? `, ${invalid.length} invalid skipped` : ""}). Values were never read or displayed.`);
76
+ return;
77
+ }
78
+
79
+ const merged = [...existing, ...toAdd];
80
+ let dropped = [];
81
+ let finalMerged = merged;
82
+ if (merged.length > PREVIEW_MAX_ENV_VARS) {
83
+ finalMerged = merged.slice(0, PREVIEW_MAX_ENV_VARS);
84
+ dropped = merged.slice(PREVIEW_MAX_ENV_VARS).map((e) => e.key);
85
+ }
86
+ const addedFinal = added.filter((k) => !dropped.includes(k));
87
+
88
+ await apiFetch(creds, "PATCH", `/api/projects/${ws}/${proj}/preview/settings`, { mainEnvVars: finalMerged });
89
+
90
+ console.log(
91
+ `Added ${addedFinal.length} missing env var(s): ${addedFinal.join(", ") || "(none)"}. ` +
92
+ `${skipped} already present` +
93
+ (invalid.length ? `; skipped ${invalid.length} invalid: ${invalid.join(", ")}` : "") +
94
+ (dropped.length ? `; DROPPED ${dropped.length} over the ${PREVIEW_MAX_ENV_VARS}-var cap: ${dropped.join(", ")}` : "") +
95
+ `. Values were never read or displayed.`,
96
+ );
97
+ }
98
+
99
+ main().catch((err) => {
100
+ console.error(`sync-env failed: ${err instanceof Error ? err.message : err}`);
101
+ process.exit(1);
102
+ });
package/package.json ADDED
@@ -0,0 +1,33 @@
1
+ {
2
+ "name": "@xevy/skills",
3
+ "version": "0.1.18",
4
+ "description": "Install Xevy agent skills and MCP for Cursor, Claude Code, and 50+ agents — one command via npx skills + add-mcp.",
5
+ "type": "module",
6
+ "keywords": [
7
+ "xevy",
8
+ "agent-skills",
9
+ "skills",
10
+ "mcp",
11
+ "cursor",
12
+ "claude-code",
13
+ "sdlc",
14
+ "deploy"
15
+ ],
16
+ "homepage": "https://xevy.ai/docs/mcp",
17
+ "license": "UNLICENSED",
18
+ "bin": {
19
+ "xevy-skills": "bin/cli.mjs"
20
+ },
21
+ "files": [
22
+ ".claude-plugin",
23
+ "bin",
24
+ "skills",
25
+ "README.md"
26
+ ],
27
+ "engines": {
28
+ "node": ">=18"
29
+ },
30
+ "publishConfig": {
31
+ "access": "public"
32
+ }
33
+ }
@@ -0,0 +1,26 @@
1
+ ---
2
+ name: analyze
3
+ description: Analyze a task in the cloud — run the Xevy server agent's 'analyze' action, then review and correct the resulting Analysis section. Use /xevy:analyze-here to analyze locally instead.
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Grep Bash mcp__xevy__find_task mcp__xevy__update_task mcp__xevy__list_specs mcp__xevy__list_subtasks mcp__xevy__start_ai_action mcp__xevy__get_ai_execution mcp__xevy__list_ai_executions"
7
+ ---
8
+
9
+ # /xevy:analyze — analyze in the cloud (then review)
10
+
11
+ Cloud is the default engine: the Xevy server agent does the analysis; **you then review and correct it**. To analyze locally instead, use `/xevy:analyze-here`.
12
+
13
+ ## 1. Resolve the task
14
+ Resolve from `$ARGUMENTS` (`mcp__xevy__find_task` by code) or the in-context task. If ambiguous, ask which task.
15
+
16
+ ## 2. Run the cloud action
17
+ - `mcp__xevy__start_ai_action({ taskId, action: "analyze", stream: true })` — **always pass `stream: true`**. The call blocks and streams live per-step progress; report it as it arrives. Do **NOT** use fire-and-forget or `sleep`/manual poll loops — streaming is the default and is reliable.
18
+ - Only if this streamed call returns *before* a terminal status (genuine client disconnect — the run keeps going server-side) resume with `mcp__xevy__get_ai_execution` until `succeeded | failed | cancelled` (newest run via `list_ai_executions` if needed).
19
+ - If it fails, read the captured output, report the error, and offer to retry or fall back to `/xevy:analyze-here`.
20
+
21
+ ## 3. Review & correct (MANDATORY — do not finish until clean)
22
+ Act as the reviewer of the cloud result:
23
+ - Re-read the task (`find_task`) and any specs/subtasks. Re-read the Analysis section the agent wrote.
24
+ - Check it actually covers: Overview (plain-language, before/after, user impact), Technical Implementation (affected files, API/data/UI changes, assumptions, risks, verification), and a `storyPoints` estimate. Inspect the referenced code with Read/Grep to confirm the analysis is accurate, not hand-wavy.
25
+ - If anything is missing, wrong, or contradicts the code, **fix it** via `mcp__xevy__update_task` (append/repair the Analysis section — never delete the user's original request) and set `storyPoints` if absent.
26
+ - Report a PASS/PARTIAL verdict, what you corrected, and the task URL. Don't push the user to the next phase.
@@ -0,0 +1,30 @@
1
+ ---
2
+ name: analyze-here
3
+ description: Analyze a task locally in this Claude Code session — inspect the codebase, write the Analysis section + storyPoints via MCP, then self-review. Cloud equivalent is /xevy:analyze.
4
+ argument-hint: "[task]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read Grep Bash mcp__xevy__find_task mcp__xevy__update_task mcp__xevy__list_specs mcp__xevy__list_subtasks mcp__xevy__create_task_note mcp__xevy__list_task_decisions mcp__xevy__create_decision mcp__xevy__answer_decision"
7
+ ---
8
+
9
+ # /xevy:analyze-here — analyze locally (then review)
10
+
11
+ Run the analysis yourself in this session (no server agent). Mirror the Xevy analyze workflow.
12
+
13
+ ## 1. Resolve the task
14
+ Resolve from `$ARGUMENTS` or context (`mcp__xevy__find_task` / `find_task`). Read existing specs, subtasks, and notes.
15
+
16
+ ## 1b. Decisions gate (BEFORE the work)
17
+ Call `mcp__xevy__list_task_decisions`. If any decision is **open**, resolve them first — open decisions block AI actions. Present each open question to the user with **AskUserQuestion** (use its preset choices + explanations), record the answer with `mcp__xevy__answer_decision`, and fold the answers into the analysis. Never guess or bypass an open decision.
18
+
19
+ ## 2. Inspect the codebase
20
+ Read the relevant files (callers, callees, similar patterns). Identify whether the task involves UI changes; if so, study existing UI patterns and record a `UI/UX Flow` note (`create_task_note`). Base decisions on existing patterns — don't ask about every detail.
21
+
22
+ ## 3. Write the Analysis
23
+ Use `mcp__xevy__update_task` to append a `## Analysis` section (do NOT replace the user's original request):
24
+ - **Overview:** plain-language summary, before/after behaviour, user impact, key decisions.
25
+ - **Technical Implementation:** affected files/modules, API/data/UI changes, assumptions, risks, verification approach.
26
+ - Estimate `storyPoints` (1 trivial · 2 small · 3 medium · 5 large · 8 XL · 13 epic) and set it.
27
+ - **Open questions:** for a genuine ambiguity a human must resolve, don't bury it as an assumption — record it with `mcp__xevy__create_decision` (preset choices + explanation, optional follow-up per choice). It will gate the next step until answered. If the user is present, you may instead ask via **AskUserQuestion** and persist the result with `create_decision` + `answer_decision`.
28
+
29
+ ## 4. Review & correct (MANDATORY)
30
+ Re-read your Analysis against the actual code: is every claim accurate, are affected files real, are risks/ACs concrete? Fix any gap or inaccuracy before finishing. Then call `mcp__xevy__list_task_decisions` once more (post-check): if any decision is still open, surface it to the user. Report a PASS/PARTIAL verdict, what you corrected, any open decisions, and the task URL. Do not push the user to plan/execute next.
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: create-document
3
+ description: Create a document in the current Xevy project — a standalone note, spec write-up, RFC, runbook, or report. Documents are personal by default (private to you); you can share them with project members or publish a public, no-login link. Use when the user asks to "write up", "document", "draft a doc/RFC/runbook", or "make a shareable document".
4
+ argument-hint: "[title or topic] [--shared|--public]"
5
+ disable-model-invocation: true
6
+ allowed-tools: "Read mcp__xevy__get_current_user mcp__xevy__list_workspaces mcp__xevy__list_projects mcp__xevy__create_document mcp__xevy__update_document"
7
+ ---
8
+
9
+ # /xevy:create-document — create a project document
10
+
11
+ Create a document in the current Xevy project and return a link. Documents are project-scoped but **personal**: `private` to you by default, optionally `shared` with project members, or `public` (readable by anyone with the link, no login). Optional argument `$ARGUMENTS` may carry the title/topic and a `--shared` or `--public` flag.
12
+
13
+ ## 1. Resolve the project
14
+ - Prefer `.xevy/project.json` for `workspaceIdentifier` + `projectIdentifier`. If it's missing, call `mcp__xevy__list_projects` (and `mcp__xevy__list_workspaces` when there's more than one workspace) and ask the user which project to use when ambiguous.
15
+ - Confirm `mcp__xevy__get_current_user` succeeds so the document is owned by the right account.
16
+
17
+ ## 2. Decide title, body, and visibility
18
+ - **Title:** from `$ARGUMENTS` or the user's request. Keep it concise and descriptive. Ask if it's unclear.
19
+ - **Body (markdown):** draft `details` from the conversation/request. Don't fabricate facts — if the user only gave a title, create a short stub and say so. Use real markdown (headings, lists, code fences).
20
+ - **Visibility — default `private`:**
21
+ - `private` (default) — only the creator can see it.
22
+ - `shared` — visible to project members. Use when the user says "share with the team" or passes `--shared`.
23
+ - `public` — readable by anyone with the link, no login. Use ONLY when the user explicitly asks for a public/shareable link or passes `--public`. Confirm first: public documents need no authentication.
24
+
25
+ ## 3. Create it
26
+ - Call `mcp__xevy__create_document` with `workspaceIdentifier`, `projectIdentifier`, `title`, `details` (markdown), and `visibility`. Status defaults to `draft`.
27
+ - To change visibility later (e.g. publish an existing doc), use `mcp__xevy__update_document` with the new `visibility`.
28
+
29
+ ## 4. Report
30
+ - Give the user the document **title** and **visibility**.
31
+ - If it's **public**, share the no-login URL: `<XEVY_BASE>/d/<documentId>` (e.g. `https://xevy.ai/d/<id>`). Otherwise tell them it's in the project's Documents app.
32
+ - Never print secrets or paste private content into third-party tools.
@@ -0,0 +1,169 @@
1
+ ---
2
+ name: create-report
3
+ description: >-
4
+ Build a custom, shareable Xevy report from the project's connectors — mix
5
+ read-only SQL-connector queries, service connectors (SEO/analytics), and
6
+ markdown into ordered blocks (tables, charts, KPI cards, text), then create it,
7
+ run it once for evidence, and optionally schedule (hourly/daily/weekly/monthly)
8
+ and share a public no-login link. Use /xevy:create-report when the user
9
+ asks to "build/create a report", "put X on a dashboard", "chart Y from the
10
+ database", or "a weekly report of Z".
11
+ argument-hint: "[what the report should show]"
12
+ disable-model-invocation: true
13
+ allowed-tools: "Read mcp__xevy__get_current_user mcp__xevy__list_workspaces mcp__xevy__list_projects mcp__xevy__connector_list mcp__xevy__connector_get mcp__xevy__connector_describe mcp__xevy__connector_search mcp__xevy__connector_sql_schema mcp__xevy__connector_query mcp__xevy__reports_list_definitions mcp__xevy__reports_get_definition mcp__xevy__reports_create_definition mcp__xevy__reports_update_definition mcp__xevy__reports_run_definition mcp__xevy__reports_share_definition"
14
+ ---
15
+
16
+ # /xevy:create-report — build a custom report from connectors
17
+
18
+ Design a custom report out of **ordered blocks**, each pairing a **data source**
19
+ (a read-only SQL connector query, a service connector operation, or static
20
+ markdown) with a **presentation** (table, line/bar/pie chart, KPI cards, or
21
+ text). Create it, **run it once to prove it works**, and — only if asked —
22
+ schedule it and mint a public share link. `$ARGUMENTS` may carry what the report
23
+ should show.
24
+
25
+ **Discover the real data first. Never invent columns, tables, or connector
26
+ operations.** Introspect the SQL schema / describe the connector operation, then
27
+ build blocks against columns you have actually seen.
28
+
29
+ ## Workflow
30
+
31
+ ```
32
+ 1. Resolve → workspace + project
33
+ 2. Discover → which connectors exist, and what data they expose
34
+ 3. Design → map the request to ordered blocks (source + presentation)
35
+ 4. Create → reports_create_definition (blocks validated server-side)
36
+ 5. Run → reports_run_definition once; verify the snapshot (evidence)
37
+ 6. Deliver → report the result; schedule / share only if the user asked
38
+ ```
39
+
40
+ ### 1. Resolve the project
41
+
42
+ - Prefer `.xevy/project.json` for `workspaceIdentifier` + `projectIdentifier`.
43
+ If missing, call `list_projects` (and `list_workspaces` when there's more than
44
+ one) and ask which project when ambiguous.
45
+ - `get_current_user` should succeed so the report is owned by the right account.
46
+
47
+ ### 2. Discover the connectors and their data
48
+
49
+ A report block's data comes from a connector, so find out what's available
50
+ before designing anything.
51
+
52
+ - **SQL connectors** (databases): `connector_list` with `serviceName: "sql"`.
53
+ Each has an `id` (the block's `connectorId`) and a name — pick the one for the
54
+ environment/database the user means. **If two SQL connectors could match (e.g.
55
+ prod vs staging) and it's not obvious, ask** — don't guess which database.
56
+ - Learn its structure: `connector_sql_schema { connectorId }` →
57
+ `{ schemas: [{ name, tables: [{ name, columns: [{ name, dataType }] }] }] }`.
58
+ - Author your `SELECT`/`WITH` against those exact tables/columns. To sanity-
59
+ check a query before baking it into a block, run it with
60
+ `connector_query { connectorId, sql, maxRows }` (read-only enforced).
61
+ - **Service connectors** (SEO/analytics, e.g. `dataforseo`):
62
+ `connector_list` (no filter) shows what's configured. Then
63
+ `connector_get { serviceName }` for its operation index, and
64
+ `connector_describe { serviceName, operation }` for one operation's params.
65
+ `connector_search { query }` finds operations across services.
66
+ - If the project has **no connector** for what the user wants, say so and point
67
+ them to **Settings → Connectors** to add one; don't fabricate a data source.
68
+
69
+ ### 3. Design the blocks
70
+
71
+ A report is `blocks: [...]` — an ordered array (max **20**). Each block is:
72
+
73
+ ```jsonc
74
+ {
75
+ "id": "unique-slug", // 1–64 chars, unique within the report
76
+ "title": "Human title", // shown above the block (optional)
77
+ "source": { … }, // one of the three source shapes below
78
+ "presentation": "table", // table | line_chart | bar_chart | pie_chart | cards | text
79
+ "options": { … } // presentation hints (optional) — see below
80
+ }
81
+ ```
82
+
83
+ **Sources** (`source.type`):
84
+
85
+ | type | shape | use for |
86
+ |---|---|---|
87
+ | `sql` | `{ "type":"sql", "connectorId":"<uuid>", "query":"SELECT …", "maxRows": 1000 }` | one read-only query against a SQL connector |
88
+ | `connector` | `{ "type":"connector", "serviceName":"dataforseo", "operation":"…", "params": { … } }` | one service-connector operation |
89
+ | `text` | `{ "type":"text", "markdown":"## Notes\n…" }` | a static narrative / heading block |
90
+
91
+ **Presentation + `options`** (options are optional hints; the renderer copes
92
+ without them, but they make charts/cards read correctly):
93
+
94
+ | presentation | key `options` | notes |
95
+ |---|---|---|
96
+ | `table` | `columns` (subset/order of column names) | default for any tabular source |
97
+ | `line_chart` / `bar_chart` | `xKey` (category axis column), `yKeys` (one or more numeric series), `format` | source must return rows with those columns |
98
+ | `pie_chart` | `labelKey`, `valueKey` | one slice per row |
99
+ | `cards` | `valueKey`, `labelKey`, `format` | KPI cards from a small result |
100
+ | `text` | — | requires a `text` source |
101
+
102
+ `format` is one of `number | currency | percent | text`.
103
+
104
+ **Validation rules the server enforces** (build to them or the create fails):
105
+ - Block `id`s must be **unique**; max 20 blocks; SQL `query` ≤ 100k chars,
106
+ `maxRows` 1–10 000; text `markdown` ≤ 20k chars.
107
+ - A `text` **presentation** requires a `text` **source**, and a `text` source
108
+ can only use the `text` presentation. Charts/tables/cards need a data source
109
+ (`sql` or `connector`).
110
+ - Make chart `xKey`/`yKeys`/`valueKey`/`labelKey` match **actual result columns**
111
+ (from `connector_sql_schema` or a `connector_query` dry run). SQL: alias
112
+ columns explicitly (`SELECT count(*) AS orders`) so the keys are stable.
113
+
114
+ See [examples.md](examples.md) for complete, copy-ready block JSON.
115
+
116
+ ### 4. Create
117
+
118
+ Call `reports_create_definition` with `workspaceIdentifier`, `projectIdentifier`,
119
+ `name`, optional `description`, and `blocks`. Leave `cadence` off (default) unless
120
+ the user asked for a schedule. Set `timezone` (IANA, e.g. `Europe/London`) when a
121
+ daily/weekly/monthly cadence needs a sensible anchor.
122
+
123
+ ### 5. Run it once — evidence, not assumption
124
+
125
+ Immediately call `reports_run_definition { id }`. Inspect the returned run's
126
+ `snapshot.blocks`:
127
+ - `status: "ok"` → every block ran. `partial` → some blocks failed;
128
+ `error` → all failed.
129
+ - Each block is `{ ok: true, data, … }` or `{ ok: false, error }`. If any block
130
+ is `ok:false`, **fix its source** (usually a bad column/table or wrong
131
+ connector) and `reports_update_definition` the blocks, then run again. Do not
132
+ report success while a block is failing.
133
+
134
+ Never paste raw result rows that may contain PII into chat — report block
135
+ `ok/error` and counts, not customer data.
136
+
137
+ ### 6. Deliver
138
+
139
+ - Give the report **name** and a link to the Reports app:
140
+ `<XEVY_BASE>/<workspace>/<project>/reports` (e.g.
141
+ `https://xevy.ai/<ws>/<proj>/reports`).
142
+ - **Schedule only if asked:** `reports_update_definition { cadence, timezone }`
143
+ (`hourly|daily|weekly|monthly`). Auto-runs reuse a short per-cadence cache.
144
+ - **Public link only if the user explicitly asks:** `reports_share_definition
145
+ { action: "share" }` → returns `<XEVY_BASE>/r/<token>`. Confirm first — the
146
+ link needs **no login** and serves the latest successful run's frozen snapshot.
147
+ Revoke with `action: "revoke"`.
148
+
149
+ ## Hard rules
150
+
151
+ 1. **Real data only** — introspect (`connector_sql_schema`) or describe
152
+ (`connector_describe`) before writing a block; never invent columns, tables,
153
+ or operations.
154
+ 2. **Right connector** — match the SQL connector to the environment the user
155
+ means; if prod vs staging is ambiguous, ask.
156
+ 3. **Read-only** — SQL blocks are `SELECT`/`WITH` only (the gateway rejects
157
+ writes); use them for reporting, never to mutate.
158
+ 4. **Prove it ran** — always `reports_run_definition` and confirm the snapshot is
159
+ `ok` (fix failing blocks) before telling the user it's done.
160
+ 5. **No secrets / no PII in chat** — connectors keep credentials in the gateway;
161
+ don't echo credential values or dump result rows that may contain personal data.
162
+ 6. **Share is opt-in** — never mint a public `/r/<token>` link unless the user
163
+ explicitly asks; confirm it's no-login first.
164
+
165
+ ## Examples
166
+
167
+ See [examples.md](examples.md) for full block JSON (SQL table, SQL time-series
168
+ chart, KPI cards, an SEO connector block, and a text narrative) and a complete
169
+ `reports_create_definition` payload.
@@ -0,0 +1,134 @@
1
+ # create-report examples
2
+
3
+ Copy-ready block JSON. Replace `connectorId`, table/column names, and
4
+ `serviceName`/`operation` with the ones you actually discovered via
5
+ `connector_list` + `connector_sql_schema` / `connector_describe`. Every chart
6
+ key (`xKey`, `yKeys`, `valueKey`, `labelKey`) must match a real result column —
7
+ alias SQL columns so the keys are stable.
8
+
9
+ ## A. SQL — table block
10
+
11
+ ```jsonc
12
+ {
13
+ "id": "recent-orders",
14
+ "title": "Recent orders",
15
+ "source": {
16
+ "type": "sql",
17
+ "connectorId": "b7c1…-uuid-from-connector_list",
18
+ "query": "SELECT id, status, total_amount, created_at FROM orders ORDER BY created_at DESC LIMIT 50",
19
+ "maxRows": 50
20
+ },
21
+ "presentation": "table",
22
+ "options": { "columns": ["id", "status", "total_amount", "created_at"] }
23
+ }
24
+ ```
25
+
26
+ ## B. SQL — time-series line chart
27
+
28
+ Return one row per time bucket; `xKey` is the bucket, `yKeys` the numeric series.
29
+
30
+ ```jsonc
31
+ {
32
+ "id": "orders-per-day",
33
+ "title": "Orders per day (last 30 days)",
34
+ "source": {
35
+ "type": "sql",
36
+ "connectorId": "b7c1…-uuid",
37
+ "query": "SELECT date_trunc('day', created_at)::date AS day, count(*) AS orders, sum(total_amount) AS revenue FROM orders WHERE created_at > now() - interval '30 days' GROUP BY 1 ORDER BY 1"
38
+ },
39
+ "presentation": "line_chart",
40
+ "options": { "xKey": "day", "yKeys": ["orders", "revenue"], "format": "number" }
41
+ }
42
+ ```
43
+
44
+ ## C. SQL — KPI cards
45
+
46
+ A single row of aggregates renders as cards.
47
+
48
+ ```jsonc
49
+ {
50
+ "id": "kpis",
51
+ "title": "This month",
52
+ "source": {
53
+ "type": "sql",
54
+ "connectorId": "b7c1…-uuid",
55
+ "query": "SELECT count(*) AS orders, sum(total_amount) AS revenue, count(DISTINCT customer_id) AS customers FROM orders WHERE created_at >= date_trunc('month', now())"
56
+ },
57
+ "presentation": "cards",
58
+ "options": { "format": "number" }
59
+ }
60
+ ```
61
+
62
+ ## D. SQL — pie chart (breakdown)
63
+
64
+ ```jsonc
65
+ {
66
+ "id": "orders-by-status",
67
+ "title": "Orders by status",
68
+ "source": {
69
+ "type": "sql",
70
+ "connectorId": "b7c1…-uuid",
71
+ "query": "SELECT status AS label, count(*) AS n FROM orders GROUP BY status ORDER BY n DESC"
72
+ },
73
+ "presentation": "pie_chart",
74
+ "options": { "labelKey": "label", "valueKey": "n" }
75
+ }
76
+ ```
77
+
78
+ ## E. Service connector (SEO / analytics)
79
+
80
+ Discover `serviceName`/`operation`/params with `connector_get` +
81
+ `connector_describe` first. The runner normalises the response to
82
+ `{ columns, rows }` where it can.
83
+
84
+ ```jsonc
85
+ {
86
+ "id": "backlinks",
87
+ "title": "Backlink summary",
88
+ "source": {
89
+ "type": "connector",
90
+ "serviceName": "dataforseo",
91
+ "operation": "backlinks_summary",
92
+ "params": { "target": "example.com" }
93
+ },
94
+ "presentation": "table"
95
+ }
96
+ ```
97
+
98
+ ## F. Text / narrative block
99
+
100
+ A `text` source must use the `text` presentation (and vice-versa). Good for a
101
+ report intro or section headers between data blocks.
102
+
103
+ ```jsonc
104
+ {
105
+ "id": "intro",
106
+ "title": "",
107
+ "source": { "type": "text", "markdown": "## Weekly operations\nGenerated automatically from the production database." },
108
+ "presentation": "text"
109
+ }
110
+ ```
111
+
112
+ ## Full create payload
113
+
114
+ `reports_create_definition` assembles the blocks in order. Leave `cadence` off
115
+ unless the user asked to schedule it.
116
+
117
+ ```jsonc
118
+ {
119
+ "workspaceIdentifier": "acme",
120
+ "projectIdentifier": "storefront",
121
+ "name": "Orders overview",
122
+ "description": "Daily orders, revenue and status mix from the production DB.",
123
+ "blocks": [
124
+ { "id": "intro", "source": { "type": "text", "markdown": "## Orders overview" }, "presentation": "text" },
125
+ { "id": "kpis", "title": "This month", "source": { "type": "sql", "connectorId": "b7c1…-uuid", "query": "SELECT count(*) AS orders, sum(total_amount) AS revenue FROM orders WHERE created_at >= date_trunc('month', now())" }, "presentation": "cards", "options": { "format": "number" } },
126
+ { "id": "orders-per-day", "title": "Orders per day", "source": { "type": "sql", "connectorId": "b7c1…-uuid", "query": "SELECT date_trunc('day', created_at)::date AS day, count(*) AS orders FROM orders WHERE created_at > now() - interval '30 days' GROUP BY 1 ORDER BY 1" }, "presentation": "line_chart", "options": { "xKey": "day", "yKeys": ["orders"] } }
127
+ ],
128
+ "cadence": "off",
129
+ "timezone": "Europe/London"
130
+ }
131
+ ```
132
+
133
+ After creating, call `reports_run_definition { id }` and confirm every
134
+ `snapshot.blocks[*].ok` is `true` before reporting success.