feat: sync Getting Started page from complytime/complytime via sync-content

[sonupreetam]

Is your feature request related to a problem? Please describe.

The Getting Started page (content/docs/getting-started/_index.md) is the only major content page on the site that is hand-maintained in the website repo rather than synced from an upstream source of truth. This disconnect is already causing real problems, there are currently 11 open issues against the page where commands are broken, behavior doesn't match reality, or critical information is missing:

• Getting Started: documented cosign verify-blob command cannot verify any release #59 — cosign verify-blob command cannot verify any release
• Getting Started: cp bin/complyctl-provider-openscap copies a file make build never creates #60 — cp bin/complyctl-provider-openscap copies a file make build never creates
• Getting Started: complyctl init documentation does not match observed behavior #61 — complyctl init docs don't match observed behavior
• Getting Started: "Your First Compliance Scan" cannot be completed — no policy URL or registry given #62 — "Your First Compliance Scan" can't be completed — no policy URL or registry given
• Getting Started: behavior-changing environment variables are not documented on the page #63 — Behavior-changing environment variables not documented
• Getting Started: the page never states what problem the tool solves or who it is for #64 — Page never states what problem the tool solves or who it is for
• Getting Started: the openscap path needs a profile target variable the page never mentions #65 — OpenSCAP path needs a profile target variable never mentioned
• Getting Started: cosign is required by the recommended path but not listed as a prerequisite #66 — cosign required but not listed as prerequisite
• Getting Started: two different .complytime directories are never disambiguated #67 — Two different .complytime directories never disambiguated
• Getting Started: top-level commands and global flags are omitted from the walkthrough #68 — Top-level commands and global flags omitted
• Getting-started: correct "block the pipeline" wording to match scan exit code contract #75 — "Block the pipeline" wording doesn't match scan exit code contract

PR #82 is working on fixes and proposes a doctest infrastructure to catch broken commands. These are all symptoms of the same root cause: the getting-started content lives in the website repo, disconnected from the repos where tool behavior is defined and changes. Contributors who change complyctl behavior have no visibility into the getting-started page they're silently breaking.

Every other documentation page flows through the sync-content pipeline with lockfile-gated deploys and weekly upstream change detection. The getting-started page should follow the same pattern.

Describe the solution you'd like

Sync the Getting Started page from complytime/complytime via the existing sync-content tool.

1. Upstream source: Create docs/guides/getting-started.md in complytime/complytime. This is the ecosystem-level onboarding guide (architecture overview, prerequisites, first scan walkthrough). The docs/guides/ directory already exists with a .keep placeholder reserved for how-to docs.

2. Sync config: Add a config-driven source entry in sync-config.yaml that maps the upstream file to content/docs/getting-started/_index.md:

   sources:
     - repo: complytime
       files:
         - src: docs/guides/getting-started.md
           dest: content/docs/getting-started/_index.md
           transforms:
             - inject-frontmatter:
                 title: "Getting Started"
                 description: "Get started with ComplyTime in minutes."
                 lead: "Get up and running with ComplyTime compliance automation tools."
                 weight: 200
                 toc: true
             - theme-image
             - rewrite-links

3. Lockfile tracking: complytime is already tracked in .content-lock.json. The existing weekly sync-content-check workflow will detect upstream changes and open a lockfile update PR automatically.

4. Remove hand-maintained file from git: Once the sync source is wired up, remove content/docs/getting-started/_index.md from git tracking (it becomes a generated file, like content/docs/projects/*/). Update .gitignore accordingly.

5. Companion PR on complytime/complytime: Move the current page content into docs/guides/getting-started.md in plain Markdown (no Hugo shortcodes), fixing the 11 open issues in the process. Hugo-specific rendering (theme-aware images, frontmatter) is handled by sync transforms on the website side.

6. Resolve open issues: The migration is the right time to address Getting Started: documented cosign verify-blob command cannot verify any release #59–Getting Started: top-level commands and global flags are omitted from the walkthrough #68 and Getting-started: correct "block the pipeline" wording to match scan exit code contract #75 in the upstream file rather than patching the website copy. Once the synced version lands, those issues can be closed.

Describe alternatives you've considered

• Fix issues in place and keep it hand-maintained: Addresses the immediate bugs but doesn't fix the structural problem. The same drift will recur as complyctl evolves.

• Source from complyctl instead: complyctl/docs/QUICK_START.md covers similar ground, but the getting-started page is ecosystem-level (architecture overview, multi-tool concepts, provider model) rather than tool-specific. Sourcing from complytime/complytime keeps the guide at the right abstraction level while QUICK_START.md remains the tool-specific reference.

Additional context

• The sync-config.yaml sources list is currently empty — this would be the first config-driven source entry, exercising a capability that was built but not yet used in production.
• The theme-image transform for converting standard Markdown images to Hugo shortcodes may need to be implemented in cmd/sync-content/ if it doesn't already exist. The upstream file would use standard Markdown image syntax and the transform handles the Hugo conversion.
• complyctl/docs/QUICK_START.md already syncs separately as a project doc page. The two pages serve different audiences: Getting Started is the front-door onboarding experience; Quick Start is the tool-specific reference.
• The doctest infrastructure proposed in PR fix: add cosign to prerequisites #82 could run against the upstream file in complytime/complytime CI, catching broken commands before they ever reach the website.

[trevor-vaughan]

Thanks for putting this together @sonupreetam, I had originally filed the separate issues as a one-off but having a single point RCA that can fix all of them would be great.

I'm going to block this one on #64 since it upgrades Hugo to the latest (at the time of patch) version and does some template updating. I wouldn't want the implementer to end up running into the same issues that I did that precipitated that change.

[beatrizmcouto]

Sonu created this issue to compile issues found in the website. It's more efficient that one persons solves all of them, mainly focusing on the source repos, which will then feed the website. If we need to include more sources for the website, we can review the sync process later. @trevor-vaughan FYI - since you started looking at this, if you want to take this one when you're free (no urgency)