docs: update onboarding docs

.vale/styles/config/vocabularies/local/accept.txt

@@ -1,2 +1,8 @@
 AI
+Cloudflare
+cloudflare-configurator
+cloudflared
+configurator
+Diataxis
+nameserver
 redeployments

CONTRIBUTING.md

@@ -1,13 +1,13 @@
-<!-- Remember to update this file for your charm -- replace __charm_name__ with the appropriate name. -->
+<!-- Remember to update this file for your charm -- replace cloudflared with the appropriate name. -->
 
 # Contributing
 
-This document explains the processes and practices recommended for contributing enhancements to the __charm_name__ charm.
+This document explains the processes and practices recommended for contributing enhancements to the cloudflared charm.
 
 ## Overview
 
 - Generally, before developing enhancements to this charm, you should consider [opening an issue
-  ](link to issues page) explaining your use case.
+  ](https://github.com/canonical/cloudflared-operators/issues) explaining your use case.
 - If you would like to chat with us about your use-cases or proposed implementation, you can reach
   us at [Canonical Matrix public channel](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
   or [Discourse](https://discourse.charmhub.io/).
@@ -30,7 +30,7 @@ When contributing, you must abide by the
 ## Changelog
 
 Please ensure that any new feature, fix, or significant change is documented by
-adding an entry to the [CHANGELOG.md](link to changelog) file. Use the date of the
+adding an entry to the [CHANGELOG.md](https://github.com/canonical/cloudflared-operators/blob/main/cloudflared-operator/CHANGELOG.md) file. Use the date of the
 contribution as the header for new entries.
 
 To learn more about changelog best practices, visit [Keep a Changelog](https://keepachangelog.com/).
@@ -42,7 +42,7 @@ notify in advance the people involved to avoid confusion;
 also, reference the issue or bug number when you submit the changes.
 
 - [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks)
-  our [GitHub repository](link to GitHub repository)
+  our [GitHub repository](https://github.com/canonical/cloudflared-operators)
   and add the changes to your fork, properly structuring your commits,
   providing detailed commit messages and signing your commits.
 - Make sure the updated project builds and runs without warnings or errors;
@@ -76,7 +76,7 @@ AI usage). You don't need to go into explicit details about how and where you us
 Avoid submitting contributions that you don't fully understand.
 You are responsible for the entire contribution, including the AI-assisted portions.
 You must be willing to engage in discussion and respond to any questions, comments,
-or suggestions we may have. 
+or suggestions we may have.
 
 ### Signing commits
 
@@ -86,7 +86,7 @@ we use the [Canonical contributor license agreement](https://assets.ubuntu.com/v
 
 #### Canonical contributor agreement
 
-Canonical welcomes contributions to the __charm_name__ charm. Please check out our
+Canonical welcomes contributions to the cloudflared charm. Please check out our
 [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution.
 
 The CLA sign-off is simple line at the
@@ -107,7 +107,7 @@ To make contributions to this charm, you'll need a working
 The code for this charm can be downloaded as follows:
 
 ```
-git clone https://github.com/canonical/__charm_name__
+git clone https://github.com/canonical/cloudflared-operators
 ```
 
 Make sure to install [`uv`](https://docs.astral.sh/uv/). For example, you can install `uv` on Ubuntu using:
@@ -145,42 +145,33 @@ that can be used for linting and formatting code when you're preparing contribut
 * ``tox -e unit``: Runs the unit tests.
 * ``tox -e integration``: Runs the integration tests.
 
-### Build the rock and charm
+### Build the charms
 
-Use [Rockcraft](https://documentation.ubuntu.com/rockcraft/stable/) to create an
-OCI image for the __charm_name__ app, and then upload the image to a MicroK8s registry,
-which stores OCI archives so they can be downloaded and deployed.
-
-Enable the MicroK8s registry:
-
-```bash
-microk8s enable registry
-```
-
-The following commands pack the OCI image and push it into
-the MicroK8s registry:
+Each charm project contains a ``charmcraft.yaml``. Pack the charms from their
+respective directories:
 
 ```bash
-cd <project_dir>
-rockcraft pack
-skopeo --insecure-policy copy --dest-tls-verify=false oci-archive:<rock-name>.rock docker://localhost:32000/<app-name>:latest
-```
-
-Build the charm in this git repository using:
-
-```shell
+cd cloudflared-operator
+charmcraft pack
+cd ../cloudflare-configurator-operator
 charmcraft pack
 ```
 
+The ``charmed-cloudflared`` workload is maintained separately under
+``charmed-cloudflared-snap`` and is not an OCI image or Rockcraft project.
+
 ### Deploy
 
+For a model deployment, use the charms from Charmhub:
+
 ```bash
 # Create a model
 juju add-model charm-dev
 # Enable DEBUG logging
 juju model-config logging-config="<root>=INFO;unit=DEBUG"
-# Deploy the charm
-juju deploy ./__charm_name__.charm 
+# Deploy the charms
+juju deploy cloudflared
+juju deploy cloudflare-configurator
 ```
 
 

README.md

@@ -1,4 +1,4 @@
-# Cloudflared operators
+# cloudflared operators
 This repository provides a collection of operators related to Cloudflare's `cloudflared` tunnel.
 This repository contains the code for the following charms:
 1. `cloudflared`: A subordinate machine charm that deploys and manages the `cloudflared` tunnel. See the [cloudflared-operator README](cloudflared-operator/README.md) for more information.

docs/changelog.rst

@@ -1,5 +1,5 @@
 .. meta::
-   :description: View the changelog for the __charm_name__ charm, including all versions and changes.
+   :description: View the project changelog for the Cloudflared Operators charms and their changes.
 
 .. _changelog:
 

docs/explanation/charm-design.rst

@@ -1,28 +1,22 @@
 .. meta::
-   :description: Understand the architectural design decisions and code structure of the __charm_name__ charm.
+   :description: Understand the architectural design decisions and code structure of the Cloudflared charms.
 
 .. _explanation_charm_design:
 
 Charm design
 ============
 
-.. TODO: Remember to update this file for your charm!!
-   This document should offer perspective and opinion about the charm was designed,
-   and why those design decisions were made.
+The project separates tunnel execution from configuration management.
+``cloudflared`` is a subordinate machine charm. It attaches to a principal
+application through ``juju-info`` and manages one or more parallel
+``charmed-cloudflared`` snap instances on that machine.
 
-   Some guiding questions as you consider the content for this page:
-   * What are the user's questions about the charm? What are the use cases?
-   * What questions do you want the user to be asking about the charm and its design? Why would they want to read this document? What are the questions that this document is trying to answer?
-   * What sort of framing do the users need to understand this content?
-   * What is the relationship between the user and the charm (or its code)?
-   * What is the starting point for the user's thinking?
-   * How does the code come together to operate the underlying software/workload? 
+The ``cloudflare-configurator`` charm is the configuration provider. It reads the
+public ``domain``, optional ``nameserver``, and the Juju secret named by
+``tunnel-token``. It sends the tunnel token and resolver through
+``cloudflared-route`` and publishes the configured HTTPS URL through ``ingress``.
 
-   There's no specific template or structure to follow here -- you should provide your
-   own perspective about the charm design. If a Mermaid diagram of the charm would enhance
-   the text, then include it in this document.
-
-   Some guiding points on the Mermaid diagram:
-   Limit the scope of this diagram to the charm only.
-   How is the charm containerized, and what pieces are of particular interest to the user?
-   Include those separate pieces in this diagram.
+This design keeps secret and routing configuration in one charm while allowing
+the workload charm to remain reusable with either a relation provider or its
+direct ``tunnel-token`` configuration. The Cloudflare-side origin route is
+outside the charm boundary and remains managed through Cloudflare.

docs/explanation/index.rst

@@ -1,18 +1,13 @@
 .. meta::
-   :description: Conceptual guides explaining the design and security of the __charm_name__ charm. 
+   :description: Conceptual guides explaining the design and security of the Cloudflared charms.
 
 .. _explanation_index:
 
 Explanation
 ===========
 
-.. TODO: Update the name of the charm!
-         Note that, if there are less than 5 pages in this section,
-         you don't need to split up the pages into different themes
-         or subsections.
-
-The pages in this section provide additional context and deeper understanding
-of foundational topics and concepts related to the __charm_name__ charm.
+These pages provide context about the design, security boundaries, and
+operational model of the Cloudflared charms.
 
 .. vale Canonical.013-Spell-out-numbers-below-10 = NO
 
@@ -22,4 +17,3 @@ of foundational topics and concepts related to the __charm_name__ charm.
 
     Charm design overview <charm-design>
     Security overview <security>
-

docs/explanation/security.rst

@@ -1,26 +1,18 @@
 .. meta::
-   :description: Understand the security design, risks, and best practices for the __charm_name__ charm.
+   :description: Understand the security design, risks, and best practices for the Cloudflared charms.
 
 .. _explanation_security:
 
 Security overview
 =================
 
-.. TODO: Remember to update this file for your charm!!
-         Elaborate on topics such as common risks, good practices, built-in protection, etc.
-         Are there upstream security docs that we can point to? If so, include a
-         sentence like:
-         For details regarding upstream __charm_name__ configuration and broader security
-         considerations, please refer to the upstream documentation (include a link here).
+Tunnel credentials are stored in Juju secrets. The secret must contain a
+``tunnel-token`` key and must be granted to the application that consumes it.
 
-         In most cases, it will be appropriate to include a specific heading for risks.
-         Include a subheading for best practices for the user to follow to avoid or limit risks.
-
-         In some cases a product will have particular information security implications
-         (concerned with potential for information loss, incorrect retention, unlawful disclosure
-         and so on). Notes on these should be gathered separately in the overview topic, or
-         in a topic of their own.
-
-This document outlines the security design of the __charm_name__  charm along common risks
-and best practices.
+The configurator reads the secret and sends the token through the
+``cloudflared-route`` relation. The subordinate writes the token to the
+``charmed-cloudflared`` snap configuration on the principal application's
+machine.
 
+For Cloudflare-specific tunnel security guidance, see the `Cloudflare Tunnel documentation
+<https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/>`_.

docs/how-to/back-up-restore.rst

@@ -1,13 +1,16 @@
 .. meta::
-   :description: How to back up and restore the __charm_name__ charm and its associated data.
+   :description: How to back up and restore Cloudflared charm configuration.
 
 .. _how_to_back_up_restore:
 
 How to back up and restore
 ===========================
 
-.. TODO: Remember to update this file for your charm!! 
-    If applicable, use this placeholder to provide information on how to
-    back up and restore the charm. Some questions to answer:
-    * Does this charm have a database that needs to be backed up?
-    * Are there are upstream docs we can link here?
+The charms do not manage an application database or other persistent application
+data. A backup should preserve the Juju model definition, application
+configuration, relation topology, and the Cloudflare-side tunnel configuration.
+
+Keep the tunnel token in a Juju secret. Preserve the secret and its grant to
+``cloudflare-configurator`` without exporting the token into a public backup.
+When restoring into a new model, recreate the secret, grant it to the
+application, and reapply the ``domain`` and ``nameserver`` configuration.

docs/how-to/configure-dns.rst

@@ -6,32 +6,35 @@
 How to configure DNS
 ====================
 
-By default, the ``cloudflared`` charm uses the Kubernetes cluster's internal DNS 
-(``kube-dns.kube-system.svc``) to resolve internal service names when routing traffic from
-Cloudflare to your applications.
+The ``cloudflare-configurator`` charm tries to resolve the Kubernetes DNS
+service, ``kube-dns.kube-system.svc``, when ``nameserver`` is unset. On a
+machine cloud where that name is not resolvable, configure ``nameserver``
+explicitly rather than relying on an automatic host-resolver fallback.
 
-If your architecture requires the tunnel to resolve names using a specific external DNS server or a
-custom internal DNS, you can override this behavior using the ``cloudflare-configurator`` charm.
-This guide assumes that you've already deployed and integrated the ``cloudflared`` and
-``cloudeflare-configurator`` charms.
+This guide assumes
+that the ``cloudflared`` and ``cloudflare-configurator`` charms are deployed and
+integrated.
 
-To configure a custom DNS resolver, set the ``nameserver`` configuration option on the
-``cloudflare-configurator`` charm:
+Configure the resolver on ``cloudflare-configurator``:
 
 .. code-block:: bash
 
    juju config cloudflare-configurator nameserver=8.8.8.8
 
-After you run this configuration, the nameserver is set as follows:
+After this configuration:
 
-1. The ``cloudflare-configurator`` charm passes the configured nameserver to the ``cloudflared``
-charm via the ``cloudflared-route`` relation.
-2. The ``cloudflared`` charm writes this nameserver into a dedicated ``resolv.conf`` file located
-at ``/var/snap/charmed-cloudflared/current/etc/resolv.conf``.
-3. The ``cloudflared`` snap instance uses this configuration to resolve domain names when
-establishing routes to your internal services.
+1. ``cloudflare-configurator`` sends the nameserver to ``cloudflared`` through
+   the ``cloudflared-route`` relation.
+2. ``cloudflared`` writes it to the resolver file for each installed
+   ``charmed-cloudflared`` snap instance.
+3. The snap instance uses the resolver when resolving names for its tunnel.
 
-To revert to the default Kubernetes DNS, simply unset the configuration:
+The instance path is based on the tunnel source. Direct configuration uses the
+``charmed-cloudflared_config0`` instance, while relation-backed tunnels use an
+instance named with the relation ID. The resolver file is stored under
+``/var/snap/<instance>/current/etc/resolv.conf``.
+
+To return to the default behavior, unset the option:
 
 .. code-block:: bash
 

docs/how-to/contribute.rst

@@ -1,32 +1,26 @@
 .. meta::
-   :description: Familiarize yourself with contributing to the __charm_name__ charm documentation.
+   :description: Familiarize yourself with contributing to the cloudflared charm documentation.
 
 .. _how_to_contribute:
 
 How to contribute
 =================
 
-.. TODO: Add link to CONTRIBUTING.md
-
 .. note::
 
-   See CONTRIBUTING.md
-   for information on contributing to the source code. 
-
-.. TODO: Update the links to point to the correct repo!!
-         Is the documentation hosted on Charmhub or RTD? Include a link
+   See `CONTRIBUTING.md <https://github.com/canonical/cloudflared-operators/blob/main/CONTRIBUTING.md>`_
+   for information on contributing to the source code.
 
-Our documentation is hosted on __docs_hosting_with_link__ to enable collaboration.
+The documentation source is maintained in the `cloudflared-operators repository
+<https://github.com/canonical/cloudflared-operators/tree/main/docs>`_.
 Please use the links on each documentation page to either
 directly change something you see that's wrong, ask a question, or make a suggestion
 about a potential change.
 
-.. TODO: Add link to GitHub page for "source code on GitHub"
-         Add link to issues page for "file a bug"
-
-Our documentation is also available alongside the source code on GitHub.
-You may open a pull request with your documentation changes, or you can
-file a bug to provide constructive feedback or suggestions.
+The source code is available in the `cloudflared-operators repository
+<https://github.com/canonical/cloudflared-operators>`_. Open an issue in the
+`issue tracker <https://github.com/canonical/cloudflared-operators/issues>`_ to
+report a problem or suggest an improvement.
 
 AI usage
 --------