@webwriter/guidance 1.0.0 → 1.1.0

package/docs.mjs

@@ -3,7 +3,9 @@ import {join, relative, sep} from "node:path"
 import {fileURLToPath, pathToFileURL} from "node:url"
 
 const checkoutDocs = fileURLToPath(new URL("../domeditor/docs/widgets/", import.meta.url))
+const checkoutKeywords = new URL("../domeditor/src/widget-keywords.json", import.meta.url)
 const snapshot = new URL("./dist/widget-docs.json", import.meta.url)
+const readJSON = file => JSON.parse(readFileSync(file, "utf8"))
 
 function readWidgetDocs(directory = checkoutDocs) {
   return readdirSync(directory, {withFileTypes: true}).flatMap(entry => {
@@ -16,11 +18,15 @@ function readWidgetDocs(directory = checkoutDocs) {
 }
 
 export function loadWidgetDocs() {
-  return existsSync(checkoutDocs) ? readWidgetDocs() : JSON.parse(readFileSync(snapshot, "utf8"))
+  return existsSync(checkoutDocs) ? readWidgetDocs() : readJSON(snapshot).docs
+}
+
+export function loadWidgetKeywords() {
+  return existsSync(checkoutKeywords) ? readJSON(checkoutKeywords) : readJSON(snapshot).widgetKeywords
 }
 
 if(process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
   const docs = readWidgetDocs().sort((a, b) => a.id.localeCompare(b.id))
   mkdirSync(new URL(".", snapshot), {recursive: true})
-  writeFileSync(snapshot, JSON.stringify(docs) + "\n")
+  writeFileSync(snapshot, JSON.stringify({docs, widgetKeywords: readJSON(checkoutKeywords)}) + "\n")
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@webwriter/guidance",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "WebWriter widget documentation search and coding agent skill",
   "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "https://github.com/webwriter-app/webwriter.git",
+    "url": "git+https://github.com/webwriter-app/webwriter.git",
     "directory": "@webwriter/guidance"
   },
   "publishConfig": {
@@ -16,7 +16,7 @@
     "node": ">=22.20.0"
   },
   "bin": {
-    "webwriter-guidance": "./cli.mjs"
+    "webwriter-guidance": "cli.mjs"
   },
   "files": [
     "cli.mjs",

package/skills/webwriter-guidance/SKILL.md

@@ -1,12 +1,16 @@
 ---
 name: webwriter-guidance
-description: Search and retrieve WebWriter's widget documentation. Use before answering WebWriter widget questions or implementing changes that rely on its documented widget interfaces, including package exports, framework adapters, editing controls, state, styling, and live sessions.
+description: Search and retrieve WebWriter's widget documentation and audit or rework existing widgets using their capability badges. Use for WebWriter widget questions and changes involving documented widget interfaces, including package exports, framework adapters, editing controls, state, styling, and live sessions.
 ---
 
 # WebWriter Guidance
 
 Use the WebWriter widget guides, tutorials, and interface reference through the `@webwriter/guidance` CLI. Run it with Node.js 22.20 or newer.
 
+## Rework an existing widget
+
+For a widget audit, modernization, or rework, use the [widget rework checklist](references/widget-rework.md). Resolve the manifest's badges to their guides, verify the claims in scope, and ask the user to decide open design questions while continuing independent fixes.
+
 ## Search
 
 Search for one capability or API at a time. Use WebWriter terminology and exact identifiers when known.

package/skills/webwriter-guidance/references/widget-rework.md

@@ -0,0 +1,40 @@
+# Widget rework
+
+## Establish the current behavior
+
+Identify the target widget exports, their package manifest, existing tests and fixtures, and the author and reader tasks affected by the request. Start with the declared badges and add checks for capabilities the request affects. Use the whole catalog for a broad review and mark unrelated capabilities out of scope.
+
+```sh
+npx -y @webwriter/guidance badges ./package.json
+npx -y @webwriter/guidance badges
+npx -y @webwriter/guidance retrieve "reference/keywords,guides/focus,guides/sharing"
+```
+
+`badges` uses the documentation's badge-to-guide mapping and reports guide IDs for `retrieve`. With a manifest path it resolves declared keywords, retaining specific language tags, formats, and migration versions. Check the keyword reference for valid values. Retrieve the guides for the checks in scope. For a package with several widget exports, verify which exports support each relevant package-level claim.
+
+Keep an audit row for each relevant badge and each declared value. Record the affected export, expected behavior, observed behavior and evidence, and status. Use `Verified`, `Gap`, `Needs decision`, `Out of scope`, or `Unverified` when evidence is unavailable. A manifest entry alone is a claim. Verify it against behavior.
+
+## Work through the capabilities
+
+| Badges | Evidence to collect | Decisions for the human when open |
+| --- | --- | --- |
+| Editable, Configurable, Has content | Exercise author controls in edit mode and reader controls in read mode. Save and reopen authored text and nested widgets. Check option defaults, actions, and undo. | What authors can change, which controls to expose, and accepted content. |
+| Pointer, Keyboard, Touch input | Complete the primary task with each claimed input method. Check activation, focus order, visible focus, and interaction with editor selection. | Interaction changes such as new controls, gestures, or a different task flow. |
+| Responsive, Themeable, Printable, Content languages | Check narrow and wide document widths, inherited theme or documented styling hooks, print preview, and each claimed language. | What gets priority in a narrow layout, what appears in print, public styling hooks, and supported languages. |
+| Stateful, Reactive | Check saved state after reopening and undo, temporary state during interaction, and updates between connected widgets. | What persists or resets and which signals form a public interface. |
+| Shareable, Distributable | Exercise the claimed scopes with participants in distinct roles or groups. Check permissions, submission, and what the host can see. | Default sharing scope, participation permissions, and what participants and hosts can see. |
+| Converts from, Converts to, Migrates from | Use a fixture per claimed format or version. Inspect what survives conversion or migration and how invalid imports are handled. | Supported formats and versions and acceptable data loss. |
+| Online variants, Dynamic loading, Shared dependencies, Standalone | Exercise the claimed modes online and offline. Check optional imports, dependency sharing, and standalone use on a plain page as applicable. | Network requirements, offline behavior, and where standalone results are stored. |
+| Testable, Widget, purpose badges | Check manifest exports and discovery, run exported tests in the Developer console when claimed, and compare the purpose badge with the reader's primary task. | Intended audience and purpose, and whether to publish. |
+
+## Ask and keep working
+
+Use the request, accepted decisions, documented behavior, and existing tests or saved content to establish intent. On a rework, fix gaps with a clear expected outcome within scope, including compatibility and accessibility regressions. On an audit, report the findings. Preserve existing behavior and authored data when the request leaves them open.
+
+When fixing a gap would choose a user-visible design, change a documented default, or add or drop a supported capability, ask before making that change unless the user already decided it. Group related questions. State the observed behavior, give two or three concrete options with tradeoffs when available, and recommend one. Use the host's question mechanism if available. While the answer is pending, continue independent fixes and verification. Keep dependent changes pending until the user answers. If the host requires a reply before work can resume, complete the independent work first and ask with a summary of what remains.
+
+For example, if a poll's default sharing scope is unclear, ask who should see votes by default and explain the individual, group, and everyone options. While waiting, verify keyboard submission and that existing saved polls still open, provided those checks do not depend on the choice.
+
+## Verify and report
+
+Test the affected flows with a fresh widget and representative saved content. Recheck the declared badge claims against the result. Update manifest keywords to reflect verified capabilities within the agreed scope. If a badge is unsupported and retaining or dropping the capability is a design decision, record the gap and ask. Report completed fixes and evidence alongside any pending decisions or unverified claims.