[yanksyoon]

What this PR does

• Completes the Cloudflared Operators onboarding documentation.
• Replaces the remaining starter-pack placeholder content in the published documentation.
• Adds how-to guidance for exposing a frontend application and using the configurator.
• Documents the actual charm configuration, actions, relations, COS metrics, lifecycle events, security model, and deployment flow.
• Updates the tutorials and indexes so the new and existing pages are discoverable.
• Keeps the contribution guide structure and links it to the repository sources.
• Adds the local Vale vocabulary and Lychee configuration needed for the documentation checks.

Why we need it

The documentation still contained generic charm-template text and incomplete references. It also did not clearly explain that cloudflared is a subordinate machine charm, how it relates to a principal application, or how the configurator passes tunnel settings. This PR gives operators source-backed instructions for deploying, configuring, integrating, troubleshooting, and upgrading the charms.

Test plan

• make -f Makefile.docs docs-check
  • Vale: 0 errors, 0 warnings, and 0 suggestions.
  • Lychee: 0 errors.
• Strict Sphinx dummy build with warnings treated as errors: passed.
• git diff --check: passed.
• Verified that all documentation toctree and cross-reference targets resolve.
• Verified that no TODO or starter-template placeholder markers remain under docs/.

Review focus

• Confirm that the documented cloudflared-route, juju-info, ingress, and cos-agent relation directions match the charm metadata.
• Confirm that the deployment and DNS guidance reflects a subordinate machine charm rather than a Kubernetes-only workload.
• Confirm that the action and metrics descriptions remain aligned with the current charm source.
• Confirm that the expanded onboarding content is appropriate for the project’s intended users.

Potential breaking changes

None. This PR changes documentation and documentation lint configuration only. It does not change charm runtime behavior, interfaces, configuration keys, or workflows.

Dependencies, APIs, and workflow changes

No runtime dependencies or APIs are added. lychee.toml configures the existing documentation link checker, and the local Vale vocabulary adds project-specific terms.

Checklist

• I followed the contributing guide
• I added or updated the documentation.
• No separate release note is required; this is a documentation-only change.
• I used AI to assist with preparing this PR.
• I ran the relevant documentation checks.
• I added or updated tests as needed (not applicable to this documentation-only change).

[github-actions]

license-eye has checked 116 files.

Valid	Invalid	Ignored	Fixed
32	1	83	0

Click to see the invalid file list

• lychee.toml

Use this command to fix any missing license headers

```bash

docker run -it --rm -v $(pwd):/github/workspace apache/skywalking-eyes header fix

</details>

[github-actions]

license-eye has checked 116 files.

Valid	Invalid	Ignored	Fixed
32	1	83	0

Click to see the invalid file list

• lychee.toml

Use this command to fix any missing license headers

```bash

docker run -it --rm -v $(pwd):/github/workspace apache/skywalking-eyes header fix

</details>

[yanksyoon]

Initial review

[Copilot]

🟡 Changes recommended

CONTRIBUTING.md contains incorrect/non-existent build instructions (and an incorrect clone URL), and a couple of DNS “fallback” claims in docs don’t reliably match the current charm implementation.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR refreshes the Cloudflared Operators documentation to replace charm-template placeholders with source-aligned onboarding material, including tutorials, how-to guides, and reference/explanation pages, plus documentation-lint configuration.

Changes:

• Rewrites tutorial, how-to, reference, and explanation content to document the cloudflared (subordinate machine) and cloudflare-configurator charms and their relations/configuration.
• Updates docs navigation (indexes/toctrees) and adds new how-to pages (expose frontend, use configurator).
• Adds documentation-check configuration (Lychee config + local Vale vocabulary).

File summaries

File	Description
README.md	Adjusts repository README heading.
lychee.toml	Adds Lychee exclusions for internal doc URLs.
docs/index.rst	Replaces template landing page text and updates navigation/table links.
docs/tutorial/index.rst	Updates tutorial index copy and toctree entries.
docs/tutorial/basic-deployment.rst	Replaces placeholder tutorial with machine-model deployment/integration steps.
docs/tutorial/advanced-deployment.rst	Adds advanced operational guidance (DNS, multiple tunnels, snap channels, COS).
docs/how-to/index.rst	Adds/updates how-to index entries.
docs/how-to/configure-dns.rst	Documents DNS resolution behavior and nameserver option usage.
docs/how-to/expose-frontend.rst	New guide for exposing a frontend via ingress.
docs/how-to/use-configurator.rst	New guide for configurator usage and secret handling.
docs/how-to/integrate-with-cos.rst	Documents COS integration via cos-agent.
docs/how-to/redeploy.rst	Documents redeploy workflow in a new model.
docs/how-to/upgrade.rst	Documents refresh/upgrade workflow for both charms.
docs/how-to/troubleshoot.rst	Adds troubleshooting checks for relations/config/secrets.
docs/how-to/terraform.rst	States Terraform is not currently supported and gives alternative path.
docs/how-to/back-up-restore.rst	Describes what to preserve (topology/config/secrets) given no DB.
docs/how-to/contribute.rst	Updates contribution links to repository sources and issue tracker.
docs/reference/index.rst	Replaces template reference index copy with Cloudflared-specific structure.
docs/reference/actions.rst	Links to Charmhub actions page for configurator.
docs/reference/configurations.rst	Documents charm configuration keys and intent.
docs/reference/relation-endpoints.rst	Documents relation endpoints, directions, and example integrate commands.
docs/reference/metrics.rst	Documents COS metrics exposure and port allocation scheme.
docs/reference/juju-events.rst	Documents observed Juju events for both charms.
docs/reference/high-level-deployment.rst	Documents deployment model and relation topology (subordinate + configurator).
docs/reference/charm-architecture.rst	Replaces template architecture text with snap/subordinate architecture overview.
docs/reference/cryptographic-overview.rst	Documents security boundary (Juju secrets + Cloudflare tunnel).
docs/reference/terraform.rst	Notes absence of Terraform modules in repo and links to Juju deployment path.
docs/release-notes/index.rst	Replaces template release-notes landing page with project-specific policy/links.
docs/explanation/index.rst	Updates explanation index to Cloudflared-specific context.
docs/explanation/charm-design.rst	Explains the split between workload execution and configuration provider.
docs/explanation/security.rst	Documents secret flow and points to upstream Cloudflare guidance.
docs/changelog.rst	Adds/links a changelog page in docs navigation.
CONTRIBUTING.md	Updates contribution guide links and commands.
.vale/styles/config/vocabularies/local/accept.txt	Adds project terms to Vale local vocabulary.

Review details

• Files reviewed: 34/34 changed files
• Comments generated: 5
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[erinecon]

Thanks so much for all your work on expanding this documentation set 🚀 I've gone through the explanation material (no comments) and how-to guides today. Thanks for your patience on the remaining pages :)

[erinecon]

Made it through the rest of the docs today -- thank you so much for all your work here!!

[erinecon]

Some remaining nits, but nothing that's blocking the merge. Thank you so much for all your work and effort on the documentation 🎉

[github-actions]

Test results for commit a07823e

Test coverage for a07823e

Name           Stmts   Miss Branch BrPart  Cover   Missing
----------------------------------------------------------
src/charm.py      69      0     20      0   100%
----------------------------------------------------------
TOTAL             69      0     20      0   100%

Static code analysis report

Run started:2026-09-17 05:02:05.275931+00:00

Test results:
  No issues identified.

Code scanned:
  Total lines of code: 509
  Total lines skipped (#nosec): 0
  Total potential issues skipped due to specifically being disabled (e.g., #nosec BXXX): 0

Run metrics:
  Total issues (by severity):
  	Undefined: 0
  	Low: 0
  	Medium: 0
  	High: 0
  Total issues (by confidence):
  	Undefined: 0
  	Low: 0
  	Medium: 0
  	High: 0
Files skipped (0):

[github-actions]

Test results for commit a07823e

Test coverage for a07823e

Name           Stmts   Miss Branch BrPart  Cover   Missing
----------------------------------------------------------
src/charm.py     159     62     52      5    57%   88-89, 112->114, 117-156, 164, 176-185, 212, 221-226, 234-247, 256-266, 283-293, 303-306, 325
----------------------------------------------------------
TOTAL            159     62     52      5    57%

Static code analysis report

Run started:2026-09-17 05:02:04.050459+00:00

Test results:
  No issues identified.

Code scanned:
  Total lines of code: 800
  Total lines skipped (#nosec): 7
  Total potential issues skipped due to specifically being disabled (e.g., #nosec BXXX): 0

Run metrics:
  Total issues (by severity):
  	Undefined: 0
  	Low: 0
  	Medium: 0
  	High: 0
  Total issues (by confidence):
  	Undefined: 0
  	Low: 0
  	Medium: 0
  	High: 0
Files skipped (0):