skillwiki 0.10.105 → 0.10.107
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.
- package/dist/{chunk-XYXTV2YD.js → chunk-DTTKCCQ4.js} +2 -2
- package/dist/{chunk-QM64LUEY.js → chunk-GJC2CI3W.js} +8 -1
- package/dist/{chunk-KDH352MC.js → chunk-HMHMCPCE.js} +1 -1
- package/dist/{chunk-F5GFUYPF.js → chunk-JCDAEZVD.js} +1 -1
- package/dist/{chunk-PVIOU7BN.js → chunk-PGD3J2GE.js} +3 -3
- package/dist/{chunk-H42EY6E7.js → chunk-QU2IXZRN.js} +2 -2
- package/dist/{chunk-2BPOEEMW.js → chunk-Z4NCF6K6.js} +7 -7
- package/dist/cli.js +30 -14
- package/dist/{index-projection-6OHDINHT.js → index-projection-ESBJOBS7.js} +3 -3
- package/dist/{managed-write-preflight-ATDFVLJV.js → managed-write-preflight-AYD3CJYD.js} +4 -4
- package/dist/skillwiki-mcp.js +7 -7
- package/dist/sources-QTQSZMST.js +9 -0
- package/package.json +1 -1
- package/skills/.claude-plugin/plugin.json +1 -1
- package/skills/.codex-plugin/plugin.json +1 -1
- package/skills/.cursor-plugin/plugin.json +1 -1
- package/skills/package.json +1 -1
- package/skills/scripts/check_readiness.py +14 -0
- package/skills/skills/skillwiki-connect/SKILL.md +1 -0
- package/skills/skills/skillwiki-mcp/SKILL.md +5 -4
- package/skills/skills/using-skillwiki/activation.md +5 -5
- package/skills/skills/wiki-query/SKILL.md +1 -0
- package/skills/skillwiki-connect/SKILL.md +1 -0
- package/skills/skillwiki-mcp/SKILL.md +5 -4
- package/skills/using-skillwiki/activation.md +5 -5
- package/skills/wiki-query/SKILL.md +1 -0
- package/templates/SCHEMA.md +6 -0
- package/dist/sources-OSGKH6KN.js +0 -9
|
@@ -3,11 +3,11 @@ import {
|
|
|
3
3
|
ROOT_INDEX_SECTION_ORDER,
|
|
4
4
|
atomicWriteText,
|
|
5
5
|
buildRootIndexUniverse
|
|
6
|
-
} from "./chunk-
|
|
6
|
+
} from "./chunk-HMHMCPCE.js";
|
|
7
7
|
import {
|
|
8
8
|
err,
|
|
9
9
|
ok
|
|
10
|
-
} from "./chunk-
|
|
10
|
+
} from "./chunk-GJC2CI3W.js";
|
|
11
11
|
|
|
12
12
|
// src/utils/index-projection.ts
|
|
13
13
|
import { readFile } from "fs/promises";
|
|
@@ -161,6 +161,7 @@ var TypedKnowledgeSchema = z.object({
|
|
|
161
161
|
}
|
|
162
162
|
});
|
|
163
163
|
var sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
|
|
164
|
+
var identityToken = z.string().min(1).max(128).regex(/^[a-zA-Z0-9_.-]+$/, "must be bounded alphanumeric token with _.-");
|
|
164
165
|
var RawSourceSchema = z.object({
|
|
165
166
|
title: z.string().min(1).optional(),
|
|
166
167
|
source_url: z.string().nullable(),
|
|
@@ -170,7 +171,10 @@ var RawSourceSchema = z.object({
|
|
|
170
171
|
sha256: sha256Hex.optional(),
|
|
171
172
|
project: wikilink.optional(),
|
|
172
173
|
work_item: wikilink.optional(),
|
|
173
|
-
kind: z.enum(["postmortem", "session-log", "meeting-notes", "other", "idea", "bug", "task", "note"]).optional()
|
|
174
|
+
kind: z.enum(["postmortem", "session-log", "meeting-notes", "other", "idea", "bug", "task", "note"]).optional(),
|
|
175
|
+
host: identityToken.optional(),
|
|
176
|
+
agent_role: identityToken.optional(),
|
|
177
|
+
agent_id: identityToken.optional()
|
|
174
178
|
}).superRefine((v, ctx) => {
|
|
175
179
|
if (v.work_item !== void 0 && (v.project === void 0 || v.kind === void 0)) {
|
|
176
180
|
ctx.addIssue({ code: z.ZodIssueCode.custom, message: "project and kind are required when work_item is set" });
|
|
@@ -201,6 +205,9 @@ var WorkItemSchema = z.object({
|
|
|
201
205
|
parent: wikilink.optional(),
|
|
202
206
|
related: z.array(wikilink).optional(),
|
|
203
207
|
sources: z.array(z.string()).optional(),
|
|
208
|
+
host: identityToken.optional(),
|
|
209
|
+
agent_role: identityToken.optional(),
|
|
210
|
+
agent_id: identityToken.optional(),
|
|
204
211
|
post_release_verification: PostReleaseVerificationSchema.optional()
|
|
205
212
|
}).superRefine((v, ctx) => {
|
|
206
213
|
if (v.status === "completed" && !v.completed) {
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
import {
|
|
3
3
|
atomicWriteText,
|
|
4
4
|
buildRootIndexUniverse
|
|
5
|
-
} from "./chunk-
|
|
5
|
+
} from "./chunk-HMHMCPCE.js";
|
|
6
6
|
import {
|
|
7
7
|
authorizeRawOperation,
|
|
8
8
|
buildSourceReferenceIndex,
|
|
@@ -22,7 +22,7 @@ import {
|
|
|
22
22
|
resolveExistingRegularFileInsideVault,
|
|
23
23
|
stripFencedBlocks,
|
|
24
24
|
writeLogEvent
|
|
25
|
-
} from "./chunk-
|
|
25
|
+
} from "./chunk-JCDAEZVD.js";
|
|
26
26
|
import {
|
|
27
27
|
ExitCode,
|
|
28
28
|
FleetManifestSchema,
|
|
@@ -41,7 +41,7 @@ import {
|
|
|
41
41
|
scanVault,
|
|
42
42
|
splitFrontmatter,
|
|
43
43
|
vaultIoConcurrency
|
|
44
|
-
} from "./chunk-
|
|
44
|
+
} from "./chunk-GJC2CI3W.js";
|
|
45
45
|
|
|
46
46
|
// src/utils/managed-write-preflight.ts
|
|
47
47
|
import { existsSync as existsSync11 } from "fs";
|
|
@@ -8,7 +8,7 @@ import {
|
|
|
8
8
|
readLogEvents,
|
|
9
9
|
resolveExistingRegularFileInsideVault,
|
|
10
10
|
writeLogEvent
|
|
11
|
-
} from "./chunk-
|
|
11
|
+
} from "./chunk-JCDAEZVD.js";
|
|
12
12
|
import {
|
|
13
13
|
ExitCode,
|
|
14
14
|
RawSourceSchema,
|
|
@@ -19,7 +19,7 @@ import {
|
|
|
19
19
|
scanSensitiveContent,
|
|
20
20
|
scanVault,
|
|
21
21
|
splitFrontmatter
|
|
22
|
-
} from "./chunk-
|
|
22
|
+
} from "./chunk-GJC2CI3W.js";
|
|
23
23
|
|
|
24
24
|
// src/commands/sources.ts
|
|
25
25
|
import { readFile as readFile4 } from "fs/promises";
|
|
@@ -6,7 +6,7 @@ import {
|
|
|
6
6
|
import {
|
|
7
7
|
renderRootIndex,
|
|
8
8
|
writeRootIndexProjection
|
|
9
|
-
} from "./chunk-
|
|
9
|
+
} from "./chunk-DTTKCCQ4.js";
|
|
10
10
|
import {
|
|
11
11
|
CONFIG_KEYS,
|
|
12
12
|
VAULT_HYGIENE_GENERATED_COMMIT_PATHS,
|
|
@@ -40,11 +40,11 @@ import {
|
|
|
40
40
|
snapshotterAliasForLocalHost,
|
|
41
41
|
toUndirectedWeighted,
|
|
42
42
|
writeDotenv
|
|
43
|
-
} from "./chunk-
|
|
43
|
+
} from "./chunk-PGD3J2GE.js";
|
|
44
44
|
import {
|
|
45
45
|
atomicWriteText,
|
|
46
46
|
prepareTypedPage
|
|
47
|
-
} from "./chunk-
|
|
47
|
+
} from "./chunk-HMHMCPCE.js";
|
|
48
48
|
import {
|
|
49
49
|
applySourceCompileClaim,
|
|
50
50
|
applySourceCompilePublished,
|
|
@@ -57,11 +57,11 @@ import {
|
|
|
57
57
|
planSourceCompileRelease,
|
|
58
58
|
planSourceReview,
|
|
59
59
|
runSourcesPending
|
|
60
|
-
} from "./chunk-
|
|
60
|
+
} from "./chunk-QU2IXZRN.js";
|
|
61
61
|
import {
|
|
62
62
|
eventPathFor,
|
|
63
63
|
writeLogEvent
|
|
64
|
-
} from "./chunk-
|
|
64
|
+
} from "./chunk-JCDAEZVD.js";
|
|
65
65
|
import {
|
|
66
66
|
CompoundSchema,
|
|
67
67
|
ExitCode,
|
|
@@ -82,7 +82,7 @@ import {
|
|
|
82
82
|
scanVault,
|
|
83
83
|
splitFrontmatter,
|
|
84
84
|
systemdPropertyFor
|
|
85
|
-
} from "./chunk-
|
|
85
|
+
} from "./chunk-GJC2CI3W.js";
|
|
86
86
|
|
|
87
87
|
// src/commands/log-append.ts
|
|
88
88
|
import { readFile, stat } from "fs/promises";
|
|
@@ -6606,7 +6606,7 @@ async function runQuery(input) {
|
|
|
6606
6606
|
}
|
|
6607
6607
|
let pendingSources;
|
|
6608
6608
|
if (input.includePending) {
|
|
6609
|
-
const { runSourcesPending: runSourcesPending2 } = await import("./sources-
|
|
6609
|
+
const { runSourcesPending: runSourcesPending2 } = await import("./sources-QTQSZMST.js");
|
|
6610
6610
|
const pending = await runSourcesPending2({
|
|
6611
6611
|
vault: input.vault,
|
|
6612
6612
|
match: input.text,
|
package/dist/cli.js
CHANGED
|
@@ -63,7 +63,7 @@ import {
|
|
|
63
63
|
snapshotterHealthChecks,
|
|
64
64
|
upsertIndexEntry,
|
|
65
65
|
vectorIndexStatus
|
|
66
|
-
} from "./chunk-
|
|
66
|
+
} from "./chunk-Z4NCF6K6.js";
|
|
67
67
|
import {
|
|
68
68
|
normalizeDistTag,
|
|
69
69
|
readCache,
|
|
@@ -76,7 +76,7 @@ import {
|
|
|
76
76
|
UNMANAGED_START,
|
|
77
77
|
renderRootIndex,
|
|
78
78
|
writeRootIndexProjection
|
|
79
|
-
} from "./chunk-
|
|
79
|
+
} from "./chunk-DTTKCCQ4.js";
|
|
80
80
|
import {
|
|
81
81
|
FLEET_REL_PATH,
|
|
82
82
|
REDACTED_MALFORMED_REFERENCE,
|
|
@@ -168,12 +168,12 @@ import {
|
|
|
168
168
|
supersedeStaleReviewRequiredJournals,
|
|
169
169
|
taxonomyCommentForPage,
|
|
170
170
|
writeDotenv
|
|
171
|
-
} from "./chunk-
|
|
171
|
+
} from "./chunk-PGD3J2GE.js";
|
|
172
172
|
import {
|
|
173
173
|
assertTargetInsideVault,
|
|
174
174
|
atomicWriteText,
|
|
175
175
|
prepareTypedPage
|
|
176
|
-
} from "./chunk-
|
|
176
|
+
} from "./chunk-HMHMCPCE.js";
|
|
177
177
|
import {
|
|
178
178
|
applySourceDisposition,
|
|
179
179
|
decodeSourceActionApproval,
|
|
@@ -181,7 +181,7 @@ import {
|
|
|
181
181
|
inventorySources,
|
|
182
182
|
planSourceDisposition,
|
|
183
183
|
runSourcesPending
|
|
184
|
-
} from "./chunk-
|
|
184
|
+
} from "./chunk-QU2IXZRN.js";
|
|
185
185
|
import {
|
|
186
186
|
authorizeRawOperation,
|
|
187
187
|
buildSourceReferenceIndex,
|
|
@@ -198,7 +198,7 @@ import {
|
|
|
198
198
|
resolveExistingRegularFileInsideVault,
|
|
199
199
|
validateLogEvent,
|
|
200
200
|
writeLogEvent
|
|
201
|
-
} from "./chunk-
|
|
201
|
+
} from "./chunk-JCDAEZVD.js";
|
|
202
202
|
import {
|
|
203
203
|
ExitCode,
|
|
204
204
|
MetaSchema,
|
|
@@ -219,7 +219,7 @@ import {
|
|
|
219
219
|
scanVault,
|
|
220
220
|
splitFrontmatter,
|
|
221
221
|
vaultIoConcurrency
|
|
222
|
-
} from "./chunk-
|
|
222
|
+
} from "./chunk-GJC2CI3W.js";
|
|
223
223
|
|
|
224
224
|
// src/cli.ts
|
|
225
225
|
import { join as join45 } from "path";
|
|
@@ -4117,7 +4117,7 @@ ${fmRewritten}
|
|
|
4117
4117
|
}
|
|
4118
4118
|
let indexUpdated = false;
|
|
4119
4119
|
if (!isRaw) {
|
|
4120
|
-
const { renderRootIndex: renderRootIndex2, writeRootIndexProjection: writeRootIndexProjection2 } = await import("./index-projection-
|
|
4120
|
+
const { renderRootIndex: renderRootIndex2, writeRootIndexProjection: writeRootIndexProjection2 } = await import("./index-projection-ESBJOBS7.js");
|
|
4121
4121
|
const before = await readFile8(join20(input.vault, "index.md"), "utf8").catch(() => "");
|
|
4122
4122
|
const fullTarget = relPath.replace(/\.md$/, "");
|
|
4123
4123
|
const bare = fullTarget.split("/").pop() ?? fullTarget;
|
|
@@ -4240,7 +4240,7 @@ async function runRemove(input) {
|
|
|
4240
4240
|
if (relPath.endsWith(".md") && !relPath.startsWith("raw/")) {
|
|
4241
4241
|
const { readFile: readFile24 } = await import("fs/promises");
|
|
4242
4242
|
const { join: pathJoin } = await import("path");
|
|
4243
|
-
const { renderRootIndex: renderRootIndex2, writeRootIndexProjection: writeRootIndexProjection2 } = await import("./index-projection-
|
|
4243
|
+
const { renderRootIndex: renderRootIndex2, writeRootIndexProjection: writeRootIndexProjection2 } = await import("./index-projection-ESBJOBS7.js");
|
|
4244
4244
|
const before = await readFile24(pathJoin(input.vault, "index.md"), "utf8").catch(() => "");
|
|
4245
4245
|
const fullTarget = relPath.replace(/\.md$/, "");
|
|
4246
4246
|
const bare = fullTarget.split("/").pop() ?? fullTarget;
|
|
@@ -9856,7 +9856,11 @@ function localRecord(p, githubOid) {
|
|
|
9856
9856
|
}
|
|
9857
9857
|
function liveDriftRecord(p) {
|
|
9858
9858
|
if (!p || p.unknown || p.content === void 0 && p.ledger === void 0) {
|
|
9859
|
-
return {
|
|
9859
|
+
return {
|
|
9860
|
+
state: "unknown",
|
|
9861
|
+
reason_code: p?.reason_code ?? "live_drift_unmeasured",
|
|
9862
|
+
detail: p?.detail ?? "live drift unmeasured"
|
|
9863
|
+
};
|
|
9860
9864
|
}
|
|
9861
9865
|
const content = p.content ?? 0;
|
|
9862
9866
|
const ledger = p.ledger ?? 0;
|
|
@@ -9872,6 +9876,7 @@ function formatLiveDrift(rec) {
|
|
|
9872
9876
|
const parts = [`live_drift: ${rec.state}`];
|
|
9873
9877
|
if (rec.content !== void 0) parts.push(`content=${rec.content}`);
|
|
9874
9878
|
if (rec.ledger !== void 0) parts.push(`ledger=${rec.ledger}`);
|
|
9879
|
+
if (rec.reason_code) parts.push(`reason_code=${rec.reason_code}`);
|
|
9875
9880
|
if (rec.detail) parts.push(rec.detail);
|
|
9876
9881
|
return parts.join(" ");
|
|
9877
9882
|
}
|
|
@@ -9929,6 +9934,9 @@ function defaultCopyStatusDeps(input) {
|
|
|
9929
9934
|
const nestedWithLive = selection.path !== void 0 && (pathsAreNested(selection.path, input.vault) || pathsAreNested(input.vault, selection.path));
|
|
9930
9935
|
const configuredProjection = sameAsLive || nestedWithLive ? void 0 : selection.path;
|
|
9931
9936
|
const projectionProblem = selection.invalidDetail ?? (sameAsLive ? "configured fetch projection must be distinct from live vault" : nestedWithLive ? "configured fetch projection and live vault must not be nested" : void 0);
|
|
9937
|
+
let unmeasuredLiveDriftReason = "fetch_projection_not_configured";
|
|
9938
|
+
if (selection.invalidDetail) unmeasuredLiveDriftReason = "fetch_projection_invalid";
|
|
9939
|
+
else if (projectionProblem) unmeasuredLiveDriftReason = "fetch_projection_conflicts_with_live_vault";
|
|
9932
9940
|
const gitVault = input.vault;
|
|
9933
9941
|
const projectionWarning = selection.configured ? `configured fetch projection ignored for Git status; using live vault${projectionProblem ? ` (${projectionProblem})` : ""}` : void 0;
|
|
9934
9942
|
const invalidProjectionDetail = projectionProblem ?? "configured fetch projection is not a git repository";
|
|
@@ -9999,10 +10007,18 @@ function defaultCopyStatusDeps(input) {
|
|
|
9999
10007
|
},
|
|
10000
10008
|
probeLiveDrift() {
|
|
10001
10009
|
if (!configuredProjection) {
|
|
10002
|
-
return {
|
|
10010
|
+
return {
|
|
10011
|
+
unknown: true,
|
|
10012
|
+
reason_code: unmeasuredLiveDriftReason,
|
|
10013
|
+
detail: projectionProblem ?? "live drift requires a configured fetch projection"
|
|
10014
|
+
};
|
|
10003
10015
|
}
|
|
10004
10016
|
if (!existsSync13(join39(configuredProjection, ".git"))) {
|
|
10005
|
-
return {
|
|
10017
|
+
return {
|
|
10018
|
+
unknown: true,
|
|
10019
|
+
reason_code: "fetch_projection_invalid",
|
|
10020
|
+
detail: invalidProjectionDetail
|
|
10021
|
+
};
|
|
10006
10022
|
}
|
|
10007
10023
|
return measureAuthoritativeLiveDrift(input.vault, configuredProjection);
|
|
10008
10024
|
}
|
|
@@ -11207,7 +11223,7 @@ async function emitManagedVaultWrite(vault, command, mutate, opts) {
|
|
|
11207
11223
|
if (dirty) {
|
|
11208
11224
|
return emit(dirty, void 0, { postCommit: false });
|
|
11209
11225
|
}
|
|
11210
|
-
const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-
|
|
11226
|
+
const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-AYD3CJYD.js");
|
|
11211
11227
|
const run = await runManagedWriteTransaction2({
|
|
11212
11228
|
vault,
|
|
11213
11229
|
command,
|
|
@@ -12302,7 +12318,7 @@ memoryCmd.command("index [vault]").description("build the derived project memory
|
|
|
12302
12318
|
check: false,
|
|
12303
12319
|
ifStale: !!opts.ifStale
|
|
12304
12320
|
}),
|
|
12305
|
-
{ postCommit:
|
|
12321
|
+
{ postCommit: false }
|
|
12306
12322
|
);
|
|
12307
12323
|
});
|
|
12308
12324
|
memoryCmd.command("recall [vault]").description("recall bounded source summaries for a memory topic").requiredOption("--project <slug>", "project slug").requiredOption("--topic <slug>", "memory topic slug").option("--scope <scope>", "memory scope: project, global, cross-agent, or all").option("--limit <n>", "maximum sources to return", (s) => parseInt(s, 10), 10).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
|
|
@@ -4,9 +4,9 @@ import {
|
|
|
4
4
|
UNMANAGED_START,
|
|
5
5
|
renderRootIndex,
|
|
6
6
|
writeRootIndexProjection
|
|
7
|
-
} from "./chunk-
|
|
8
|
-
import "./chunk-
|
|
9
|
-
import "./chunk-
|
|
7
|
+
} from "./chunk-DTTKCCQ4.js";
|
|
8
|
+
import "./chunk-HMHMCPCE.js";
|
|
9
|
+
import "./chunk-GJC2CI3W.js";
|
|
10
10
|
export {
|
|
11
11
|
UNMANAGED_END,
|
|
12
12
|
UNMANAGED_START,
|
|
@@ -6,10 +6,10 @@ import {
|
|
|
6
6
|
runManagedWritePeerGate,
|
|
7
7
|
runManagedWritePreflight,
|
|
8
8
|
runManagedWriteTransaction
|
|
9
|
-
} from "./chunk-
|
|
10
|
-
import "./chunk-
|
|
11
|
-
import "./chunk-
|
|
12
|
-
import "./chunk-
|
|
9
|
+
} from "./chunk-PGD3J2GE.js";
|
|
10
|
+
import "./chunk-HMHMCPCE.js";
|
|
11
|
+
import "./chunk-JCDAEZVD.js";
|
|
12
|
+
import "./chunk-GJC2CI3W.js";
|
|
13
13
|
export {
|
|
14
14
|
DEFAULT_MANAGED_WRITE_WAIT_MS,
|
|
15
15
|
MANAGED_WRITE_POLL_INTERVAL_MS,
|
package/dist/skillwiki-mcp.js
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import {
|
|
3
3
|
runSkillwikiMcpStdio
|
|
4
|
-
} from "./chunk-
|
|
4
|
+
} from "./chunk-Z4NCF6K6.js";
|
|
5
5
|
import "./chunk-7I2TPIV5.js";
|
|
6
|
-
import "./chunk-
|
|
7
|
-
import "./chunk-
|
|
8
|
-
import "./chunk-
|
|
9
|
-
import "./chunk-
|
|
10
|
-
import "./chunk-
|
|
11
|
-
import "./chunk-
|
|
6
|
+
import "./chunk-DTTKCCQ4.js";
|
|
7
|
+
import "./chunk-PGD3J2GE.js";
|
|
8
|
+
import "./chunk-HMHMCPCE.js";
|
|
9
|
+
import "./chunk-QU2IXZRN.js";
|
|
10
|
+
import "./chunk-JCDAEZVD.js";
|
|
11
|
+
import "./chunk-GJC2CI3W.js";
|
|
12
12
|
|
|
13
13
|
// src/mcp-entry.ts
|
|
14
14
|
runSkillwikiMcpStdio().catch((error) => {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "skillwiki",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.107",
|
|
4
4
|
"skills": "./",
|
|
5
5
|
"description": "Project-aware Karpathy-style knowledge base for Claude Code: 22 prompt-only skills (wiki-*, proj-*, using-skillwiki, skillwiki-mcp, skillwiki-connect) backed by the deterministic `skillwiki` CLI.",
|
|
6
6
|
"author": {
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "skillwiki",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.107",
|
|
4
4
|
"description": "Project-aware Karpathy-style knowledge base: 22 prompt-only skills (wiki-*, proj-*, using-skillwiki, skillwiki-mcp, skillwiki-connect) backed by HTTP MCP wiki_capture.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "karlorz"
|
package/skills/package.json
CHANGED
|
@@ -16,12 +16,24 @@ from typing import Mapping
|
|
|
16
16
|
PRODUCTION_MCP_URL = "https://wiki.karldigi.dev/mcp"
|
|
17
17
|
TOKEN_ENV = "SKILLWIKI_MCP_TOKEN"
|
|
18
18
|
URL_ENV = "SKILLWIKI_MCP_URL"
|
|
19
|
+
HEADLESS_OAUTH_LOOPBACK_WARNING = (
|
|
20
|
+
"headless_oauth_loopback: SSH is a hint that the operator browser may not "
|
|
21
|
+
"be this host. MCP OAuth loopback (localhost callback) binds on this host, "
|
|
22
|
+
"so an operator browser on another machine cannot finish it. Set "
|
|
23
|
+
f"{TOKEN_ENV} via process env, host Configure, or skillwiki connect "
|
|
24
|
+
"--from-file. Do not click the SkillWiki OAuth login on another machine."
|
|
25
|
+
)
|
|
19
26
|
|
|
20
27
|
|
|
21
28
|
def _strip(value: str | None) -> str:
|
|
22
29
|
return (value or "").strip()
|
|
23
30
|
|
|
24
31
|
|
|
32
|
+
def _ssh_remote_session(source: Mapping[str, str]) -> bool:
|
|
33
|
+
"""SSH is a hint that the operator browser may not be this host (callback would bind here)."""
|
|
34
|
+
return bool(_strip(source.get("SSH_CONNECTION")) or _strip(source.get("SSH_TTY")))
|
|
35
|
+
|
|
36
|
+
|
|
25
37
|
def probe(environ: Mapping[str, str] | None = None) -> dict:
|
|
26
38
|
source = os.environ if environ is None else environ
|
|
27
39
|
token = _strip(source.get(TOKEN_ENV))
|
|
@@ -30,6 +42,8 @@ def probe(environ: Mapping[str, str] | None = None) -> dict:
|
|
|
30
42
|
reasons: list[str] = []
|
|
31
43
|
|
|
32
44
|
if not token:
|
|
45
|
+
if _ssh_remote_session(source):
|
|
46
|
+
warnings.append(HEADLESS_OAUTH_LOOPBACK_WARNING)
|
|
33
47
|
return {
|
|
34
48
|
"status": "missing_prereq",
|
|
35
49
|
"reasons": [f"{TOKEN_ENV} unset"],
|
|
@@ -21,6 +21,7 @@ Unknown-agent HTTP MCP setup. Use when the client has no SkillWiki plugin and no
|
|
|
21
21
|
- Do **not** use 云盘 / Drive / CloudStorage as the secret path. Only a chat-attached file reaches the VM.
|
|
22
22
|
- Missing `WIKI_PATH` is expected on an MCP-only leaf. Handshake pass is done.
|
|
23
23
|
- Do **not** instruct the operator to paste the bearer into the chat transcript.
|
|
24
|
+
- Do **not** tell the operator to complete SkillWiki OAuth login in a laptop browser for an SSH/remote host. Loopback `http://localhost:<port>/callback` binds on the remote client; headed vs headless is not the discriminator, and SSH is a hint that the operator browser may not be this host. Use `skillwiki connect --from-file`.
|
|
24
25
|
|
|
25
26
|
## Paste-once prompt
|
|
26
27
|
|
|
@@ -16,6 +16,7 @@ SkillWiki captures are HTTP MCP only (`type: http`). Claude/Grok use `SKILLWIKI_
|
|
|
16
16
|
- Resolve the installed plugin root from `GROK_PLUGIN_ROOT`, falling back to `CLAUDE_PLUGIN_ROOT`, and run `python3 "$PLUGIN_ROOT/scripts/check_readiness.py" --apply --json` before the first SkillWiki MCP call.
|
|
17
17
|
- **Cursor / Grok Bot:** the Cursor-native plugin requires `SKILLWIKI_MCP_TOKEN` under **Plugins → Configure**. Optional non-secret `SKILLWIKI_EXTRA_VAULTS` (comma-separated vault ids such as `wiki-fin`) opts the client into extra vaults on the **same** connector URL. It is not a second connector, not a secret, and not written to `~/.cursor/mcp.json` or Grok `config.toml`. Server `allowed_vaults` remains the security boundary; an extra listed here but missing from the bearer still fails closed. Omit `vault=` on tools to use the live handshake `default_vault`; specify an extra vault only when requested. Grok Bot does not inherit Mac process env or `~/.cursor/mcp.json`. `failed_to_load` with no token box means this package is missing; after this package is installed, Configure is the token field (same pattern as grok-search).
|
|
18
18
|
- `missing_prereq` means `SKILLWIKI_MCP_TOKEN` is absent from process environment; stop and ask for a bearer. Do not invent a stdio MCP.
|
|
19
|
+
- **Operator browser not on this host (SSH):** installed `.mcp.json` already sends `Authorization: Bearer ${SKILLWIKI_MCP_TOKEN}`. If the token is missing, a 401 may start MCP OAuth with `http://localhost:<port>/callback` on this host. MCP OAuth loopback binds on this host; headed vs headless is not the discriminator (DISPLAY, VNC, or local Chrome cannot complete loopback when the operator browser is on another machine), and SSH is a hint that the operator browser may not be this host. If `check_readiness.py` `warnings` contain `headless_oauth_loopback`, or the host shows an OAuth login URL over SSH: stop. Ask the operator to set `SKILLWIKI_MCP_TOKEN` (process env, Configure, or `skillwiki connect --from-file`). Do not tell the operator to click the login link on another machine. If SkillWiki tools are already connected, continue.
|
|
19
20
|
- A new host (a machine that should write the wiki for the first time) needs an issued host-id bearer before handshake can pass. The operator runs `skillwiki mcp-auth issue-host --host-id <id> --write` on metal (TTY required). Connector hosts put the printed value into process env or host Configure. Unknown agents (no plugin / no usable connector) ingest a chat-attached env file with `skillwiki connect --from-file` (or `--from-stdin`); do not instruct paste-into-chat. Do not auto-write `mcp.env`, `mcp.json`, or Grok `config.toml`. Do not invent a second admin skill. A local vault/FUSE mirror is optional.
|
|
20
21
|
- First-run order: install plugin/CLI → operator issues on metal → connector Configure **or** unknown-agent `skillwiki connect --from-file <attachment>` → **new session** → `skillwiki doctor --check-mcp` → one write (`wiki_capture`, work-item write, or page publish).
|
|
21
22
|
- `in_sync` means the probe has a usable URL/token decision.
|
|
@@ -30,14 +31,14 @@ Remotes still on a pre-HTTP-MCP plugin or CLI must upgrade the plugin channel (a
|
|
|
30
31
|
|
|
31
32
|
## Writes
|
|
32
33
|
|
|
33
|
-
On leaf hosts, wiki captures go through MCP. Do **not** write `raw/transcripts/` or `log.md` as local files.
|
|
34
|
+
Local Mac coding agents with a valid bearer are managed read-write peers through advertised MCP tools. Remote and other agents are read-mostly; they write only when explicitly authorized and the advertised tool permits the target. On leaf hosts, wiki captures go through MCP. Do **not** write `raw/transcripts/` or `log.md` as local files.
|
|
34
35
|
|
|
35
36
|
Check the successful write receipt's `vault_id` against the intended vault before reporting any write as saved.
|
|
36
37
|
|
|
37
38
|
1. Call MCP `wiki_capture` with `kind` (`task` | `idea` | `bug` | `note`), `project`, `title`, and `content`. Optional `agent_note`. Verify its returned `path` with `wiki_read_page` in that vault.
|
|
38
39
|
2. Call MCP `wiki_log_append` when a structural `log.md` line is needed. Pass append-only `content` (optional `operation_id` is 64 hex). Success returns a receipt (`operation_id`, `event_path`, hashes, `s3_verified`). Verify the exact block via `wiki_read_page(event_path)`. Do not require reading `log.md`. If `log.md` is over 256 KiB, full `wiki_read_page("log.md")` returns `PAGE_TOO_LARGE`; use `tail_bytes` only to browse the newest end.
|
|
39
40
|
3. **Feature-detect work-item and page-publish tools**:
|
|
40
|
-
- When the server advertises `wiki_workitem_write`: use it to create, mutate, or close work items under `projects/<slug>/work/**` or update `projects/<slug>/knowledge.md`, and to save Layer-3 workspace markdown: `projects/<slug>/README.md`, `projects/<slug>/architecture/**/*.md`, `projects/<slug>/requirements/**/*.md`, `projects/<slug>/compound/**/*.md`. Pass `path`, `content`, and `base_sha256` of existing bytes (from `wiki_read_page` or local mirror). On `FILE_CHANGED`, re-read and retry once. Deployed servers that predate the workspace-family allowlist deny those paths — treat that `PATH_DENIED` as "server predates this release"; STOP, do not fall back.
|
|
41
|
+
- When the server advertises `wiki_workitem_write`: use it to create, mutate, or close work items under `projects/<slug>/work/**` or update `projects/<slug>/knowledge.md`, and to save Layer-3 workspace markdown. For work-item `spec.md` or goal-plan `plan.md`, pass optional `agent_role` / `agent_id`; the server stamps authenticated `host` and supplied agent identity into frontmatter. Supported workspace paths are: `projects/<slug>/README.md`, `projects/<slug>/architecture/**/*.md`, `projects/<slug>/requirements/**/*.md`, `projects/<slug>/compound/**/*.md`. Pass `path`, `content`, and `base_sha256` of existing bytes (from `wiki_read_page` or local mirror). On `FILE_CHANGED`, re-read and retry once. Deployed servers that predate the workspace-family allowlist deny those paths — treat that `PATH_DENIED` as "server predates this release"; STOP, do not fall back.
|
|
41
42
|
- When the server advertises `wiki_page_publish`: use it to publish typed Layer-2 pages (`entities/`, `concepts/`, `comparisons/`, `queries/`, `meta/`) using the same CAS protocol.
|
|
42
43
|
- When those tools are **absent** from the live tool list (e.g. server is captures-only): do not call them or claim they exist. If `$VAULT/.WIKI_GIT_FROZEN` exists, fall back to capturing a close note via `wiki_capture` or STOP. Work-item close remains unavailable on the frozen leaf without `wiki_workitem_write`. Do not `git commit` / `wiki-push` against `~/wiki`.
|
|
43
44
|
4. **`PATH_DENIED` means STOP.** Paths outside the allowlist (`projects/<slug>/history/**`, non-`.md` files such as `fleet.yaml` or `.canvas`, `AGENTS.md`/`CLAUDE.md`, raw edits, index/projection rebuilds) have no agent write path over MCP. wiki-push / `rclone copy` is **not** an agent writer: it bypasses the daemon working copy, so `wiki_read_page` cannot see those bytes until the sg01 snapshot. Never report an S3-only copy as "saved to wiki". Capture the blocked intent via `wiki_capture` and report the denial instead.
|
|
@@ -46,8 +47,8 @@ Check the successful write receipt's `vault_id` against the intended vault befor
|
|
|
46
47
|
|
|
47
48
|
Local `~/wiki` (or `skillwiki path`) is fine for reads. MCP read tools are optional. Prefer ordinary file reads of the local mirror. Frozen-leaf agents should use HTTP `wiki_sources_pending`, `wiki_lint_summary`, `wiki_stale`, `wiki_compile_status`, and `wiki_reviews` instead of local CLI commands when those tools are advertised.
|
|
48
49
|
|
|
49
|
-
`wiki_query` is typed knowledge only unless `scope` is `work` or `all`. For queued work, doctor, plugin-drift, or MCP diagnose questions, call `wiki_context` first (active_work) or pass `scope: "work"` / `"all"`. Do not treat a top typed packet hit as the live work queue.
|
|
50
|
+
`wiki_query` is typed knowledge only unless `scope` is `work` or `all`. For recent progress, key projects, or to-dos, feature-detect and call `wiki_progress`; apply `project`, `host`, or `agent_role` filters when requested, and present `recent_progress`, `key_projects`, and `todos` as complete bullet lists. For queued work, doctor, plugin-drift, or MCP diagnose questions, call `wiki_context` first (active_work) or pass `scope: "work"` / `"all"`. Do not treat a top typed packet hit as the live work queue.
|
|
50
51
|
|
|
51
52
|
## Errors
|
|
52
53
|
|
|
53
|
-
Report handshake, capture, and append failures literally. If tools are missing after a 401 or `missing_prereq`, stop and tell the operator to set `SKILLWIKI_MCP_TOKEN` via process env, host Configure, or `skillwiki connect --from-file` (unknown agents; never paste-into-chat), run `grok plugin update skillwiki`, and start a new session. Do not fall back to local `raw/transcripts/` writes.
|
|
54
|
+
Report handshake, capture, and append failures literally. If tools are missing after a 401 or `missing_prereq`, stop and tell the operator to set `SKILLWIKI_MCP_TOKEN` via process env, host Configure, or `skillwiki connect --from-file` (unknown agents; never paste-into-chat), run `grok plugin update skillwiki`, and start a new session. Over SSH, treat an OAuth login URL the same way: report `headless_oauth_loopback` and stop. Do not fall back to local `raw/transcripts/` writes.
|
|
@@ -16,7 +16,7 @@ Choose the matching installed skill:
|
|
|
16
16
|
- Projects and planning: `proj-init`, `proj-work`, `proj-distill`,
|
|
17
17
|
`proj-decide`, `wiki-gate-plan-mode`, `dev-loop:research`.
|
|
18
18
|
- Fleet and visualization: `wiki-sync`, `wiki-canvas`.
|
|
19
|
-
- HTTP MCP capture or
|
|
19
|
+
- HTTP MCP capture, append, or progress query: `skillwiki-mcp`.
|
|
20
20
|
|
|
21
21
|
If routing is unclear, invoke `using-skillwiki` rather than guessing.
|
|
22
22
|
|
|
@@ -39,10 +39,7 @@ PRD provider and stage, SkillWiki provenance, and simplify review independent.
|
|
|
39
39
|
|
|
40
40
|
## Managed-Write Safety
|
|
41
41
|
|
|
42
|
-
The HTTP MCP contract below controls remote reads and mutations. On leaf hosts,
|
|
43
|
-
captures use MCP, never local `raw/transcripts` or `log.md` writes. Project
|
|
44
|
-
workspace writes use `wiki_workitem_write` with compare-and-swap; stop if the
|
|
45
|
-
tool or path family is unavailable. A wiki push or rclone copy is not a managed
|
|
42
|
+
The HTTP MCP contract below controls remote reads and mutations. Local Mac coding agents with a valid bearer are managed read-write peers through advertised MCP tools. Remote and other agents are read-mostly; they write only when explicitly authorized and the advertised MCP tool permits the target. On leaf hosts, captures use MCP, never local `raw/transcripts` or `log.md` writes. Project workspace writes use `wiki_workitem_write` with compare-and-swap; stop if the tool or path family is unavailable. A wiki push or rclone copy is not a managed
|
|
46
43
|
write and is not visible until the authoritative snapshot. Never use bare `rm`
|
|
47
44
|
or `git rm` for fleet deletion. Never auto-install SkillWiki in unattended
|
|
48
45
|
sessions. If required publish support is unavailable, fail closed.
|
|
@@ -72,6 +69,9 @@ vault.
|
|
|
72
69
|
For `wiki_workitem_write` or `wiki_page_publish`, read first, send the returned
|
|
73
70
|
sha256 as `base_sha256`, and on `FILE_CHANGED` re-read, rebase, and retry.
|
|
74
71
|
|
|
72
|
+
### Progress Queries
|
|
73
|
+
Use `wiki_progress` for recent progress, key projects, or to-dos. Apply requested project, host, or agent-role filters and answer with complete bullet lists.
|
|
74
|
+
|
|
75
75
|
### Capture Kinds
|
|
76
76
|
`wiki_capture` kind is `task | idea | bug | note`. Captures append to
|
|
77
77
|
`raw/transcripts/`. Verify its returned `path` with `wiki_read_page`.
|
|
@@ -14,6 +14,7 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
|
|
|
14
14
|
0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
|
|
15
15
|
1. **Determine scope.** Ask the user once if ambiguous: vault | current project | project+concepts.
|
|
16
16
|
- Ordinary questions are typed-knowledge-first. Run `skillwiki query "<text>" [vault]` without widening into raw captures. Default ranking is 4-signal only. Optional `skillwiki query "<text>" --hybrid` RRF-fuses that ranking with a rebuildable TF-IDF cache (`skillwiki vectors rebuild`); if the cache is missing, stop and rebuild instead of silently falling back.
|
|
17
|
+
- Recent progress, key-project, or to-do questions use the MCP `wiki_progress` tool when advertised. Apply requested `project`, `host`, or `agent_role` filters and render all three result sections as complete bullet lists.
|
|
17
18
|
- Setup, MCP, doctor, plugin-drift, or "open work" questions are not typed-knowledge searches. Call `wiki_context` (active_work) or `skillwiki query "<text>" --scope work` / `--scope all`. Default typed query never ranks `projects/*/work`.
|
|
18
19
|
- Explicit freshness language — `new`, `recent`, `fresh`, `clipped`, `raw`, `pending`, `undigested`, `unprocessed`, `not yet ingested`, or `not yet integrated` — requests the pending evidence channel. Run `skillwiki sources pending [vault]` for inventory and `skillwiki query "<text>" [vault] --include-pending` for synthesis support.
|
|
19
20
|
2. **Refresh graph.** If `.skillwiki/graph.json` is missing or older than 24h: `skillwiki graph build <vault>`.
|
|
@@ -21,6 +21,7 @@ Unknown-agent HTTP MCP setup. Use when the client has no SkillWiki plugin and no
|
|
|
21
21
|
- Do **not** use 云盘 / Drive / CloudStorage as the secret path. Only a chat-attached file reaches the VM.
|
|
22
22
|
- Missing `WIKI_PATH` is expected on an MCP-only leaf. Handshake pass is done.
|
|
23
23
|
- Do **not** instruct the operator to paste the bearer into the chat transcript.
|
|
24
|
+
- Do **not** tell the operator to complete SkillWiki OAuth login in a laptop browser for an SSH/remote host. Loopback `http://localhost:<port>/callback` binds on the remote client; headed vs headless is not the discriminator, and SSH is a hint that the operator browser may not be this host. Use `skillwiki connect --from-file`.
|
|
24
25
|
|
|
25
26
|
## Paste-once prompt
|
|
26
27
|
|
|
@@ -16,6 +16,7 @@ SkillWiki captures are HTTP MCP only (`type: http`). Claude/Grok use `SKILLWIKI_
|
|
|
16
16
|
- Resolve the installed plugin root from `GROK_PLUGIN_ROOT`, falling back to `CLAUDE_PLUGIN_ROOT`, and run `python3 "$PLUGIN_ROOT/scripts/check_readiness.py" --apply --json` before the first SkillWiki MCP call.
|
|
17
17
|
- **Cursor / Grok Bot:** the Cursor-native plugin requires `SKILLWIKI_MCP_TOKEN` under **Plugins → Configure**. Optional non-secret `SKILLWIKI_EXTRA_VAULTS` (comma-separated vault ids such as `wiki-fin`) opts the client into extra vaults on the **same** connector URL. It is not a second connector, not a secret, and not written to `~/.cursor/mcp.json` or Grok `config.toml`. Server `allowed_vaults` remains the security boundary; an extra listed here but missing from the bearer still fails closed. Omit `vault=` on tools to use the live handshake `default_vault`; specify an extra vault only when requested. Grok Bot does not inherit Mac process env or `~/.cursor/mcp.json`. `failed_to_load` with no token box means this package is missing; after this package is installed, Configure is the token field (same pattern as grok-search).
|
|
18
18
|
- `missing_prereq` means `SKILLWIKI_MCP_TOKEN` is absent from process environment; stop and ask for a bearer. Do not invent a stdio MCP.
|
|
19
|
+
- **Operator browser not on this host (SSH):** installed `.mcp.json` already sends `Authorization: Bearer ${SKILLWIKI_MCP_TOKEN}`. If the token is missing, a 401 may start MCP OAuth with `http://localhost:<port>/callback` on this host. MCP OAuth loopback binds on this host; headed vs headless is not the discriminator (DISPLAY, VNC, or local Chrome cannot complete loopback when the operator browser is on another machine), and SSH is a hint that the operator browser may not be this host. If `check_readiness.py` `warnings` contain `headless_oauth_loopback`, or the host shows an OAuth login URL over SSH: stop. Ask the operator to set `SKILLWIKI_MCP_TOKEN` (process env, Configure, or `skillwiki connect --from-file`). Do not tell the operator to click the login link on another machine. If SkillWiki tools are already connected, continue.
|
|
19
20
|
- A new host (a machine that should write the wiki for the first time) needs an issued host-id bearer before handshake can pass. The operator runs `skillwiki mcp-auth issue-host --host-id <id> --write` on metal (TTY required). Connector hosts put the printed value into process env or host Configure. Unknown agents (no plugin / no usable connector) ingest a chat-attached env file with `skillwiki connect --from-file` (or `--from-stdin`); do not instruct paste-into-chat. Do not auto-write `mcp.env`, `mcp.json`, or Grok `config.toml`. Do not invent a second admin skill. A local vault/FUSE mirror is optional.
|
|
20
21
|
- First-run order: install plugin/CLI → operator issues on metal → connector Configure **or** unknown-agent `skillwiki connect --from-file <attachment>` → **new session** → `skillwiki doctor --check-mcp` → one write (`wiki_capture`, work-item write, or page publish).
|
|
21
22
|
- `in_sync` means the probe has a usable URL/token decision.
|
|
@@ -30,14 +31,14 @@ Remotes still on a pre-HTTP-MCP plugin or CLI must upgrade the plugin channel (a
|
|
|
30
31
|
|
|
31
32
|
## Writes
|
|
32
33
|
|
|
33
|
-
On leaf hosts, wiki captures go through MCP. Do **not** write `raw/transcripts/` or `log.md` as local files.
|
|
34
|
+
Local Mac coding agents with a valid bearer are managed read-write peers through advertised MCP tools. Remote and other agents are read-mostly; they write only when explicitly authorized and the advertised tool permits the target. On leaf hosts, wiki captures go through MCP. Do **not** write `raw/transcripts/` or `log.md` as local files.
|
|
34
35
|
|
|
35
36
|
Check the successful write receipt's `vault_id` against the intended vault before reporting any write as saved.
|
|
36
37
|
|
|
37
38
|
1. Call MCP `wiki_capture` with `kind` (`task` | `idea` | `bug` | `note`), `project`, `title`, and `content`. Optional `agent_note`. Verify its returned `path` with `wiki_read_page` in that vault.
|
|
38
39
|
2. Call MCP `wiki_log_append` when a structural `log.md` line is needed. Pass append-only `content` (optional `operation_id` is 64 hex). Success returns a receipt (`operation_id`, `event_path`, hashes, `s3_verified`). Verify the exact block via `wiki_read_page(event_path)`. Do not require reading `log.md`. If `log.md` is over 256 KiB, full `wiki_read_page("log.md")` returns `PAGE_TOO_LARGE`; use `tail_bytes` only to browse the newest end.
|
|
39
40
|
3. **Feature-detect work-item and page-publish tools**:
|
|
40
|
-
- When the server advertises `wiki_workitem_write`: use it to create, mutate, or close work items under `projects/<slug>/work/**` or update `projects/<slug>/knowledge.md`, and to save Layer-3 workspace markdown: `projects/<slug>/README.md`, `projects/<slug>/architecture/**/*.md`, `projects/<slug>/requirements/**/*.md`, `projects/<slug>/compound/**/*.md`. Pass `path`, `content`, and `base_sha256` of existing bytes (from `wiki_read_page` or local mirror). On `FILE_CHANGED`, re-read and retry once. Deployed servers that predate the workspace-family allowlist deny those paths — treat that `PATH_DENIED` as "server predates this release"; STOP, do not fall back.
|
|
41
|
+
- When the server advertises `wiki_workitem_write`: use it to create, mutate, or close work items under `projects/<slug>/work/**` or update `projects/<slug>/knowledge.md`, and to save Layer-3 workspace markdown. For work-item `spec.md` or goal-plan `plan.md`, pass optional `agent_role` / `agent_id`; the server stamps authenticated `host` and supplied agent identity into frontmatter. Supported workspace paths are: `projects/<slug>/README.md`, `projects/<slug>/architecture/**/*.md`, `projects/<slug>/requirements/**/*.md`, `projects/<slug>/compound/**/*.md`. Pass `path`, `content`, and `base_sha256` of existing bytes (from `wiki_read_page` or local mirror). On `FILE_CHANGED`, re-read and retry once. Deployed servers that predate the workspace-family allowlist deny those paths — treat that `PATH_DENIED` as "server predates this release"; STOP, do not fall back.
|
|
41
42
|
- When the server advertises `wiki_page_publish`: use it to publish typed Layer-2 pages (`entities/`, `concepts/`, `comparisons/`, `queries/`, `meta/`) using the same CAS protocol.
|
|
42
43
|
- When those tools are **absent** from the live tool list (e.g. server is captures-only): do not call them or claim they exist. If `$VAULT/.WIKI_GIT_FROZEN` exists, fall back to capturing a close note via `wiki_capture` or STOP. Work-item close remains unavailable on the frozen leaf without `wiki_workitem_write`. Do not `git commit` / `wiki-push` against `~/wiki`.
|
|
43
44
|
4. **`PATH_DENIED` means STOP.** Paths outside the allowlist (`projects/<slug>/history/**`, non-`.md` files such as `fleet.yaml` or `.canvas`, `AGENTS.md`/`CLAUDE.md`, raw edits, index/projection rebuilds) have no agent write path over MCP. wiki-push / `rclone copy` is **not** an agent writer: it bypasses the daemon working copy, so `wiki_read_page` cannot see those bytes until the sg01 snapshot. Never report an S3-only copy as "saved to wiki". Capture the blocked intent via `wiki_capture` and report the denial instead.
|
|
@@ -46,8 +47,8 @@ Check the successful write receipt's `vault_id` against the intended vault befor
|
|
|
46
47
|
|
|
47
48
|
Local `~/wiki` (or `skillwiki path`) is fine for reads. MCP read tools are optional. Prefer ordinary file reads of the local mirror. Frozen-leaf agents should use HTTP `wiki_sources_pending`, `wiki_lint_summary`, `wiki_stale`, `wiki_compile_status`, and `wiki_reviews` instead of local CLI commands when those tools are advertised.
|
|
48
49
|
|
|
49
|
-
`wiki_query` is typed knowledge only unless `scope` is `work` or `all`. For queued work, doctor, plugin-drift, or MCP diagnose questions, call `wiki_context` first (active_work) or pass `scope: "work"` / `"all"`. Do not treat a top typed packet hit as the live work queue.
|
|
50
|
+
`wiki_query` is typed knowledge only unless `scope` is `work` or `all`. For recent progress, key projects, or to-dos, feature-detect and call `wiki_progress`; apply `project`, `host`, or `agent_role` filters when requested, and present `recent_progress`, `key_projects`, and `todos` as complete bullet lists. For queued work, doctor, plugin-drift, or MCP diagnose questions, call `wiki_context` first (active_work) or pass `scope: "work"` / `"all"`. Do not treat a top typed packet hit as the live work queue.
|
|
50
51
|
|
|
51
52
|
## Errors
|
|
52
53
|
|
|
53
|
-
Report handshake, capture, and append failures literally. If tools are missing after a 401 or `missing_prereq`, stop and tell the operator to set `SKILLWIKI_MCP_TOKEN` via process env, host Configure, or `skillwiki connect --from-file` (unknown agents; never paste-into-chat), run `grok plugin update skillwiki`, and start a new session. Do not fall back to local `raw/transcripts/` writes.
|
|
54
|
+
Report handshake, capture, and append failures literally. If tools are missing after a 401 or `missing_prereq`, stop and tell the operator to set `SKILLWIKI_MCP_TOKEN` via process env, host Configure, or `skillwiki connect --from-file` (unknown agents; never paste-into-chat), run `grok plugin update skillwiki`, and start a new session. Over SSH, treat an OAuth login URL the same way: report `headless_oauth_loopback` and stop. Do not fall back to local `raw/transcripts/` writes.
|
|
@@ -16,7 +16,7 @@ Choose the matching installed skill:
|
|
|
16
16
|
- Projects and planning: `proj-init`, `proj-work`, `proj-distill`,
|
|
17
17
|
`proj-decide`, `wiki-gate-plan-mode`, `dev-loop:research`.
|
|
18
18
|
- Fleet and visualization: `wiki-sync`, `wiki-canvas`.
|
|
19
|
-
- HTTP MCP capture or
|
|
19
|
+
- HTTP MCP capture, append, or progress query: `skillwiki-mcp`.
|
|
20
20
|
|
|
21
21
|
If routing is unclear, invoke `using-skillwiki` rather than guessing.
|
|
22
22
|
|
|
@@ -39,10 +39,7 @@ PRD provider and stage, SkillWiki provenance, and simplify review independent.
|
|
|
39
39
|
|
|
40
40
|
## Managed-Write Safety
|
|
41
41
|
|
|
42
|
-
The HTTP MCP contract below controls remote reads and mutations. On leaf hosts,
|
|
43
|
-
captures use MCP, never local `raw/transcripts` or `log.md` writes. Project
|
|
44
|
-
workspace writes use `wiki_workitem_write` with compare-and-swap; stop if the
|
|
45
|
-
tool or path family is unavailable. A wiki push or rclone copy is not a managed
|
|
42
|
+
The HTTP MCP contract below controls remote reads and mutations. Local Mac coding agents with a valid bearer are managed read-write peers through advertised MCP tools. Remote and other agents are read-mostly; they write only when explicitly authorized and the advertised MCP tool permits the target. On leaf hosts, captures use MCP, never local `raw/transcripts` or `log.md` writes. Project workspace writes use `wiki_workitem_write` with compare-and-swap; stop if the tool or path family is unavailable. A wiki push or rclone copy is not a managed
|
|
46
43
|
write and is not visible until the authoritative snapshot. Never use bare `rm`
|
|
47
44
|
or `git rm` for fleet deletion. Never auto-install SkillWiki in unattended
|
|
48
45
|
sessions. If required publish support is unavailable, fail closed.
|
|
@@ -72,6 +69,9 @@ vault.
|
|
|
72
69
|
For `wiki_workitem_write` or `wiki_page_publish`, read first, send the returned
|
|
73
70
|
sha256 as `base_sha256`, and on `FILE_CHANGED` re-read, rebase, and retry.
|
|
74
71
|
|
|
72
|
+
### Progress Queries
|
|
73
|
+
Use `wiki_progress` for recent progress, key projects, or to-dos. Apply requested project, host, or agent-role filters and answer with complete bullet lists.
|
|
74
|
+
|
|
75
75
|
### Capture Kinds
|
|
76
76
|
`wiki_capture` kind is `task | idea | bug | note`. Captures append to
|
|
77
77
|
`raw/transcripts/`. Verify its returned `path` with `wiki_read_page`.
|
|
@@ -14,6 +14,7 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
|
|
|
14
14
|
0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
|
|
15
15
|
1. **Determine scope.** Ask the user once if ambiguous: vault | current project | project+concepts.
|
|
16
16
|
- Ordinary questions are typed-knowledge-first. Run `skillwiki query "<text>" [vault]` without widening into raw captures. Default ranking is 4-signal only. Optional `skillwiki query "<text>" --hybrid` RRF-fuses that ranking with a rebuildable TF-IDF cache (`skillwiki vectors rebuild`); if the cache is missing, stop and rebuild instead of silently falling back.
|
|
17
|
+
- Recent progress, key-project, or to-do questions use the MCP `wiki_progress` tool when advertised. Apply requested `project`, `host`, or `agent_role` filters and render all three result sections as complete bullet lists.
|
|
17
18
|
- Setup, MCP, doctor, plugin-drift, or "open work" questions are not typed-knowledge searches. Call `wiki_context` (active_work) or `skillwiki query "<text>" --scope work` / `--scope all`. Default typed query never ranks `projects/*/work`.
|
|
18
19
|
- Explicit freshness language — `new`, `recent`, `fresh`, `clipped`, `raw`, `pending`, `undigested`, `unprocessed`, `not yet ingested`, or `not yet integrated` — requests the pending evidence channel. Run `skillwiki sources pending [vault]` for inventory and `skillwiki query "<text>" [vault] --include-pending` for synthesis support.
|
|
19
20
|
2. **Refresh graph.** If `.skillwiki/graph.json` is missing or older than 24h: `skillwiki graph build <vault>`.
|
package/templates/SCHEMA.md
CHANGED
|
@@ -92,6 +92,9 @@ created: YYYY-MM-DD # when capture was written
|
|
|
92
92
|
ingested: # filled by ingest pipeline (empty at creation)
|
|
93
93
|
kind: # idea | bug | task | note | other
|
|
94
94
|
project: # optional: "[[slug]]" for cross-reference
|
|
95
|
+
host: # optional: host identity token (stamped by MCP writer)
|
|
96
|
+
agent_role: # optional: agent role identity token
|
|
97
|
+
agent_id: # optional: agent identity token
|
|
95
98
|
---
|
|
96
99
|
```
|
|
97
100
|
|
|
@@ -101,6 +104,9 @@ project: # optional: "[[slug]]" for cross-reference
|
|
|
101
104
|
- `ingested`: Date processed into typed knowledge. **Empty at creation.** Filled by `wiki-ingest`, `wiki-crystallize`.
|
|
102
105
|
- `kind`: Capture type. Affects dev-loop routing (`bug`/`task` → work items; `idea` → knowledge development).
|
|
103
106
|
- `project`: Optional project cross-reference. Enables `provenance_projects:` auto-linking.
|
|
107
|
+
- `host`: Optional host identity token (e.g. `macos-dev`, `sg01`). Stamped by MCP writer from authenticated identity.
|
|
108
|
+
- `agent_role`: Optional agent role identity token (e.g. `researcher`, `worker`, `reviewer`).
|
|
109
|
+
- `agent_id`: Optional specific agent instance identifier.
|
|
104
110
|
|
|
105
111
|
### vs Ingested Sources
|
|
106
112
|
|