Update docs for control-plane monolith

[gciavarrini]

Updates the DCM documentation site for the control-plane monolith.

The old docs still described api-gateway on :9080 and four separate manager services. Update them with the current stack: one control-plane process on :8080, compose under control-plane/deploy/, and CLI config via --control-plane-url.

Main content changes are in architecture, local setup, troubleshooting, policies, CLI configuration, and a few user-guide/blog references (Rego URLs, repo links).

Also adds make format / make check-format for docs and blog markdown (80-column prose wrap), with .prettierignore for the Hugo homepage and RemoteMD stubs. A CI workflow runs the format check automatically.

Fixes: https://redhat.atlassian.net/browse/FLPATH-4407

--
Assisted-By: Claude (Anthropic)
Signed-off-by: Gloria Ciavarrini gciavarrini@redhat.com

Summary by Sourcery

Update DCM documentation and examples to reflect the unified control-plane monolith and new CLI configuration, and add automated markdown formatting tooling for docs and blog content.

Enhancements:

• Refresh architecture, local setup, troubleshooting, and user guide docs to describe a single control-plane service on :8080 instead of the legacy API gateway and separate managers.
• Adjust policy, catalog item, instance, provider, and blog examples to use the control-plane APIs and updated Rego provider URLs.
• Improve markdown layout across docs and blogs for readability and consistent tables and notes.
• Add Makefile targets for formatting and format checking of documentation markdown using Prettier.

CI:

• Introduce a GitHub Actions workflow that runs the documentation formatting check on relevant pull requests.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• In architecture.md, the components table now describes an embedded OPA engine while the sequence diagram still models OPA as a separate participant; consider updating the diagram and surrounding text so the role of OPA is consistently represented as part of the control-plane process rather than an external service.
• In local-setup.md and related getting-started docs, terminology alternates between “API gateway” and “control plane” (e.g., “The API gateway will be available at http://localhost:8080”); it would be clearer to standardize on “control plane” throughout those sections to match the new monolith architecture.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In `architecture.md`, the components table now describes an embedded OPA engine while the sequence diagram still models OPA as a separate participant; consider updating the diagram and surrounding text so the role of OPA is consistently represented as part of the control-plane process rather than an external service.
- In `local-setup.md` and related getting-started docs, terminology alternates between “API gateway” and “control plane” (e.g., “The API gateway will be available at http://localhost:8080”); it would be clearer to standardize on “control plane” throughout those sections to match the new monolith architecture.

## Individual Comments

### Comment 1
<location path="Makefile" line_range="28-32" />
<code_context>
 check-spell:
 	$(SPELLCHECK) "$(FILE)"
+
+format:
+	$(PRETTIER) --write --prose-wrap always --print-width 80 $(FORMAT_FILES)
+
+check-format:
+	$(PRETTIER) --check --prose-wrap always --print-width 80 $(FORMAT_FILES)
</code_context>
<issue_to_address>
**suggestion:** Avoid duplicating Prettier CLI flags between `format` and `check-format` targets.

Both `format` and `check-format` repeat `--prose-wrap` and `--print-width`. Please extract these into a shared `PRETTIER_FLAGS` (or similar) so formatting options are defined in one place and don’t drift between targets.

Suggested implementation:

```
FORMAT_FILES ?= content/docs/**/*.md content/blog/**/*.md
PRETTIER_FLAGS ?= --prose-wrap always --print-width 80

```

```
format:
	$(PRETTIER) $(PRETTIER_FLAGS) --write $(FORMAT_FILES)

check-format:
	$(PRETTIER) $(PRETTIER_FLAGS) --check $(FORMAT_FILES)

```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gabriel-farache]

with the formatting it's hard to tell what was changed and what was just formatted, could you split in 2 to make the review easier?

[chadcrum]

This file still references http://localhost:3000 — should be http://localhost:7007 to match local-setup.md and the actual compose config. I verified against the running stack and :7007 returns 200 while :3000 is connection refused. Port 3000 was the old Backstage dev mode default.

Not a blocker, but worth fixing while we're updating these docs.

[gciavarrini]

Good catch! Addressed d12ce4c

[gciavarrini]

with the formatting it's hard to tell what was changed and what was just formatted, could you split in 2 to make the review easier?

The commit history is split on purpose so you don’t need a separate formatting PR.

• da13712 — monolith doc changes only (no Prettier pass)
• 13f6fa4 — formatting only (make format)
• daeeb6f, d40ef37, 8232079 — Makefile / CI workflow
• 361e4fb — minor follow-up for addressing sourcery-ai comment (OPA wording, control-plane terminology)

For a content-only review da13712 is the one to use.

I can open another PR if you want but it will be the same split just with extra review/approval/merge overhead 🤷🏻‍♀️

[gabriel-farache]

thx for the clear commits separation!