@webex/internal-plugin-call-ai-summary 3.12.0-next.59 → 3.12.0-next.60

package/.sdd/manifest.json

@@ -0,0 +1,408 @@
+{
+  "manifest_version": 1,
+  "repository": {
+    "name": "@webex/internal-plugin-call-ai-summary",
+    "purpose": "A Webex internal plugin for AI-generated call summary retrieval. Resolves a Pragya container for a call, fetches AI Bridge summary, notes, action-item, and transcript content, and returns it decrypted through the Webex KMS encryption plugin.",
+    "category": "cat1-legacy",
+    "primary_languages": [
+      "typescript"
+    ]
+  },
+  "topology": "Single-repo",
+  "commands": {
+    "install": {
+      "command": "yarn install",
+      "source_file": "package.json",
+      "role": "install"
+    },
+    "build": {
+      "command": "yarn build",
+      "source_file": "package.json",
+      "role": "build"
+    },
+    "compile": {
+      "command": "yarn build:src",
+      "source_file": "package.json",
+      "role": "compile"
+    },
+    "lint": {
+      "command": "yarn test:style",
+      "source_file": "package.json",
+      "role": "lint"
+    },
+    "unit-test": {
+      "command": "yarn test:unit",
+      "source_file": "package.json",
+      "role": "unit-test"
+    },
+    "test-all": {
+      "command": "yarn test",
+      "source_file": "package.json",
+      "role": "other"
+    },
+    "deploy": {
+      "command": "yarn deploy:npm",
+      "source_file": "package.json",
+      "role": "deploy"
+    },
+    "manual-pragya-check": {
+      "command": "node src/manual-pragya-api-test.js",
+      "source_file": "src/manual-pragya-api-test.js",
+      "role": "other"
+    },
+    "manual-integration-check": {
+      "command": "node src/manual-integration-test.js",
+      "source_file": "src/manual-integration-test.js",
+      "role": "other"
+    }
+  },
+  "toolchain": [
+    {
+      "name": "node",
+      "version": ">=16",
+      "origin": "repo-config",
+      "source_file": "package.json"
+    },
+    {
+      "name": "yarn",
+      "version": "berry (workspace protocol)",
+      "origin": "repo-config",
+      "source_file": "package.json"
+    }
+  ],
+  "quality_gates": {
+    "code_coverage": {
+      "origin": "none",
+      "declared_by": "@riag (repository owner; verified in the 2026-09-23 bootstrap questionnaire that no repo-specific coverage gate applies to this package)"
+    }
+  },
+  "coverage_status_definitions": {
+    "specced": ">=80% public surface specced, drift <5% \u2014 spec is authoritative",
+    "partial": "40-80% specced \u2014 spec is a hint, cross-check code",
+    "untracked": "<40% specced \u2014 code is the source of truth"
+  },
+  "template_migration": {
+    "status": "validated",
+    "target_source": "repo-standards",
+    "target_source_commit": "d89a7fe59126ae3ad9bac9ca352aa7f12b4c85dc",
+    "detected_footprints": [
+      "ai-docs"
+    ],
+    "old_template_disposition": "retain",
+    "decided_by": "@riag",
+    "decided_at": "2026-09-23T05:24:48Z"
+  },
+  "spec_source_policy": {
+    "mode": "reconcile",
+    "migrated_source_disposition": "delete-after-validation",
+    "disposition_decided_by": "@riag",
+    "disposition_decided_at": "2026-09-23T15:20:00Z",
+    "decided_by": "@riag",
+    "decided_at": "2026-09-23T05:24:48Z",
+    "decision_record": ".generated/sdd/spec-source-policy/decision.md"
+  },
+  "spec_sources": [
+    {
+      "path": "ai-docs/ARCHITECTURE.md",
+      "scope": "repo",
+      "role": "superseded",
+      "canonical": false,
+      "use_by_agents": "source-for-reconciliation",
+      "canonical_target": "docs/architecture.md",
+      "post_migration_action": "delete-after-validation",
+      "deletion_status": "deleted",
+      "notes": "1189-line pre-implementation design/intent document. This entry routes its repo-scope half: sections 1-3, 8, 10 and 13 reconcile into docs/architecture.md, and section 1.2 Key Design Decisions reconciles into docs/adr/. Its module-scope half is routed by the separate src/ entry below. Section 6.4 pseudo-code and section 11.1 test-suite block are executable-contract units routed under the Migrated Executable Contract Gate and are not copied into canonical documents. Retained permanently as the audit trail; never a deletion candidate. DELETED 2026-09-23 after independent validation passed (codex, 0 blocking): content reconciled into the canonical docs, the drafted unit-test suite salvaged into test/unit/spec/ai-summary.ts, and the upstream wire samples salvaged into test/unit/fixture/responses.ts. Recoverable from commit 3db31e87c7."
+    },
+    {
+      "path": "ai-docs/ARCHITECTURE.md",
+      "scope": "module",
+      "module": "src/",
+      "role": "superseded",
+      "canonical": false,
+      "use_by_agents": "source-for-reconciliation",
+      "canonical_target": "src/docs/README.md",
+      "post_migration_action": "delete-after-validation",
+      "deletion_status": "deleted",
+      "notes": "Module-scope half of the same design document. Sections 4-7, 9, 11 and 12 (SDK method interfaces, DTOs, low-level design, wire-level request/response detail, error handling, testing strategy, package structure) reconcile into the module spec. Per-unit routing across both halves is authoritative in the source-fidelity inventories, not in this single primary route. DELETED 2026-09-23 after independent validation passed (codex, 0 blocking): content reconciled into the canonical docs, the drafted unit-test suite salvaged into test/unit/spec/ai-summary.ts, and the upstream wire samples salvaged into test/unit/fixture/responses.ts. Recoverable from commit 3db31e87c7."
+    },
+    {
+      "path": "ai-docs/AGENTS.md",
+      "scope": "repo",
+      "role": "superseded",
+      "canonical": false,
+      "use_by_agents": "source-for-reconciliation",
+      "canonical_target": "AGENTS.md",
+      "post_migration_action": "delete-after-validation",
+      "deletion_status": "deleted",
+      "notes": "Human-authored agent guidance plus API reference. Not a canonical overlap: it sits at ai-docs/AGENTS.md while the canonical agent entry is the package-root AGENTS.md, which does not currently exist. Documents only 5 public methods and omits getTranscript, which is corrected from src/ai-summary.ts. Retained permanently. DELETED 2026-09-23 after independent validation passed (codex, 0 blocking): content reconciled into the canonical docs, the drafted unit-test suite salvaged into test/unit/spec/ai-summary.ts, and the upstream wire samples salvaged into test/unit/fixture/responses.ts. Recoverable from commit 3db31e87c7."
+    },
+    {
+      "path": "README.md",
+      "scope": "repo",
+      "role": "source-material",
+      "canonical": false,
+      "use_by_agents": "source-for-reconciliation",
+      "canonical_target": "docs/getting-started.md",
+      "post_migration_action": "retain",
+      "deletion_status": "not-applicable",
+      "notes": "Native npm-facing package documentation and the only source documenting getTranscript, the error Cause/Recovery columns, the keyUrl-over-encryptionKeyUrl fallback rule, and the end-to-end Janus-to-Pragya usage example. Install/Prerequisites/Development/Manual Testing reconcile into docs/getting-started.md; Overview into docs/index.md; the API section is contract evidence for the module spec. Remains the authoritative npm readme in place and is never a deletion candidate. Its stale Package Structure block was corrected in place at publication on 2026-09-23: pre-correction sha256 6346708224c1d3ad8371e15190f6125571e70a85d64d00a50f4cad04a14908e7, post-correction sha256 981b206a902652e389cca97e74f8012ab919fc22ac63d7aa6d2d92147a821dce. The source-fidelity inventories record the pre-correction source state, which is the migration basis; unit SF-0050 is the stale record of the removed claim."
+    }
+  ],
+  "modules": [
+    {
+      "path": "src/",
+      "coverage_status": "Specced",
+      "coverage_evidence": "Public surface 100% specced at src/docs/README.md: all six public methods and all ten exported types are documented, and independent validation (codex, 2026-09-23) reported B1 signature match and B4 type match PASS with no drift. Behavior is verified by 38 unit tests in test/unit/spec/ai-summary.ts covering plugin registration, every public method, the summaryData.data flattening transform, the keyUrl precedence rule, all validation branches and each normalized error mapping. No requirement is without unit evidence.",
+      "canonical_spec": "src/docs/README.md",
+      "contracts": {
+        "provides": [
+          "aisummary-sdk",
+          "aisummary-package-entry",
+          "aisummary-types"
+        ],
+        "requires": [
+          "pragya-containers-http",
+          "ai-bridge-content-http",
+          "webex-encryption-sdk"
+        ]
+      },
+      "last_assessed": "2026-09-23",
+      "section_profile": {
+        "has_ui": false,
+        "crosses_service_boundaries": true,
+        "enforces_domain_rules": false,
+        "is_concurrent_async": true,
+        "owns_persistence": false,
+        "returns_caller_errors": true,
+        "has_design_tradeoff": true,
+        "stateful_transitions": false,
+        "exposes_wire_protocol": false,
+        "ui_multi_screen": false,
+        "large_data_model": false,
+        "has_tiers": false,
+        "module_specific_conventions": false,
+        "published_package": true,
+        "embedded_in_host": false,
+        "holds_client_state": false,
+        "has_submodules": false,
+        "has_submodules_computed_by": "scripts/module_tree.py",
+        "has_submodules_computed_at": "2026-09-23T05:24:48Z",
+        "resolved_by": "claude-code/claude-opus-5[1m] (host metadata; code-grounded from src/ai-summary.ts, src/types.ts, src/index.ts and package.json)",
+        "resolved_at": "2026-09-23T05:24:48Z"
+      },
+      "source_policy": {
+        "mode": "reconcile",
+        "existing_sources": [
+          "ai-docs/ARCHITECTURE.md",
+          "ai-docs/AGENTS.md",
+          "README.md"
+        ],
+        "conflict_status": "resolved",
+        "decision_record": ".generated/sdd/spec-source-policy/decision.md"
+      }
+    }
+  ],
+  "contract_catalog": {
+    "index_path": "docs/architecture.md",
+    "definitions": {
+      "aisummary-sdk": {
+        "kind": "sdk",
+        "publication": "internal",
+        "source_kind": "repository-path",
+        "source": "src/ai-summary.ts",
+        "summary": "Internal Webex SDK plugin surface reached as webex.internal.aisummary, registered by registerInternalPlugin('aisummary', ...) in src/index.ts. Six public methods declared here: getContainer, getSummary, getNotes, getActionItems, getTranscriptUrl (synchronous) and getTranscript."
+      },
+      "aisummary-package-entry": {
+        "kind": "sdk",
+        "publication": "internal",
+        "source_kind": "repository-path",
+        "source": "src/index.ts",
+        "summary": "Package entry point. Calls registerInternalPlugin('aisummary', AISummary, {config}), imports @webex/internal-plugin-encryption for its side effects, and re-exports the plugin as the package default. Importing the package is what makes webex.internal.aisummary available."
+      },
+      "aisummary-types": {
+        "kind": "sdk",
+        "publication": "internal",
+        "source_kind": "repository-path",
+        "source": "src/types.ts",
+        "summary": "Ten exported TypeScript interfaces forming the typed request/response surface: PragyaSummaryData, PragyaContainerResponse, GetContainerOptions, GetSummaryContentOptions, SummaryContent, SummaryNotes, ActionItemSnippet, SummaryActionItems, TranscriptSnippet, TranscriptContent."
+      },
+      "pragya-containers-http": {
+        "kind": "http",
+        "publication": "published",
+        "source_kind": "external",
+        "source": "Webex service-catalog service 'pragya', resource 'containers/{containerId}' (AI_SUMMARY_SERVICE and AI_SUMMARY_CONTAINERS_RESOURCE in src/constants.ts)",
+        "summary": "Upstream Pragya container-lookup API consumed by getContainer. Owned by the Pragya service, not by this repository. The response nests summary URLs under summaryData.data, which getContainer flattens onto summaryData."
+      },
+      "ai-bridge-content-http": {
+        "kind": "http",
+        "publication": "published",
+        "source_kind": "external",
+        "source": "AI Bridge absolute URLs supplied at runtime by PragyaSummaryData: summaryUrl, notesUrl, actionItemsUrl and transcriptUrl",
+        "summary": "Upstream AI Bridge content endpoints consumed by getSummary, getNotes, getActionItems and getTranscript. Owned by AI Bridge, not by this repository. Returns KMS-encrypted content plus an optional per-response keyUrl that takes precedence over containerInfo.encryptionKeyUrl."
+      },
+      "webex-encryption-sdk": {
+        "kind": "sdk",
+        "publication": "internal",
+        "source_kind": "external",
+        "source": "@webex/internal-plugin-encryption (workspace package; webex.internal.encryption.decryptText)",
+        "summary": "Sibling workspace plugin providing KMS/JWE decryption. Consumed by the private _decryptContent helper for every content field returned by this module. Declared as a workspace dependency in package.json and imported for side effects in src/index.ts."
+      }
+    }
+  },
+  "spec_policy": {
+    "require_what_and_why": true,
+    "require_provenance": true,
+    "protected_specs": [
+      "src/docs/README.md"
+    ]
+  },
+  "validation": {
+    "generator_runtime": "claude-code",
+    "generator_model": "claude-opus-5[1m]",
+    "generator_runtime_source": "host-metadata",
+    "validator_runtime": "codex",
+    "validator_runtime_source": "invocation-input",
+    "validator_run_id": "01a0cd0c-f017-7f92-9179-5c6f54d46814",
+    "minimum_independence": "different-runtime",
+    "runtime_fallback_tier": "different-runtime",
+    "blocking_severities": [
+      "Blocking"
+    ],
+    "generator_run_id": "call-ai-summary-migration-20260923-052025",
+    "source_commit": "bc61c78ba5",
+    "base_ref": "main",
+    "head_ref": "ai-summary"
+  },
+  "layout": {
+    "sdd_root": ".sdd",
+    "docs_root": "docs",
+    "agent_entry_path": "AGENTS.md",
+    "standing_docs_root": "docs",
+    "spec_index_path": "docs/specs/README.md",
+    "module_docs_strategy": "source-local",
+    "module_docs_relative_path": "docs/README.md",
+    "module_docs_decision": {
+      "basis": "repo-standards-default",
+      "reason": "The package has no pre-existing module-local documentation convention. ai-docs/ holds repo-scope design documents rather than module specs, and it cannot serve as the standing docs root: the filesystem is case-insensitive, so the canonical lowercase docs/architecture.md would collide with the existing ai-docs/ARCHITECTURE.md, which the policy refuses as a case-variant pair rather than an overlap. standing_docs_root is additionally enum-locked to docs by the manifest schema. The source-local default src/docs/README.md therefore applies unchanged.",
+      "decided_by": "@riag",
+      "decided_at": "2026-09-23T05:24:48Z"
+    },
+    "repo_context_decision": {
+      "path": ".repo-context.json",
+      "schema_path": "schemas/repo-context.schema.json",
+      "action": "create",
+      "schema_action": "create",
+      "reason": "No repository operational-context manifest or schema exists in this package; both are created from verified repository evidence.",
+      "decided_by": "@riag",
+      "decided_at": "2026-09-23T05:24:48Z"
+    },
+    "artifact_decisions": [
+      {
+        "path": "docs/service.md",
+        "action": "omit",
+        "reason": "This package is a published SDK plugin library, not a deployable service. It has no deployment surface, no runtime of its own, and no infrastructure configuration.",
+        "decided_by": "@riag",
+        "decided_at": "2026-09-23T05:24:48Z"
+      },
+      {
+        "path": "api-specs/openapi.yaml",
+        "action": "omit",
+        "reason": "No repository-owned HTTP API exists. The package is a consumer of two upstream services (Pragya, AI Bridge) and publishes a JS/TS SDK surface, so contracts stay on ecosystem-native artifacts. An empty paths scaffold is an explicit blocker.",
+        "decided_by": "@riag",
+        "decided_at": "2026-09-23T05:24:48Z"
+      },
+      {
+        "path": "mkdocs.yml",
+        "action": "omit",
+        "reason": "No MkDocs publishing workflow exists for this package or the surrounding monorepo.",
+        "decided_by": "@riag",
+        "decided_at": "2026-09-23T05:24:48Z"
+      },
+      {
+        "path": "SECURITY.md",
+        "action": "omit",
+        "reason": "Security policy is owned at the webex-js-sdk repository root, not per package.",
+        "decided_by": "@riag",
+        "decided_at": "2026-09-23T05:24:48Z"
+      },
+      {
+        "path": "CONTRIBUTING.md",
+        "action": "omit",
+        "reason": "Contribution guidance is owned at the webex-js-sdk repository root, not per package.",
+        "decided_by": "@riag",
+        "decided_at": "2026-09-23T05:24:48Z"
+      },
+      {
+        "path": "CHANGELOG.md",
+        "action": "omit",
+        "reason": "The monorepo generates changelogs centrally through its release tooling; a package-level changelog would diverge from it.",
+        "decided_by": "@riag",
+        "decided_at": "2026-09-23T05:24:48Z"
+      },
+      {
+        "path": "CTO_CHECKLIST.yml",
+        "action": "omit",
+        "reason": "No deployable service, so the package does not participate in the CTO readiness workflow.",
+        "decided_by": "@riag",
+        "decided_at": "2026-09-23T05:24:48Z"
+      },
+      {
+        "path": "schemas/cto-checklist.schema.json",
+        "action": "omit",
+        "reason": "No CTO checklist is selected, so its matching schema is not required.",
+        "decided_by": "@riag",
+        "decided_at": "2026-09-23T05:24:48Z"
+      }
+    ],
+    "template_roots": {
+      "canonical": ".sdd/templates/repo-standards"
+    },
+    "repo_skills_root": ".sdd/skills",
+    "contract_index_path": "docs/architecture.md"
+  },
+  "tooling": {
+    "sdlc_skills": {
+      "install_mode": "copy",
+      "installed_at": "2026-09-23T05:24:48Z",
+      "plugins": [
+        "repo-annotation@2.0.3"
+      ]
+    }
+  },
+  "substrate": {
+    "source": "the org repo-readiness standards (the repo-standards substrate)",
+    "consumed": [
+      "lint/format configs",
+      "base AGENTS.md"
+    ],
+    "compliance_tier": "baseline"
+  },
+  "section_profiles": {
+    "repo": {
+      "owns_datastore": false,
+      "holds_client_state": false,
+      "components_interact": false,
+      "domain_data_across_components": false,
+      "caches_data": false,
+      "observability_convention": true,
+      "deploys_to_infra": false,
+      "shared_base_libs": true,
+      "is_monorepo": false,
+      "multi_platform": false,
+      "published_package": true,
+      "embedded_in_host": true,
+      "cross_repo_deps_material": true,
+      "security_arch_warranted": true,
+      "exposes_commands_or_artifacts": true
+    },
+    "resolved_by": "claude-code/claude-opus-5[1m] (host metadata; code-grounded from package.json, src/ and the routed source documents)",
+    "resolved_at": "2026-09-23T05:24:48Z"
+  },
+  "tests": {
+    "unit": {
+      "command_ref": "unit-test",
+      "dir": "test/unit/spec",
+      "framework": "jest"
+    }
+  }
+}

package/AGENTS.md

@@ -0,0 +1,218 @@
+<!-- sdd-generated-metadata
+doc_kind: agent-entry
+generated_from: agents@0.3.0
+generated_by: claude-code
+approved_by: "@riag"
+updated_at: 2026-09-23T14:03:22Z
+validation_status: pass
+-->
+
+# AI Agent Instructions
+
+This is an internal Cisco Webex plugin. As such, it does not strictly adhere to semantic versioning. Use at your own risk. If you're not working on one of our first party clients, please look at our developer api and stick to our public plugins.
+
+Internal Webex JS SDK plugin for retrieving AI-generated call summaries, notes, action items, and transcript URLs from the Pragya and AI Bridge services.
+
+## Scope of this file
+
+This file covers **only** `@webex/internal-plugin-call-ai-summary`. The repository-root
+`AGENTS.md` owns monorepo-wide rules — Node toolchain, workspace command forms, cross-plugin
+search and refactoring guidance — and stays authoritative for them. Read the root file first; this
+file adds package-specific facts and records the two places where this package differs from the
+repository-wide generalization.
+
+Package-level agent entries are the established convention here: `packages/calling/AGENTS.md` and
+`packages/@webex/contact-center/AGENTS.md` sit at the same position.
+
+## Working Method
+
+- Read the relevant repository files before editing. Do not edit blind.
+- Understand the task and affected surfaces before writing code.
+- Prefer focused edits over rewriting whole files.
+- Do not invent commands, paths, exports, or behavior. Verify them from repository-local source.
+- Test or validate before declaring done.
+- Keep output concise. If something is uncertain, say so instead of guessing.
+
+## Canonical Repository Documentation
+
+Before changing code or documentation, start with:
+
+- `docs/index.md` for repository documentation navigation;
+- `docs/architecture.md` for repository boundaries and interactions;
+- `docs/specs/README.md` for the manifest-backed module and contract registry;
+- the affected module's manifest-routed `src/docs/README.md`; and
+- `docs/adr/index.md` plus applicable concrete ADRs for durable decisions.
+
+Follow `.sdd/manifest.json` for each contract's publication state and canonical source. This package
+owns no HTTP API: it consumes the externally owned Pragya and AI Bridge surfaces and publishes an
+SDK surface, so contracts stay on ecosystem-native artifacts and no OpenAPI document is selected.
+The manifest remains authoritative for canonical paths and artifact decisions.
+
+## 1. Commands (Run First)
+
+Use only documented commands. Do not invent alternatives when a command is missing.
+
+Command forms follow the root `AGENTS.md` workspace convention.
+
+| Task                   | Command             |
+| ---------------------- | ------------------- |
+| Install dependencies   | `yarn install` (from the monorepo root) |
+| Start dev environment  | Not applicable — this is a library, not a runnable app |
+| Run tests              | `yarn workspace @webex/internal-plugin-call-ai-summary test:unit` |
+| Run linters            | `yarn workspace @webex/internal-plugin-call-ai-summary test:style` |
+| Build/release artifact | `yarn workspace @webex/internal-plugin-call-ai-summary build:src` |
+| Format code            | `prettier` via the repository configuration |
+
+Running `yarn build`, `yarn test:style` or `yarn test:unit` from inside the package directory is
+equivalent.
+
+If a required command is unknown, stop and ask for the exact command.
+
+## 2. Agent Persona and Scope
+
+You are the Webex JS SDK engineering assistant for `@webex/internal-plugin-call-ai-summary`.
+
+Primary outcomes:
+
+- Deliver production-safe changes with passing tests.
+- Preserve existing behavior unless a change request explicitly requires a behavior change.
+- Keep docs and configuration aligned with code changes.
+
+Definition of done:
+
+1. Requested change is implemented.
+2. Relevant tests/lint/build checks pass locally.
+3. Updated docs/config cover new behavior.
+4. PR summary includes risks and rollback notes.
+
+## 3. Repository Knowledge
+
+The plugin resolves a **Pragya container** by ID, then fetches and decrypts AI-generated summaries,
+notes, action items, and transcripts from the URLs that container supplies. All AI-generated content is **JWE-encrypted** and decrypted via the KMS (Key Management Service) using `@webex/internal-plugin-encryption`.
+
+The plugin registers itself as `aisummary` on the internal namespace, so importing the package is
+what makes `webex.internal.aisummary` available.
+
+**Note:** The Pragya API returns summary URLs nested under `summaryData.data`. The `getContainer()` method normalizes this automatically, flattening those URLs onto `summaryData` so consumers can read `summaryData.summaryUrl` directly.
+
+### Tech Stack
+
+| Area             | Tooling     | Version     |
+| ---------------- | ----------- | ----------- |
+| Language runtime | Node.js     | Develop on **22.14** per the root `AGENTS.md` and `.nvmrc`. `package.json` declares `engines.node >=16`, which is the consumer floor, not the development version. |
+| Build tool       | `webex-legacy-tools` | workspace |
+| Test framework   | Jest via `@webex/jest-config-legacy` | workspace |
+| Lint/format      | ESLint `^8.24.0`, Prettier `^2.7.1` | see `package.json` |
+
+### Project Map
+
+- `src/index.ts`: Entry point. Registers the plugin via `registerInternalPlugin('aisummary', ...)`.
+- `src/ai-summary.ts`: Main plugin class extending `WebexPlugin`. Contains all public and private methods.
+- `src/types.ts`: TypeScript interfaces for request/response DTOs.
+- `src/constants.ts`: Service name, resource path, and error message constants.
+- `src/config.ts`: Plugin configuration (currently empty).
+- `src/manual-*.js`: Manual verification scripts requiring a live token.
+- `src/docs/README.md`: The canonical module specification.
+
+### Critical Constraints
+
+- `@webex/webex-core` provides the base plugin class, request handling, and auth interceptor; `@webex/internal-plugin-encryption` provides KMS decryption. Both are workspace dependencies.
+- The plugin is fully self-contained: it must not modify `UserSession`, the `packages/webex` bundle, or the encryption plugin.
+- Content URLs come from Pragya and are already region-correct; do not add service discovery for them.
+- Never log decrypted AI-generated call content.
+
+## 4. Testing Workflow
+
+Run checks in this order:
+
+1. `yarn test:unit`
+2. `yarn test:style`
+3. No integration or e2e tier exists; `src/manual-integration-test.js` is a manual script requiring a live token.
+
+Testing rules:
+
+- Add or update tests for every behavior change.
+- Cover failure paths and edge cases, not only happy paths.
+- Do not remove tests to make CI pass.
+
+**Current state.** `test/unit/spec/ai-summary.ts` holds 38 unit tests covering plugin registration, all six public
+methods, the `summaryData.data` flattening transform, the `keyUrl` precedence rule, every validation
+branch, and each normalized error mapping. Upstream wire fixtures are in
+`test/unit/fixture/responses.ts`. Note that Jest collects any `test/unit/**` subdirectory that is not
+named `lib` or `fixture`, so put new fixtures under `fixture/`, never `data/`.
+
+Do not construct a live `WebexCore` in a unit test. It boots the service catalog and fires
+asynchronous U2C requests that outlive the test, so Jest reports "Cannot log after tests are done"
+and the runner exits nonzero even when every assertion passes. Use `MockWebex` for behaviour, and
+the internal-core plugin registry for registration assertions.
+
+## 5. Code Style and Patterns
+
+Coding expectations:
+
+- Follow repository style rules and static analysis output.
+- Prefer small, composable functions over large procedural blocks.
+- Make error handling explicit at system boundaries.
+- Keep public interfaces stable unless a breaking change is requested.
+- Before adding a literal path, filename, command, workflow identifier, status,
+  or other policy value, search the repository for exact and semantically
+  equivalent uses. When repeated production values represent one shared
+  contract, move them to the narrowest owning shared module or catalog as one
+  canonical named constant, enum, or type and update consumers. Keep incidental
+  similarities, one-off implementation details, and independent test fixtures
+  local.
+- Do not import a default, named, object, or namespace binding and immediately
+  re-export it. Consumers should import from the owning module; package barrels
+  should use direct named re-exports.
+- Do not write inline runtime `typeof` checks outside descriptively named guard
+  implementations. Import and reuse the owning guard instead; TypeScript
+  type-position `typeof` queries remain allowed.
+
+Pattern example:
+
+```text
+Preferred:
+- Validate external input close to the boundary.
+- Return typed/structured results.
+- Include actionable error messages.
+
+Avoid:
+- Passing unvalidated payloads deep into the system.
+- Swallowing exceptions or returning ambiguous null values.
+```
+
+## 6. Git Workflow
+
+- Branch naming: `[feature|fix|chore]/[short-description]`
+- Commit format: conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`)
+- Keep commits focused and reversible.
+- Rebase on the target branch before opening PR.
+
+PR checklist:
+
+- What changed and why.
+- Tests run and results.
+- Risk/impact areas.
+- Rollback approach.
+
+## 7. Boundaries and Escalation
+
+### Always
+
+- Prefer existing patterns over introducing new architecture.
+- Keep changes minimal for the requested scope.
+- Call out assumptions and unknowns explicitly.
+
+### Ask First
+
+- Adding new dependencies or external services.
+- Large refactors or schema migrations.
+- Security-sensitive changes (auth, encryption, secrets handling).
+- Any destructive data or infrastructure operation.
+
+### Never
+
+- Commit secrets, keys, or credentials.
+- Bypass required checks by disabling tests or linters.
+- Rewrite history on shared branches.
+- Change unrelated files "while here" without clear need.

package/README.md

@@ -230,21 +230,26 @@ yarn test
 
 ```
 src/
-  index.ts          # Self-registration via registerInternalPlugin('aisummary', ...)
-  ai-summary.ts     # Plugin implementation (WebexPlugin.extend)
-  config.ts         # Plugin config
-  constants.ts      # Service name, error messages
-  types.ts          # TypeScript interfaces
+  index.ts                     # Self-registration via registerInternalPlugin('aisummary', ...)
+  ai-summary.ts                # Plugin implementation (WebexPlugin.extend)
+  config.ts                    # Plugin config
+  constants.ts                 # Service name, error messages
+  types.ts                     # TypeScript interfaces
+  manual-pragya-api-test.js    # Manual Pragya response-structure script
+  manual-integration-test.js   # Manual end-to-end script
+  docs/README.md               # Canonical module specification
 test/
   unit/
-    spec/
-      ai-summary.ts # Unit tests (26 tests)
-    data/
-      responses.ts  # Mock API response fixtures
-ai-docs/
-  ARCHITECTURE.md   # Detailed architecture document
+    spec/ai-summary.ts         # Unit tests (35 tests)
+    fixture/responses.ts       # Pragya / AI Bridge wire fixtures
+docs/                          # Repository-level SDD specifications
+AGENTS.md                      # Agent instructions for this package
 ```
 
+> **Note:** fixtures must live under `test/unit/fixture/`. Jest collects every `test/unit/**`
+> subdirectory except `lib` and `fixture`, so a `data/` directory would be picked up as a test
+> suite and fail.
+
 ## Dependencies
 
 | Package | Purpose |
@@ -254,4 +259,4 @@ ai-docs/
 
 ## Architecture
 
-See [ai-docs/ARCHITECTURE.md](ai-docs/ARCHITECTURE.md) for the full architecture document covering data flows, API request/response details, DTOs, security considerations, and testing strategy.
+See [docs/architecture.md](docs/architecture.md) for repository-wide architecture and [src/docs/README.md](src/docs/README.md) for the module specification covering data flows, API request/response details, encryption and error handling.