Perform code optimization and document cleanup (#1)

## Summary
- add repository-wide quality tooling and verification scaffolding, including CI workflows, pnpm workspace setup, ESLint/Prettier/markdown checks, and generated-output verification helpers
- reorganize skill sources and generation flow by introducing canonical `_source` variants, generator/manifests, reusable helper abstractions, and shared web-automation/browser utilities
- clean up and expand documentation so the root README flows into docs and skill docs, with clearer development, reviewer, installer, and workflow guidance

## Notable changes
- docs flow and consistency cleanup across `README.md`, `docs/README.md`, and related docs
- new scripts for `check`, docs verification, generated-file verification, shell portability, and safe directory replacement
- refactors in Atlassian and web-automation skill runtimes to reduce duplication and centralize reusable code
- changelog, development documentation, and CI surface updates

## Test Plan
- [ ] `pnpm run check`
- [ ] review generated/manifests and skill sync outputs
- [ ] smoke-check docs flow from `README.md` to `docs/README.md` to skill docs

## Notes
- this branch currently includes tracked `skills/web-automation/shared/node_modules` content that should be reviewed carefully as potentially noisy/accidental committed artifacts

Co-authored-by: Stefano Fiorini <stefano.fiorini@firsthorizon.com>
Reviewed-on: #1

skills/atlassian/opencode/scripts/src/adf.ts

@@ -1,3 +1,4 @@
+// ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/atlassian/shared/scripts/ and run `pnpm run sync:pi`.
 const TEXT_NODE = "text";
 
 function textNode(text: string) {

skills/atlassian/opencode/scripts/src/cli.ts

@@ -1,8 +1,10 @@
+// ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/atlassian/shared/scripts/ and run `pnpm run sync:pi`.
 import process from "node:process";
 import { pathToFileURL } from "node:url";
 
 import { Command } from "commander";
 
+import { resolveFormat } from "./command-helpers.js";
 import { createConfluenceClient } from "./confluence.js";
 import { loadConfig } from "./config.js";
 import { readWorkspaceFile } from "./files.js";
@@ -10,7 +12,7 @@ import { runHealthCheck } from "./health.js";
 import { createJiraClient } from "./jira.js";
 import { writeOutput } from "./output.js";
 import { runRawCommand } from "./raw.js";
-import type { FetchLike, OutputFormat, Writer } from "./types.js";
+import type { FetchLike, Writer } from "./types.js";
 
 type CliContext = {
   cwd?: string;
@@ -20,10 +22,6 @@ type CliContext = {
   stderr?: Writer;
 };
 
-function resolveFormat(format: string | undefined): OutputFormat {
-  return format === "text" ? "text" : "json";
-}
-
 function createRuntime(context: CliContext) {
   const cwd = context.cwd ?? process.cwd();
   const env = context.env ?? process.env;

skills/atlassian/opencode/scripts/src/command-helpers.ts

@@ -0,0 +1,25 @@
+// ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/atlassian/shared/scripts/ and run `pnpm run sync:pi`.
+import type { CommandOutput, OutputFormat } from "./types.js";
+
+/**
+ * Produce the standard dry-run response payload for write operations.
+ *
+ * Use this when `--dry-run` is passed to skip the actual API call and
+ * echo the pending request back to the caller.
+ *
+ * @example
+ *   if (input.dryRun) return dryRunResponse(request);
+ */
+export function dryRunResponse<T>(data: T): CommandOutput<T> {
+  return { ok: true, dryRun: true, data };
+}
+
+/**
+ * Resolve the `--format` CLI option to a typed OutputFormat.
+ *
+ * Returns `"text"` only for the exact string `"text"`;
+ * all other values (including `undefined`) fall back to `"json"`.
+ */
+export function resolveFormat(format: string | undefined): OutputFormat {
+  return format === "text" ? "text" : "json";
+}

skills/atlassian/opencode/scripts/src/config.ts

@@ -1,3 +1,4 @@
+// ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/atlassian/shared/scripts/ and run `pnpm run sync:pi`.
 import path from "node:path";
 
 import { config as loadDotEnv } from "dotenv";

skills/atlassian/opencode/scripts/src/confluence.ts

@@ -1,3 +1,5 @@
+// ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/atlassian/shared/scripts/ and run `pnpm run sync:pi`.
+import { dryRunResponse } from "./command-helpers.js";
 import { sendJsonRequest } from "./http.js";
 import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
 
@@ -177,13 +179,7 @@ export function createConfluenceClient(options: ConfluenceClientOptions) {
         },
       };
 
-      if (input.dryRun) {
-        return {
-          ok: true,
-          dryRun: true,
-          data: request,
-        };
-      }
+      if (input.dryRun) return dryRunResponse(request);
 
       const raw = await sendJsonRequest({
         config,
@@ -223,13 +219,7 @@ export function createConfluenceClient(options: ConfluenceClientOptions) {
         },
       };
 
-      if (input.dryRun) {
-        return {
-          ok: true,
-          dryRun: true,
-          data: request,
-        };
-      }
+      if (input.dryRun) return dryRunResponse(request);
 
       const raw = await sendJsonRequest({
         config,
@@ -266,13 +256,7 @@ export function createConfluenceClient(options: ConfluenceClientOptions) {
         },
       };
 
-      if (input.dryRun) {
-        return {
-          ok: true,
-          dryRun: true,
-          data: request,
-        };
-      }
+      if (input.dryRun) return dryRunResponse(request);
 
       const raw = await sendJsonRequest({
         config,

skills/atlassian/opencode/scripts/src/files.ts

@@ -1,3 +1,4 @@
+// ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/atlassian/shared/scripts/ and run `pnpm run sync:pi`.
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 

skills/atlassian/opencode/scripts/src/health.ts

@@ -1,3 +1,4 @@
+// ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/atlassian/shared/scripts/ and run `pnpm run sync:pi`.
 import { createJsonHeaders, createStatusError } from "./http.js";
 import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
 

skills/atlassian/opencode/scripts/src/http.ts

@@ -1,3 +1,4 @@
+// ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/atlassian/shared/scripts/ and run `pnpm run sync:pi`.
 import { createBasicAuthHeader } from "./config.js";
 import type { AtlassianConfig, FetchLike } from "./types.js";
 

skills/atlassian/opencode/scripts/src/jira.ts

@@ -1,4 +1,6 @@
+// ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/atlassian/shared/scripts/ and run `pnpm run sync:pi`.
 import { markdownToAdf } from "./adf.js";
+import { dryRunResponse } from "./command-helpers.js";
 import { sendJsonRequest } from "./http.js";
 import type { AtlassianConfig, CommandOutput, FetchLike, JiraIssueSummary } from "./types.js";
 
@@ -161,13 +163,7 @@ export function createJiraClient(options: JiraClientOptions) {
         },
       });
 
-      if (input.dryRun) {
-        return {
-          ok: true,
-          dryRun: true,
-          data: request,
-        };
-      }
+      if (input.dryRun) return dryRunResponse(request);
 
       const raw = await send("POST", "/rest/api/3/issue", request.body);
       return { ok: true, data: raw };
@@ -192,13 +188,7 @@ export function createJiraClient(options: JiraClientOptions) {
         fields,
       });
 
-      if (input.dryRun) {
-        return {
-          ok: true,
-          dryRun: true,
-          data: request,
-        };
-      }
+      if (input.dryRun) return dryRunResponse(request);
 
       await send("PUT", `/rest/api/3/issue/${input.issue}`, request.body);
       return {
@@ -215,13 +205,7 @@ export function createJiraClient(options: JiraClientOptions) {
         body: markdownToAdf(input.body),
       });
 
-      if (input.dryRun) {
-        return {
-          ok: true,
-          dryRun: true,
-          data: request,
-        };
-      }
+      if (input.dryRun) return dryRunResponse(request);
 
       const raw = await send("POST", `/rest/api/3/issue/${input.issue}/comment`, request.body);
       return {
@@ -242,13 +226,7 @@ export function createJiraClient(options: JiraClientOptions) {
         },
       );
 
-      if (input.dryRun) {
-        return {
-          ok: true,
-          dryRun: true,
-          data: request,
-        };
-      }
+      if (input.dryRun) return dryRunResponse(request);
 
       await send("POST", `/rest/api/3/issue/${input.issue}/transitions`, request.body);
       return {

skills/atlassian/opencode/scripts/src/output.ts

@@ -1,3 +1,4 @@
+// ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/atlassian/shared/scripts/ and run `pnpm run sync:pi`.
 import type { CommandOutput, OutputFormat, Writer } from "./types.js";
 
 function renderText(payload: CommandOutput<unknown>) {

skills/atlassian/opencode/scripts/src/raw.ts

@@ -1,3 +1,5 @@
+// ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/atlassian/shared/scripts/ and run `pnpm run sync:pi`.
+import { dryRunResponse } from "./command-helpers.js";
 import { readWorkspaceFile } from "./files.js";
 import { sendJsonRequest } from "./http.js";
 import type { AtlassianConfig, CommandOutput, FetchLike } from "./types.js";
@@ -61,13 +63,7 @@ export async function runRawCommand(
     ...(body === undefined ? {} : { body }),
   };
 
-  if (input.dryRun) {
-    return {
-      ok: true,
-      dryRun: true,
-      data: request,
-    };
-  }
+  if (input.dryRun) return dryRunResponse(request);
 
   const data = await sendJsonRequest({
     config,

skills/atlassian/opencode/scripts/src/types.ts

@@ -1,3 +1,4 @@
+// ⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in skills/atlassian/shared/scripts/ and run `pnpm run sync:pi`.
 export type AtlassianConfig = {
   baseUrl: string;
   jiraBaseUrl: string;