@skillit/core 1.5.0 → 2.1.0

package/dist/index.d.ts

@@ -13,7 +13,7 @@
  *
  * @packageDocumentation
  */
-export type { ExtractedSkill, ExtractedSkillAudit, ExtractedFunction, ExtractedFunctionMcpMetadata, ExtractedClass, ExtractedType, ExtractedEnum, ExtractedParameter, ExtractedProperty, ExtractedVariable, ExtractedDocument, ExtractedResource, ExtractedPrompt, ExtractedPromptArgument, SkillSetup, AdapterFingerprint, InvocationAdapter, AdapterRenderContext, AdapterRenderContextBase, AdapterRenderContextBundle, AdapterRenderContextHttp, AdapterRenderContextStdio, RefCategory, RefManifest, RefManifestEntry, RenderedFile, RenderedSkill, SkillRenderOptions, SkillWriteOptions, SkillWriteResult, SkillWritePreserveReason, McpAuditSeverity, McpAuditIssue } from './types.js';
+export type { DepSkillRef, ExtractedSkill, ExtractedSkillAudit, ExtractedFunction, ExtractedFunctionMcpMetadata, ExtractedClass, ExtractedType, ExtractedEnum, ExtractedParameter, ExtractedProperty, ExtractedVariable, ExtractedDocument, ExtractedResource, ExtractedPrompt, ExtractedPromptArgument, SkillSetup, AdapterFingerprint, InvocationAdapter, AdapterRenderContext, AdapterRenderContextBase, AdapterRenderContextBundle, AdapterRenderContextHttp, AdapterRenderContextStdio, RefCategory, RefManifest, RefManifestEntry, RenderedFile, RenderedSkill, SkillRenderOptions, SkillWriteOptions, SkillWriteResult, SkillWritePreserveReason, McpAuditSeverity, McpAuditIssue } from './types.js';
 export { renderSkills, renderSkill } from './renderer.js';
 export { canonicalize } from './canonical.js';
 export type { CanonicalizeOptions } from './canonical.js';
@@ -23,7 +23,7 @@ export { renderResourcesReference, renderPromptsReference } from './references-m
 export type { McpReferenceOptions } from './references-mcp.js';
 export { renderLlmsTxt } from './llms-txt.js';
 export type { LlmsTxtOptions, LlmsTxtResult } from './llms-txt.js';
-export type { AuditSeverity, AuditIssue, AuditPass, AuditContext, ParsedReadme, AuditResult } from './audit-types.js';
+export type { AuditSeverity, AuditIssue, AuditPass, ParsedReadme, AuditResult } from './audit-types.js';
 export { parseReadme } from './readme-parser.js';
 export { auditSkill } from './audit.js';
 export { formatAuditText, formatAuditJson, formatScoreEstimate } from './audit-formatter.js';
@@ -31,6 +31,7 @@ export { estimateSkillJudgeScore } from './audit-score.js';
 export type { SkillJudgeEstimate, ActionableImprovement } from './audit-score.js';
 export type { ConfigSourceType, ExtractedConfigSurface, ExtractedConfigOption, ExtractedConfigArgument } from './config-types.js';
 export { renderConfigSurfaceSection, renderConfigReference } from './config-renderer.js';
+export { extractConfigSurface } from './config-extract.js';
 export type { ParsedSection, ParsedMarkdownDoc, DocsExtractionOptions } from './markdown-types.js';
 export { parseMarkdownDoc } from './markdown-parser.js';
 export { scanDocs, docsToExtractedDocuments, scanRootDocs } from './docs-scanner.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,4BAA4B,EAC5B,cAAc,EACd,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,uBAAuB,EACvB,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,EACzB,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,gBAAgB,EAChB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACvF,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnE,YAAY,EACV,aAAa,EACb,UAAU,EACV,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE7F,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAElF,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAEzF,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,QAAQ,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErF,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC1E,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EACV,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,4BAA4B,EAC5B,cAAc,EACd,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,uBAAuB,EACvB,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,EACzB,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,gBAAgB,EAChB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACvF,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnE,YAAY,EACV,aAAa,EACb,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE7F,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAElF,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,QAAQ,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErF,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC1E,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -24,6 +24,7 @@ export { auditSkill } from './audit.js';
 export { formatAuditText, formatAuditJson, formatScoreEstimate } from './audit-formatter.js';
 export { estimateSkillJudgeScore } from './audit-score.js';
 export { renderConfigSurfaceSection, renderConfigReference } from './config-renderer.js';
+export { extractConfigSurface } from './config-extract.js';
 export { parseMarkdownDoc } from './markdown-parser.js';
 export { scanDocs, docsToExtractedDocuments, scanRootDocs } from './docs-scanner.js';
 export { scanExamples, linkExamplesToSkill } from './examples-scanner.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAsCH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAEvF,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAY9C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE7F,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAU3D,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAIzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,QAAQ,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErF,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG1E,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAuCH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAEvF,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAW9C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE7F,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAU3D,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAI3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,QAAQ,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErF,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG1E,cAAc,mBAAmB,CAAC"}

package/dist/refine/ast-edit.d.ts

@@ -8,8 +8,49 @@ import type { RefineTag } from './types.js';
  * - If a JSDoc block exists without the tag, the tag is appended before the
  *   closing `*\/`.
  * - If the declaration is not found, the source is returned unchanged.
+ *
+ * @remarks
+ * Parses `source` with ast-grep (core carries no `typescript` dependency) and
+ * edits the text in place, so formatting outside the touched JSDoc block is
+ * preserved. Tag matching is by name, so re-running with the same tag is a
+ * no-op rather than a duplicate.
  */
 export declare function upsertJsDocTag(source: string, declName: string, tag: RefineTag, content: string): string;
+/**
+ * Insert or update a JSDoc tag on a property of a config type.
+ *
+ * `propertyPath` is a dot path into the interface or object-type alias named
+ * `typeName` (e.g. `outDir` or `components.prefix`). Otherwise behaves like
+ * {@link upsertJsDocTag}. Returns the source unchanged when the type or
+ * property is not found. Used by the config refine source to write routing
+ * tags back onto a config type's property declarations.
+ *
+ * @remarks
+ * Resolves `propertyPath` against the body of `typeName` via ast-grep, recursing
+ * into nested object-type members for dotted paths. Like {@link upsertJsDocTag},
+ * the edit is text-level and idempotent per tag name.
+ */
+export declare function upsertPropertyJsDocTag(source: string, typeName: string, propertyPath: string, tag: RefineTag, content: string): string;
+/**
+ * Remove the refine-managed tag spans (`@useWhen`, `@avoidWhen`, `@pitfalls`,
+ * `@remarks`, `@example` — see {@link REFINE_TAGS}) from every JSDoc block in
+ * `source`, leaving each block's prose description and any non-refine tags
+ * intact.
+ *
+ * Used to feed an annotated config module back to the model as grounding
+ * without echoing the routing tags this package itself wrote across earlier
+ * refine iterations — those are documentation, not the implementation the model
+ * should ground runtime claims in. Unlike a blanket JSDoc strip, this preserves
+ * genuine hand-authored docs (e.g. validation notes on a `defineConfig` helper),
+ * which are exactly the runtime-behavior grounding we want to keep.
+ *
+ * Handles single-line (`/** @tag x *​/`) as well as multi-line blocks: each block
+ * is reduced to its inner content (opener/closer and ` * ` gutter dropped) before
+ * tags are matched, so an inline opener can't hide a tag. The block-matching
+ * regex is non-greedy, and writeback escapes a literal close sequence in content
+ * to `*\/`, so an escaped sequence inside a kept line never terminates early.
+ */
+export declare function stripRefineTags(source: string): string;
 /**
  * Parse the leading JSDoc block of a named export declaration and return a
  * map of the RefineTag values found in it.

package/dist/refine/ast-edit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast-edit.d.ts","sourceRoot":"","sources":["../../src/refine/ast-edit.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAwF5C;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,MAAM,GACd,MAAM,CA+BR;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAoBpC"}
+{"version":3,"file":"ast-edit.d.ts","sourceRoot":"","sources":["../../src/refine/ast-edit.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAwF5C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,MAAM,GACd,MAAM,CAKR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,MAAM,GACd,MAAM,CAOR;AAgFD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOtD;AA0CD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAyCpC"}

package/dist/refine/ast-edit.js

@@ -1,5 +1,6 @@
 // packages/core/src/refine/ast-edit.ts
 import { parse, Lang } from '@ast-grep/napi';
+import { escapeJsDocClose, findPropertyByPath, findTypeBody, unescapeJsDocClose } from '../config-extract.js';
 // `satisfies` ensures every listed value is a valid RefineTag. The
 // `MissingTags` assertion below makes the inverse hold too: if a value is added
 // to the RefineTag union but not to this list, compilation fails — so the
@@ -90,34 +91,179 @@ function leadingJsDoc(anchorNode) {
  * - If a JSDoc block exists without the tag, the tag is appended before the
  *   closing `*\/`.
  * - If the declaration is not found, the source is returned unchanged.
+ *
+ * @remarks
+ * Parses `source` with ast-grep (core carries no `typescript` dependency) and
+ * edits the text in place, so formatting outside the touched JSDoc block is
+ * preserved. Tag matching is by name, so re-running with the same tag is a
+ * no-op rather than a duplicate.
  */
 export function upsertJsDocTag(source, declName, tag, content) {
     const root = parse(Lang.TypeScript, source).root();
     const anchorNode = findDeclaration(root, declName);
     if (!anchorNode)
         return source;
-    const tagText = `@${tag} ${content}`;
+    return upsertTagOnAnchor(source, root, anchorNode, tag, content);
+}
+/**
+ * Insert or update a JSDoc tag on a property of a config type.
+ *
+ * `propertyPath` is a dot path into the interface or object-type alias named
+ * `typeName` (e.g. `outDir` or `components.prefix`). Otherwise behaves like
+ * {@link upsertJsDocTag}. Returns the source unchanged when the type or
+ * property is not found. Used by the config refine source to write routing
+ * tags back onto a config type's property declarations.
+ *
+ * @remarks
+ * Resolves `propertyPath` against the body of `typeName` via ast-grep, recursing
+ * into nested object-type members for dotted paths. Like {@link upsertJsDocTag},
+ * the edit is text-level and idempotent per tag name.
+ */
+export function upsertPropertyJsDocTag(source, typeName, propertyPath, tag, content) {
+    const root = parse(Lang.TypeScript, source).root();
+    const body = findTypeBody(root, typeName);
+    if (!body)
+        return source;
+    const property = findPropertyByPath(body, propertyPath);
+    if (!property)
+        return source;
+    return upsertTagOnAnchor(source, root, property, tag, content);
+}
+/**
+ * Insert or update `@tag content` on the JSDoc block leading `anchorNode`,
+ * creating the block when absent. Idempotent per tag (matches the tag NAME, so
+ * multi-line content never produces duplicates) and rebuilds the block as
+ * well-formed multi-line (handling single-line `/** text *\/` inputs). Shared by
+ * the declaration-level ({@link upsertJsDocTag}) and property-level
+ * ({@link upsertPropertyJsDocTag}) upserts.
+ */
+function upsertTagOnAnchor(source, root, anchorNode, tag, content) {
+    // Escape any comment-close sequence in the content so a value containing it
+    // (e.g. a glob like `**/*.ts` in a config pitfall) can't terminate the block
+    // early and corrupt the file. readJsDocTags / config extraction unescape it.
+    const tagText = escapeJsDocClose(`@${tag} ${content}`);
     const jsdocNode = leadingJsDoc(anchorNode);
+    // Indent from the comment when one exists: it may sit on the SAME line as the
+    // declaration (`/** x */ prop`), where the declaration's own column is the
+    // text after the comment, not the line indent — using it over-indented every
+    // rebuilt continuation line. With no comment, indent from the declaration the
+    // new block is prepended to.
+    const indent = ' '.repeat((jsdocNode ?? anchorNode).range().start.column);
     if (jsdocNode) {
         const block = jsdocNode.text();
-        if (block.includes(tagText))
+        if (block.match(new RegExp(`(^|\\n)\\s*\\*?\\s*@${tag}\\b`)))
             return source;
-        // Determine the indent of the closing */ line
-        const closeOffset = block.lastIndexOf('*/');
-        const beforeClose = block.slice(0, closeOffset);
-        // The whitespace prefix of the closing `*/` line
-        const linePrefix = beforeClose.match(/([^\n]*)$/)?.[1] ?? ' ';
-        const merged = block.slice(0, closeOffset - linePrefix.length) +
-            `${linePrefix}* ${tagText}\n${linePrefix}*/`;
-        return root.commitEdits([jsdocNode.replace(merged)]);
+        const innerLines = block
+            .replace(/^\/\*\*/, '')
+            .replace(/\s*\*\/\s*$/, '')
+            .split('\n')
+            .map((line) => line.replace(/^\s*\*? ?/, '').trimEnd());
+        while (innerLines.length > 0 && innerLines[0] === '')
+            innerLines.shift();
+        while (innerLines.length > 0 && innerLines[innerLines.length - 1] === '')
+            innerLines.pop();
+        // Prefix every physical line (including multi-line tag content) with ` * `.
+        const allLines = [...innerLines, ...tagText.split('\n')];
+        const body = allLines
+            .map((line) => (line.length > 0 ? `${indent} * ${line}` : `${indent} *`))
+            .join('\n');
+        const merged = `/**\n${body}\n${indent} */`;
+        // Own-line comment: a clean node replace suffices.
+        if (jsdocNode.range().end.line !== anchorNode.range().start.line) {
+            return root.commitEdits([jsdocNode.replace(merged)]);
+        }
+        // Same-line `/** x */ prop`: a node replace swaps only the comment text and
+        // leaves the declaration packed onto the closing `*/` line. Splice manually
+        // — drop the inline gap and start the declaration on its own indented line.
+        const start = jsdocNode.range().start.index;
+        const end = jsdocNode.range().end.index;
+        const tail = source.slice(end).replace(/^[^\S\n]+/, '');
+        return `${source.slice(0, start)}${merged}\n${indent}${tail}`;
     }
-    // No existing JSDoc — create one before the anchor node.
-    const col = anchorNode.range().start.column;
-    const indent = ' '.repeat(col);
+    // No existing JSDoc — create one before the anchor node. Prefix EVERY physical
+    // line of the tag (multi-line content too) with ` * `, mirroring the merge
+    // branch above. Without this, a multi-line first tag left continuation lines
+    // at column 0 — malformed JSDoc that also broke the re-parse for any tag
+    // appended to the same declaration in a later pass.
     const at = anchorNode.range().start.index;
-    const blockText = `/**\n${indent} * ${tagText}\n${indent} */\n${indent}`;
+    const body = tagText
+        .split('\n')
+        .map((line) => (line.length > 0 ? `${indent} * ${line}` : `${indent} *`))
+        .join('\n');
+    const blockText = `/**\n${body}\n${indent} */\n${indent}`;
     return source.slice(0, at) + blockText + source.slice(at);
 }
+// Fast membership set for tag-name lookups (typed as strings so an arbitrary
+// captured `@word` can be tested without a cast). Derived from REFINE_TAGS so
+// it stays in sync with the union automatically.
+const REFINE_TAG_SET = new Set(REFINE_TAGS);
+/**
+ * Remove the refine-managed tag spans (`@useWhen`, `@avoidWhen`, `@pitfalls`,
+ * `@remarks`, `@example` — see {@link REFINE_TAGS}) from every JSDoc block in
+ * `source`, leaving each block's prose description and any non-refine tags
+ * intact.
+ *
+ * Used to feed an annotated config module back to the model as grounding
+ * without echoing the routing tags this package itself wrote across earlier
+ * refine iterations — those are documentation, not the implementation the model
+ * should ground runtime claims in. Unlike a blanket JSDoc strip, this preserves
+ * genuine hand-authored docs (e.g. validation notes on a `defineConfig` helper),
+ * which are exactly the runtime-behavior grounding we want to keep.
+ *
+ * Handles single-line (`/** @tag x *​/`) as well as multi-line blocks: each block
+ * is reduced to its inner content (opener/closer and ` * ` gutter dropped) before
+ * tags are matched, so an inline opener can't hide a tag. The block-matching
+ * regex is non-greedy, and writeback escapes a literal close sequence in content
+ * to `*\/`, so an escaped sequence inside a kept line never terminates early.
+ */
+export function stripRefineTags(source) {
+    return source.replace(/\/\*\*[\s\S]*?\*\//g, (block, offset) => {
+        // Indent of the line the block opens on, for a clean re-wrap when we rebuild.
+        const lineStart = source.lastIndexOf('\n', offset) + 1;
+        const indent = source.slice(lineStart, offset).match(/^\s*/)?.[0] ?? '';
+        return stripRefineTagsFromBlock(block, indent);
+    });
+}
+/**
+ * Strip refine-tag spans from one JSDoc block. Returns the block unchanged when
+ * it holds no refine tag (preserving hand-authored formatting), the empty string
+ * when nothing but refine tags remain (the whole block is dropped), or a clean
+ * re-wrapped block at `indent` otherwise. A `@tag` line and the lines following
+ * it (its continuation) form one span; a non-refine `@tag` closes any open span.
+ */
+function stripRefineTagsFromBlock(block, indent) {
+    // Reduce to inner content so tag detection is independent of how the block is
+    // wrapped: drop the `/**` opener and `*/` closer (own-line OR inline, as in a
+    // single-line `/** @tag x */`), then the per-line ` * ` gutter.
+    const inner = block.replace(/^\s*\/\*\*/, '').replace(/\*\/\s*$/, '');
+    const lines = inner.split('\n').map((line) => line.replace(/^\s*\*? ?/, '').trimEnd());
+    const kept = [];
+    let dropping = false;
+    let droppedAny = false;
+    for (const line of lines) {
+        const tagMatch = line.match(/^@(\w+)\b/);
+        if (tagMatch) {
+            dropping = REFINE_TAG_SET.has(tagMatch[1] ?? '');
+        }
+        if (dropping) {
+            droppedAny = true;
+            continue;
+        }
+        kept.push(line);
+    }
+    if (!droppedAny)
+        return block; // no refine tag — keep original formatting verbatim
+    while (kept.length > 0 && kept[0] === '')
+        kept.shift();
+    while (kept.length > 0 && kept[kept.length - 1] === '')
+        kept.pop();
+    if (kept.length === 0)
+        return ''; // block was nothing but refine tags
+    const body = kept
+        .map((line) => (line.length > 0 ? `${indent} * ${line}` : `${indent} *`))
+        .join('\n');
+    return `/**\n${body}\n${indent} */`;
+}
 /**
  * Parse the leading JSDoc block of a named export declaration and return a
  * map of the RefineTag values found in it.
@@ -134,13 +280,35 @@ export function readJsDocTags(source, declName) {
     if (!jsdocNode)
         return {};
     const block = jsdocNode.text();
+    // Strip the block to inner content lines (no `/** */` wrapper, no ` * `
+    // prefixes), then walk them: a known `@tag` line opens a capture and the
+    // following non-tag lines are its continuation. This keeps multi-line tag
+    // content (e.g. bullet lists) intact instead of truncating at the first
+    // newline — otherwise a refined `@pitfalls` with several bullets would lose
+    // everything past line one when re-extracted into SKILL.md.
+    const innerLines = block
+        .replace(/^\/\*\*/, '')
+        .replace(/\s*\*\/\s*$/, '')
+        .split('\n')
+        .map((line) => line.replace(/^\s*\*? ?/, '').trimEnd());
+    const collected = {};
+    let current;
+    for (const line of innerLines) {
+        const tagMatch = line.match(/^@(\w+)\s?(.*)$/);
+        const matchedTag = tagMatch ? REFINE_TAGS.find((t) => t === tagMatch[1]) : undefined;
+        if (matchedTag) {
+            current = matchedTag;
+            collected[current] = [tagMatch[2] ?? ''];
+        }
+        else if (current) {
+            collected[current].push(line);
+        }
+    }
     const result = {};
     for (const tag of REFINE_TAGS) {
-        const pattern = new RegExp(`@${tag}\\s+(.+?)(?:\\s*\\n|\\s*\\*\\/|$)`, 'm');
-        const hit = block.match(pattern);
-        if (hit) {
-            result[tag] = hit[1]?.trim() ?? '';
-        }
+        const lines = collected[tag];
+        if (lines)
+            result[tag] = unescapeJsDocClose(lines.join('\n').trim());
     }
     return result;
 }

package/dist/refine/ast-edit.js.map

@@ -1 +1 @@
-{"version":3,"file":"ast-edit.js","sourceRoot":"","sources":["../../src/refine/ast-edit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ast-edit.js","sourceRoot":"","sources":["../../src/refine/ast-edit.ts"],"names":[],"mappings":"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"}

package/dist/refine/config-source.d.ts

@@ -0,0 +1,81 @@
+import type { ExtractedSkill } from '../types.js';
+import type { DraftedFix, RefineSource, TargetLocation } from './types.js';
+export interface ConfigRefineSourceOptions {
+    /** Path to the TypeScript file declaring the config type. */
+    configFile: string;
+    /** Name of the exported interface or object-type alias to document. */
+    typeName: string;
+    /** Skill name (defaults to the package name, then `typeName`). */
+    name?: string;
+    /** Skill description (defaults to the package.json description). */
+    description?: string;
+    /**
+     * Globs pointing at the code that CONSUMES this config (e.g. the CLI/filter
+     * logic). Their contents are fed to the draft model as an implementation
+     * reference so it can state CORRECT runtime behavior instead of guessing it
+     * from the type alone. Token-capped. Without grounding the model is told not
+     * to assert unverifiable runtime semantics.
+     */
+    groundingGlobs?: string[];
+}
+/**
+ * {@link RefineSource} for a TypeScript configuration surface.
+ *
+ * Reads the consumer's config type with {@link extractConfigSurface}, exposes it
+ * as a single `config` surface in an {@link ExtractedSkill}, and writes routing
+ * tags back as JSDoc onto the type's individual property declarations. Unlike
+ * the CLI source — whose routing lives at the command (surface) level — a config
+ * surface is documented per-OPTION: each fix targets one property by its
+ * dot-path `configKey` (e.g. `outDir`, `components.prefix`), routed through
+ * {@link upsertPropertyJsDocTag}.
+ *
+ * It also enriches the skill from the package.json nearest the config file (its
+ * description, keywords, repository) and a sibling README, supplying the audit
+ * context the metadata checks (F1/F2/F3/E5/W4/W5/W6) score against — without it
+ * a config skill forfeits those points even when the package already carries
+ * the data.
+ */
+export declare class ConfigRefineSource implements RefineSource {
+    private readonly opts;
+    /** Cached metadata, populated by {@link extract} (which the loop runs first). */
+    private metadata;
+    /** Cached surface, populated by {@link extract}; read by {@link guidance}. */
+    private surface;
+    /** Cached implementation-reference grounding, populated by {@link extract}. */
+    private grounding;
+    constructor(opts: ConfigRefineSourceOptions);
+    extract(): Promise<ExtractedSkill>;
+    /**
+     * Map an improvement target to its on-disk location. Config targets carry the
+     * option's dot-path `configKey` as `name` (kind `config-option`); the config
+     * type holds them, so the file is always the config file and the declName is
+     * the type. A `config-example` target points at the same file with no path.
+     */
+    resolveTargetLocation(target: {
+        name: string;
+        kind: string;
+        file?: string;
+    }): TargetLocation | undefined;
+    applyFixes(fixes: readonly DraftedFix[]): Promise<void>;
+    /**
+     * Drafting conventions passed to the model each iteration. Scopes every
+     * routing tag to the single named option, constrains claims to what the type
+     * and provided context can support (the model sees the type, NOT the code that
+     * consumes the config, so unconstrained drafting invents wrong runtime
+     * semantics), and tells it how to draft the `@example` config file. Built from
+     * the cached surface that {@link extract} populates first.
+     */
+    guidance(): string;
+    private loadMetadata;
+    /**
+     * Sibling example path for the config file: same directory, the config file's
+     * base name with any `.ts`/`.tsx`/`.mts`/`.cts` extension replaced by
+     * `.example.ts` (e.g. `z2f.config.ts` → `z2f.config.example.ts`,
+     * `config.ts` → `config.example.ts`).
+     */
+    private exampleFilePath;
+    private loadGrounding;
+    /** Nearest ancestor directory of the config file that holds a package.json. */
+    private findPackageDir;
+}
+//# sourceMappingURL=config-source.d.ts.map

package/dist/refine/config-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-source.d.ts","sourceRoot":"","sources":["../../src/refine/config-source.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE3E,MAAM,WAAW,yBAAyB;IACxC,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IAQzC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPjC,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAsB;IACtC,8EAA8E;IAC9E,OAAO,CAAC,OAAO,CAAqC;IACpD,+EAA+E;IAC/E,OAAO,CAAC,SAAS,CAAM;IAEvB,YAA6B,IAAI,EAAE,yBAAyB,EAAI;IAE1D,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAgDvC;IAED;;;;;OAKG;IACH,qBAAqB,CAAC,MAAM,EAAE;QAC5B,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,cAAc,GAAG,SAAS,CAS7B;IAEK,UAAU,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA2C5D;IAED;;;;;;;OAOG;IACH,QAAQ,IAAI,MAAM,CAoBjB;YAQa,YAAY;IAiB1B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;YAcT,aAAa;IAyC3B,+EAA+E;IAC/E,OAAO,CAAC,cAAc;CAUvB"}