Genesys Archivist

Captures Genesys Cloud Architect flows and every resource they depend on, then generates business and technical documentation from that capture.

https://github.com/mahmouddattiaa/Genesys-Archivist

Two consumers, two guarantees:

Consumer	Gets	Guarantee
Humans — engineers, PMs, customers	Markdown, PDF, and diagrams per flow	Every technical fact traces to source evidence; inference is labelled as inference
Machines — a future, separate migration server	An immutable, schema-versioned capture bundle	Complete enough to rebuild the IVR on another platform, including prompt audio

Archivist does not build that migration server. It guarantees the data contract that server will consume.

Status

Both stages work end to end against a real Genesys organization. 1,271 tests, with format, lint, production and test typechecking, and schema validation in npm run verify.

Plans 1–5 are built. Every archivist command is wired: profile, doctor, capture, document, render, verify, and update. The MCP server exposes nine tools, eight of them backed by real implementations. The source path was settled by measurement rather than assumption — the Platform API configuration endpoint (ADR-015) — and the adapter reaches it over a transport that exposes only GET, so read-only is a property of the type rather than a matter of reviewer attention (ADR-019).

Measured against the pilot sandbox: 511 flows across 15 types, 401 published. A whole-organization context capture reached 502 flows in ~361 seconds; re-running it with --since-last carried 394 unchanged flows forward and finished in ~110 seconds, producing a byte-identical content hash. Per-request budgets are in S6.

The permission gate is closed

S4 passes. A dedicated read-only role took the capture credential from 783 permission policies with 580 mutating grants down to 16 policies with zero mutation, caller-data, or credential permissions — while keeping every endpoint the adapter calls reachable. Details, and the four things the exercise found that reading could not, are in S4.

Known gaps

• Migration mode holds every asset in memory at once — ~110 MB on the sandbox, unbounded in organization size. Do not run it against a large real organization yet; context mode is unaffected. Three ranked fixes are in Plan 5.
• genesys_flow_diff still returns an explicit rejection rather than a result.
• An intermittent, unexplained run status. Roughly once in a dozen full-suite runs, a run that promoted its documents correctly is still reported failed. Two proven causes of exactly this were found and fixed — see the note below — but an instrumented hunt over eight further full runs did not reproduce a third, so it is recorded as open rather than closed. It has not been observed against a real organization; it costs a misleading status, never output.

Two capture modes

Per ADR-018, capture has two jobs and they are named separately:

archivist capture --mode context   --org <id> [--flow <id>...]
archivist capture --mode migration --org <id> [--flow <id>...]

context captures flow definitions and the resource manifest that arrives with them, so a developer returning to an unfamiliar IVR can re-orient quickly. It does not walk resources to closure or download assets, which makes it fast enough to run across a whole organization routinely.

migration captures everything needed to rebuild the IVRs elsewhere: every resource body, every byte of prompt audio, data-table rows.

Both produce a bundle. A context bundle records policy.mode: "context", reports migrationReadiness.archyImportableYaml: false, and carries a caveat saying so in words — it can never be mistaken for a migration-ready one.

The architecture in one paragraph

Two stages separated by a hard seam. Stage 1 (capture) is the only code that talks to Genesys: it discovers every flow of every type, fetches definitions, walks the resource reference graph to closure, downloads binary assets, and seals an immutable content-hashed capture bundle. Stage 2 (document) opens no sockets — it reads a bundle and produces Markdown, SVG diagrams, and PDF, with AI narration in the middle. Re-rendering documentation therefore costs zero Genesys API calls, and the bundle is a published contract rather than a disposable cache.

flowchart TD
    A["AI client"] -->|MCP STDIO| B["MCP adapter"]
    C["archivist CLI"] --> D["Application service"]
    B --> D
    D --> E["Genesys source provider"]
    E --> F["Genesys Cloud"]
    D --> G["Capture bundle (sealed, immutable)"]
    G --> H["Normalize, analyze, document"]
    H --> I["Markdown + diagrams + PDF"]
    G --> J["Future migration server"]

Getting started

npm install
npm run verify        # format + lint + typecheck + test + schema validation
npm run build

Point it at an organization

First time against a new Genesys organisation? Follow docs/SETUP-GENESYS.md — it walks through creating the least-privilege read-only role, the OAuth client, and where the credentials go. It also documents the one step nothing in the Genesys UI hints at: a new role does not appear in the OAuth client's role picker until you have added a member to it via Change Membership. That single omission costs people an hour.

A profile holds the non-secret metadata and names the credential. The client secret is read from stdin or a hidden prompt, never from a flag — argv is visible in process listings and shell history, so --client-secret is refused with an explanation rather than accepted.

archivist profile add \
  --id acme --display-name "Acme Bank" \
  --region euw1 --org <organizationId> \
  --client-id <oauthClientId> \
  --output-root /path/to/output
# then paste the secret at the prompt, or:  echo "$SECRET" | archivist profile add ...

archivist doctor                 # Node version, credential store, profiles
archivist profile validate acme  # profile parses, secret present, root writable

Capture and document

# Fast, whole-organization. Definitions plus the resource manifest that
# already travels with them. Cannot be migrated — see ADR-018.
archivist capture --profile acme --mode context --org <organizationId>

# Everything needed to rebuild elsewhere: resource bodies, prompt audio,
# data-table rows. See the memory caveat above before running this at scale.
archivist capture --profile acme --mode migration --org <organizationId> --flow <flowId>

archivist verify   --bundle <bundleDir>    # content hashes still match
archivist document --bundle <bundleDir>    # business.md, technical.md, operations.md, diagrams

--profile is required for capture, and not merely for convenience: the profile supplies the approved output root and the expectedOrganizationId that guards against a mistyped credential capturing the wrong customer's configuration.

Pictures, on request

document writes Mermaid .mmd sources in seconds. Drawing them launches a headless browser and costs roughly eleven renders per flow, so a 502-flow organization is ~5,500 renders and tens of minutes. Bundling the two would mean nobody could have the fast one, and a reader who only wants business.md would pay for pictures they never open. So it is a separate step:

archivist render --bundle <bundleDir>          # draw every .mmd as .svg
archivist render --bundle <bundleDir> --force  # redraw ones already drawn

Diagrams that cannot be drawn are reported, never omitted — a documentation set where three diagrams silently failed looks identical to one where they succeeded, and the reader has no way to tell.

Narration, opt-in and grounded

Narration is off by default, and a test asserts that a run without it opens no socket at all. The API key is a credential, so it follows the same rule as the Genesys secret: CLI-only, stored under a key derived from the profile so it can never collide with that profile's client secret.

archivist profile set-narration-key acme      # paste at the prompt, or pipe stdin
archivist document --bundle <bundleDir> --narrate --profile acme

Every claim the model produces is re-validated against the evidence pack before it can reach a document. A claim citing an evidence id that does not exist is rejected outright — never rendered in a weaker form — and the rejection is counted by reason code in narrative.md, because silently dropping it would be its own kind of dishonesty. Prompt wording is not the control here; the validator is.

Keep it current

archivist update --check    # report only: current commit, how far behind, what would land
archivist update            # pull, reinstall dependencies, rebuild -- prompts first
archivist update --yes      # same, without the confirmation prompt

update pulls from https://github.com/mahmouddattiaa/Genesys-Archivist, reinstalls dependencies, and rebuilds. It refuses, with a plain statement of what it found, when:

• the working tree is dirty (it lists the paths, never the diff), or
• origin does not point at that repository.

That second check is a supply-chain control rather than a tidiness rule: the command runs npm install and a build against whatever it pulls, so it must never do that from a fork. Clones created before the repository was renamed from genesys-architect-docs-mcp still work — GitHub redirects the old path to the same repository, and both spellings are accepted.

Drive it from an AI client

Register the server with your MCP client. Verified working against a real client over stdio — npm run smoke:mcp:live reproduces it.

{
  "mcpServers": {
    "genesys-archivist": {
      "command": "node",
      "args": ["<repo>/apps/mcp-server/dist/bin.js"]
    }
  }
}

Use node with an absolute path to the built entry point. The bin name genesys-archivist-mcp only resolves once the package is installed globally or linked; a plain node invocation always works and is what the smoke test exercises.

Run npm run build first — the client spawns the compiled output, not the TypeScript sources, and a stale dist is the most likely reason a change you just made appears to have no effect.

Nine tools, two resource templates, three prompts:

Tool	Does
genesys_profiles_list	Safe profile metadata. Never a client ID, secret, or token.
genesys_connection_check	Validates one profile, resolves the organization, reports permission gaps.
genesys_flows_list	Paginated flow descriptors, capped, with a continuation cursor.
genesys_flow_inspect	Bounded summary of one flow. Raw source is never inlined.
genesys_docs_plan	An immutable, expiring plan with a cryptographic hash.
genesys_docs_run_start	Starts a durable run from a plan; returns a run id immediately.
genesys_docs_run_get	Run state, counts, warnings, result resource URIs.
genesys_docs_run_cancel	Cooperative and idempotent. Never deletes previous good output.
genesys_flow_diff	Semantic diff between two versions.

STDIO only: protocol on stdout, everything else on stderr, no network listener. No tool accepts a credential — a test walks every registered input schema and fails on a credential-shaped property name at any depth, and the smoke test re-checks it from the client side, against what a client is actually offered.

Provisioning stays on the CLI, permanently. MCP tool arguments are chat-visible and client-logged, so profile add can never live here.

For a non-engineering audience — what this is, what it produced against a real organisation, and what is not done yet — see docs/PRODUCT-OVERVIEW.md.

If you are an AI agent integrating this tool

Read these four, in this order, before running anything:

1. docs/SETUP-GENESYS.md — the once-per-organisation admin setup. Do not attempt a capture before this is done; every failure mode at that stage traces back to it.
2. AGENTS.md — the boundaries you must not cross. In particular: never put a credential in a tool argument, and never widen the Genesys role to make a permission error go away.
3. This file's Status and Known gaps — what genuinely works today versus what is still open. Do not promise a user the migration mode at organisation scale; it is not ready.
4. docs/PRODUCT-OVERVIEW.md — for explaining the tool to the human you are working for.

Operational notes that are easy to get wrong:

• document does not draw diagrams. It writes .mmd sources in seconds; render draws them and takes tens of minutes on a large organisation. Offer the second step, do not assume it.
• Narration is opt-in (--narrate) and needs a key stored by archivist profile set-narration-key. Without it, everything else still works and opens no socket.
• Re-running is cheap. --since-last carried 394 of 502 flows forward on the reference organisation and cut a six-minute run to under two.
• A context bundle is not migration-ready and says so in its own manifest. Never present one as sufficient for a platform migration.

Then read, in order:

1. CLAUDE.md — orientation for anyone (human or agent) about to write code here.
2. AGENTS.md — non-negotiable boundaries. Violating one is a release blocker.
3. The design spec — what is being built and why. Section 2 lists where it departs from the numbered blueprint docs below.
4. Plan 1: Foundation — twelve task-by-task TDD tasks that need no Genesys access.
5. Phase 0 spikes — the go/no-go gate that unblocks everything else.

Phase 0 was a go/no-go gate, and it passed

Four source paths were in contention — Platform API, the Archy CLI, the Architect Scripting SDK, and manual YAML. Which one won was an empirical result, not an assumption.

Spike S1 measured the Platform API configuration endpoint at 100% structural fidelity against a manually exported Architect YAML baseline: 47 nodes, 10 construct types, zero unexplained differences. It additionally supplies a stable trackingId on every node and a manifest of referenced resources with ids and per-node provenance. The Architect Scripting SDK was dropped entirely (ADR-015); it would have supplied a strict subset at a much higher dependency cost.

The permission-matrix spike has since run and passed — see S4 and the Status section above. Prompt audio downloads read-only, clearing kill criterion 11 (S5), and scale budgets are measured (S6). Note that two spike-numbering schemes disagree from S3 onward; cite spikes by filename, not number.

Repository layout

apps/cli               archivist CLI
apps/mcp-server        genesys-archivist MCP STDIO server
packages/domain        contracts and DTOs. Pure: no I/O, no SDK types
packages/application   use cases, run state machines, policy
packages/composition   the one place adapters are wired to interfaces
packages/...           adapters, capture, analysis, documentation, rendering, narrative
schemas/               versioned JSON Schema contracts
fixtures/              sanitized test fixtures. Never real customer configuration
docs/                  blueprint, design spec, plans, ADRs, spikes

Dependency direction is enforced by ESLint, not by convention: domain imports nothing, application imports domain only, and apps/* stay thin.

Contributing

This project is open to outside development. Fork it, branch, and open a pull request — every PR is reviewed before merge. CONTRIBUTING.md covers the workflow, the five rules that will get a change rejected, the TDD expectations, and a list of good first contributions drawn from the current known gaps.

You do not need a Genesys organisation to contribute usefully: the documentation stage and most of capture are testable offline against fixtures.

Never commit

bundles/, derived/, documentation/, spike-evidence/, or any .wav / .mp3. Capture bundles are classified restricted — they contain endpoint URLs, DIDs, routing logic, data-table rows that may hold customer PII, and prompt audio. CI fails the build if any of these are tracked.

Terminology

The target is Genesys Cloud CX, and the IVR authoring product is Architect.

A flow has identifiers such as flowId and a version. Queues, prompts, data actions, schedules, and reusable flows also have identifiers. These are not secret API keys. A Genesys OAuth client_id and client_secret authenticate the integration and are the only secrets involved. The tool never enumerates hidden secrets, recovers OAuth client secrets, scrapes passwords, or bypasses Genesys permissions.

Non-goals for the first production release

• Editing, publishing, deleting, or importing Genesys flows
• Recovering or listing customer secrets
• Reading live caller data, recordings, transcripts, or historical execution data
• Query or Q&A tools over captured data
• Remote HTTP hosting, git/PR automation, or a scheduling daemon
• Claiming business intent that cannot be inferred from configuration

Blueprint documents

The original handoff. Still governing wherever the design spec does not override it.

File	Purpose
00-product-brief.md	Product goals, users, assumptions, scope
01-system-architecture.md	Components, packages, runtime decisions
02-genesys-integration.md	Authentication, discovery, extraction, versions
03-mcp-contract.md	MCP tools, resources, prompts, errors, jobs
04-domain-model.md	Normalized flow graph, evidence, hashes
05-documentation-generation.md	Document generation and grounding
06-security-and-compliance.md	Credentials, threats, authorization, data controls
07-change-detection.md	Incremental updates, manifests, diffs, review
08-failure-analysis.md	Bottlenecks, FMEA, degradation, kill criteria
09-testing-strategy.md	Unit, integration, contract, security, chaos tests
10-deployment-and-clients.md	Distribution and per-client configuration
11-observability-and-operations.md	Logs, metrics, audit, recovery, support
12-implementation-roadmap.md	Ordered implementation plan
13-acceptance-criteria.md	Definition of done and release gates
14-open-questions-and-spikes.md	Questions for IST and required experiments
15-sources.md	Official sources and research notes