docs/concept: rewrite modules landing page

This change starts to reshape the /docs/concept/module/ landing page
(renamed from .../modules/) to provide high-level directional guidance
aimed at allowing users to segment themselves into:

- "I won't need to publish my module, as I'm only consuming dependencies
  and not providing them"
- "I'll probably need to publish this module, as others will depend on
  it".

This split will allow us to write simpler docs for the first group which
won't need to touch on the more involved publishing workflow - hence
will be more approachable for newcomers to CUE modules, who are more
likely only to need guidance on package imports inside a single module.
Some hidden content is left in the page source as a hint at the future
direction of this landing page's user segmentation role/flow.

This change also introduces a draft pair of concept guide hierarchies
for Packages and Registries so they can be linked to from the Modules
landing page and avoid overloading the /docs/concept/module/ hierarchy.
Their text has been filled in by an LLM solely as placeholders, and
should be rewritten before being published.

Preview-Path: /docs/concept/module/
Preview-Path: /docs/concept/package/
Preview-Path: /docs/concept/registry/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: I63cdfe0d18748447d814afc7a3c771edadb5c2ef
Dispatch-Trailer: {"type":"trybot","CL":1202902,"patchset":10,"ref":"refs/changes/02/1202902/10","targetBranch":"master"}

content/docs/concept/module/_en.md

@@ -0,0 +1,108 @@
+---
+title: Modules
+tags: [modules]
+toc_hide: false
+aliases:
+- /docs/concept/modules/
+---
+
+Modules are how CUE manages native dependencies.
+A module contains a tree of CUE
+packages<!--[packages]({{< relref "../package" >}})-->
+alongside metadata that describes the module's identity, version, and its
+dependencies. The metadata is generally managed by
+[`cue mod`]({{<relref "docs/reference/command/cue-help-mod">}})
+commands such as
+[`cue mod init`]({{<relref "docs/reference/command/cue-help-mod-init">}})
+(which initializes a module), and
+[`cue mod tidy`]({{<relref "docs/reference/command/cue-help-mod-tidy">}})
+(which resolves all dependencies in the current module and updates the metadata
+to reflect them).
+
+A module must be initialized and used if any package in the tree needs to
+be referenced by any other package -- whether that other package is inside the
+same module, or in some other module.
+When a package references (or *imports*) a package from a different module, the
+module containing the importing package is said to have a *dependency* on the
+module containing the imported package.
+
+Optionally, modules can be *published* to a
+registry<!--[registry]({{< relref "../registry" >}})-->.
+A published module can be used as a dependency by other modules, and will be
+fetched from the registry, as required, by CUE commands.
+A module only needs to be published when other modules have a dependency on it.
+A module containing a tree of packages that refer to each other (and aren't
+referenced by packages in other modules) does not need to be published -- but
+can be published if so desired.
+
+<!--
+{{<cards>}}
+{{<card title="Importing packages within a module"
+        label="module/local-import"
+        href="."
+>}}
+How using a module allows you to reference one package from another, inside the same package tree.
+{{</card>}}
+
+{{<card title="Do I need to publish my module?"
+        label="module/publishing"
+        href="."
+>}}
+Only certain workflows require modules to be published. Find out about them here ...
+{{</card>}}
+
+{{<card title="Adding a module dependency"
+        label="module/cue-mod-tidy"
+        href="."
+>}}
+Teach CUE that your module needs to use another module ...
+{{</card>}}
+{{</cards>}}
+-->
+
+Learn about CUE modules using the suggested links below, or follow the
+{{<tag modules>}} tag to explore the full range of modules-related pages.
+
+{{<cards>}}
+{{<card title="Reference manual"
+        label="reference/manual"
+        href="/docs/reference/modules/"
+>}}
+The CUE modules reference manual and glossary
+{{</card>}}
+
+{{<card title="Concept Guide"
+        label="concept/faq"
+        href="/docs/concept/faq/new-modules-vs-old-modules/"
+>}}
+CUE's "new" versus "old" modules -- your questions: answered
+{{</card>}}
+
+{{<card title="The cue command"
+        label="reference/command/cue"
+        href="/docs/reference/command/cue-help-modules"
+>}}
+The built-in help text for\
+`cue help modules`
+{{</card>}}
+
+{{<card title="Getting started"
+        label="tutorial"
+        href="/docs/tutorial/working-with-the-central-registry/"
+>}}
+Working with the CUE Central Registry
+{{</card>}}
+{{<card title="Collaborate"
+        label="tutorial"
+        href="/docs/tutorial/publishing-modules-to-the-central-registry/"
+>}}
+Publishing modules to the Central Registry
+{{</card>}}
+
+{{<card title="Private infrastructure"
+        label="tutorial"
+        href="/docs/tutorial/working-with-a-custom-module-registry/"
+>}}
+Working with a custom module registry
+{{</card>}}
+{{</cards>}}

content/docs/concept/module/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: concept: module: page: _

content/docs/concept/package/_en.md

@@ -0,0 +1,26 @@
+---
+title: Packages
+toc_hide: true
+draft: true
+---
+
+<!-- LLM-generated placeholder:
+  model:  "ChatGPT 4o mini"
+  prompt: "Write a short introduction page explaining CUE packages"
+  aHuman: "Removed the too-general preamble"
+-->
+
+CUE packages are modular units that encapsulate CUE files and related resources, promoting code organization and reuse. A package typically includes:
+
+- **CUE Definitions**: These define schemas, validation rules, and data models.
+- **Imports**: Packages can import other CUE packages, enabling a hierarchical and composable approach to configuration.
+- **Documentation**: Clear documentation helps users understand the purpose and usage of the package.
+
+## Benefits of Using CUE Packages
+
+1. **Modularity**: Break down complex configurations into manageable parts.
+2. **Reusability**: Share and reuse packages across different projects or environments.
+3. **Validation**: Ensure configurations adhere to defined schemas, reducing errors.
+4. **Clarity**: Improve understanding through well-structured documentation.
+
+By utilizing CUE packages, teams can enhance collaboration and maintain consistency across their configuration management efforts. Whether you’re working on cloud infrastructure, application settings, or any other configuration-heavy project, CUE packages provide the tools needed to streamline the process.

content/docs/concept/package/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: concept: package: page: _

content/docs/concept/registry/_en.md

@@ -0,0 +1,30 @@
+---
+title: Registries
+toc_hide: true
+draft: true
+---
+
+<!-- LLM-generated placeholder:
+  model:  "ChatGPT 4o mini"
+  prompt: "Write a short introduction page explaining CUE registries"
+  aHuman: "Removed the first H1 heading"
+-->
+
+CUE Registries serve as centralized repositories for CUE packages, enabling developers to easily discover, share, and manage reusable configuration definitions. By organizing CUE packages in a registry, teams can streamline collaboration and ensure consistency in configuration management across projects.
+
+## What are CUE Registries?
+
+A CUE registry is a collection of CUE packages that can be published, versioned, and accessed by various users and applications. Registries provide the following features:
+
+- **Centralized Access**: Users can easily search for and retrieve CUE packages from a single location.
+- **Version Management**: Keep track of different versions of packages, ensuring that teams can use the most appropriate versions for their needs.
+- **Community Sharing**: Facilitate sharing of configurations among teams and the broader community, promoting best practices and reusable solutions.
+
+## Benefits of Using CUE Registries
+
+1. **Efficiency**: Quickly find and incorporate existing configurations, reducing the need to reinvent the wheel.
+2. **Standardization**: Promote consistency across projects by using shared packages that adhere to established guidelines.
+3. **Collaboration**: Enhance teamwork by allowing developers to contribute to and benefit from a common set of resources.
+4. **Maintenance**: Simplify updates and maintenance of configurations by managing versions in a single location.
+
+By leveraging CUE Registries, organizations can improve their configuration management processes, foster collaboration, and ensure that their applications are built on a solid foundation of reliable and reusable components.

content/docs/concept/registry/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: concept: registry: page: _

hugo/content/en/docs/concept/module/_index.md

@@ -0,0 +1,108 @@
+---
+title: Modules
+tags: [modules]
+toc_hide: false
+aliases:
+- /docs/concept/modules/
+---
+
+Modules are how CUE manages native dependencies.
+A module contains a tree of CUE
+packages<!--[packages]({{< relref "../package" >}})-->
+alongside metadata that describes the module's identity, version, and its
+dependencies. The metadata is generally managed by
+[`cue mod`]({{<relref "docs/reference/command/cue-help-mod">}})
+commands such as
+[`cue mod init`]({{<relref "docs/reference/command/cue-help-mod-init">}})
+(which initializes a module), and
+[`cue mod tidy`]({{<relref "docs/reference/command/cue-help-mod-tidy">}})
+(which resolves all dependencies in the current module and updates the metadata
+to reflect them).
+
+A module must be initialized and used if any package in the tree needs to
+be referenced by any other package -- whether that other package is inside the
+same module, or in some other module.
+When a package references (or *imports*) a package from a different module, the
+module containing the importing package is said to have a *dependency* on the
+module containing the imported package.
+
+Optionally, modules can be *published* to a
+registry<!--[registry]({{< relref "../registry" >}})-->.
+A published module can be used as a dependency by other modules, and will be
+fetched from the registry, as required, by CUE commands.
+A module only needs to be published when other modules have a dependency on it.
+A module containing a tree of packages that refer to each other (and aren't
+referenced by packages in other modules) does not need to be published -- but
+can be published if so desired.
+
+<!--
+{{<cards>}}
+{{<card title="Importing packages within a module"
+        label="module/local-import"
+        href="."
+>}}
+How using a module allows you to reference one package from another, inside the same package tree.
+{{</card>}}
+
+{{<card title="Do I need to publish my module?"
+        label="module/publishing"
+        href="."
+>}}
+Only certain workflows require modules to be published. Find out about them here ...
+{{</card>}}
+
+{{<card title="Adding a module dependency"
+        label="module/cue-mod-tidy"
+        href="."
+>}}
+Teach CUE that your module needs to use another module ...
+{{</card>}}
+{{</cards>}}
+-->
+
+Learn about CUE modules using the suggested links below, or follow the
+{{<tag modules>}} tag to explore the full range of modules-related pages.
+
+{{<cards>}}
+{{<card title="Reference manual"
+        label="reference/manual"
+        href="/docs/reference/modules/"
+>}}
+The CUE modules reference manual and glossary
+{{</card>}}
+
+{{<card title="Concept Guide"
+        label="concept/faq"
+        href="/docs/concept/faq/new-modules-vs-old-modules/"
+>}}
+CUE's "new" versus "old" modules -- your questions: answered
+{{</card>}}
+
+{{<card title="The cue command"
+        label="reference/command/cue"
+        href="/docs/reference/command/cue-help-modules"
+>}}
+The built-in help text for\
+`cue help modules`
+{{</card>}}
+
+{{<card title="Getting started"
+        label="tutorial"
+        href="/docs/tutorial/working-with-the-central-registry/"
+>}}
+Working with the CUE Central Registry
+{{</card>}}
+{{<card title="Collaborate"
+        label="tutorial"
+        href="/docs/tutorial/publishing-modules-to-the-central-registry/"
+>}}
+Publishing modules to the Central Registry
+{{</card>}}
+
+{{<card title="Private infrastructure"
+        label="tutorial"
+        href="/docs/tutorial/working-with-a-custom-module-registry/"
+>}}
+Working with a custom module registry
+{{</card>}}
+{{</cards>}}