docs: update htg and ref landing pages

Author: tmihoc

explanation/cli_tools.md

@@ -1,4 +1,4 @@
-# Understanding `juju` vs `jaas` vs `jimmctl`
+# `juju` vs. `jaas` vs. `jimmctl`
 
 This document aims to explain the differences between the various CLI tools you may encounter when using Juju and JAAS.
 

howto/index.md

@@ -3,59 +3,54 @@
 
 These how-to guides cover key operations and processes in JAAS.
 
+<!--
 ```{toctree}
 :titlesonly:
 :glob:
 
 *
 ```
+-->
 
-
-<!--
-## Configuration
-
-After JAAS has been deployed, you need to configure it with your Juju operated cluster.
-
-```{toctree}
-:maxdepth: 2
-
-Bootstrap permissions <bootstrap_permissions>
-Add a controller to JAAS <add_controller>
-Migrate models to JAAS <migrate_models>
-Migrate models internally <migrate_models_internal>
-Use Terraform for configuration <use_terraform>
-```
-
-## Observability
+## Your JAAS deployment, the bird's eye
 
 ```{toctree}
-:maxdepth: 2
+:titlesonly:
+:glob:
 
-Integrate with the Canonical Observability Stack <integrate_with_cos>
+manage-your-jaas-deployment
 ```
 
-## Security
+## Juju in JAAS
 
 ```{toctree}
-:maxdepth: 2
+:titlesonly:
+:glob:
 
-Harden JIMM deployment <security_hardening>
-Set up Ingress with TLS <setup_ingress_with_tls>
+manage-juju-controllers
+manage-clouds
+manage-models
+manage-offers
 ```
 
-## Juju Dashboard
+## Authorization with JAAS
 
 ```{toctree}
-:maxdepth: 2
+:titlesonly:
+:glob:
 
-Set up Juju Dashboard <setup_dashboard>
+manage-users
+manage-service-accounts
+manage-roles
+manage-groups
+manage-relations
 ```
 
-## Access
+## JAAS with Terraform
 
 ```{toctree}
-:maxdepth: 2
+:titlesonly:
+:glob:
 
-Set up new users <setup_new_users>
-```
--->
+use_terraform
+```

howto/manage-service-accounts.md

@@ -1,6 +1,6 @@
 (manage-service-accounts)=
 # Manage service accounts
-<!-->> See also: {ref}`service account`-->
+> See also: {ref}`service-account`
 
 (manage-a-service-accounts-relation-to-an-entity)=
 ## Manage a service account's relation to an entity

redirects.txt

@@ -44,3 +44,4 @@ reference/jaas/security_hardening/ reference/jaas/security/
 reference/jaas/jaas_architecture/ reference/jaas/jaas-architecture/
 reference/jaas/security/ reference/jaas/jaas-security/
 reference/jaas/supported-juju-versions/ reference/jaas/jaas-supported-juju-versions/
+reference/audit_logs/ reference/jimmctl-audit-events

reference/index.md

@@ -6,44 +6,44 @@
 ```{toctree}
 :titlesonly:
 :glob:
+:hidden:
 
 *
 ```
 
-<!--
+## JAAS at a glance
 
-## Security
+- {ref}`jaas`
+    - {ref}`jaas-architecture`
+    - {ref}`jaas-authentication`
+    - {ref}`jaas-authorization`
+    - {ref}`jaas-rebac-admin-backend`
+    - {ref}`jaas-security-scope`
+    - {ref}`jaas-security-overview`
+    - {ref}`jaas-supported-juju-versions`
 
-```{toctree}
-:maxdepth: 1
-
-JAAS Security <security>
-Audit Logs <audit_logs>
-```
 
-## Authorisation
+## JAAS Entities
 
-```{toctree}
-:maxdepth: 1
+Items marked with an asterisk are Juju entities enhanced in JAAS. <br>
+Unmarked items are JAAS-specific.
 
-Authorisation Model <authorisation_model>
-Authorisation Data <authorisation_data>
-ReBAC Admin Backend <rebac_admin_backend>
-```
+- {ref}`cloud`*
+- {ref}`controller`*
+- {ref}`group`
+- {ref}`model`*
+- {ref}`offer`*
+- {ref}`relation`
+- {ref}`role`
+- {ref}`service-account`
+- {ref}`tag`
+- {ref}`user`*
 
-## Support
+## JAAS Tools
 
 ```{toctree}
-:maxdepth: 1
-
-Supported Juju versions <juju_required_version>
-```
-
-## CLI Reference
-
-```{toctree}
-:maxdepth: 1
+:titlesonly:
 
-jimmctl CLI reference <jimmctl>
+jimmctl
+jimmctl-audit-events
 ```
--->

reference/jaas/jaas-rebac-admin-backend.md

@@ -1,3 +1,4 @@
+(jaas-rebac-admin-backend)=
 # ReBAC admin backend
 
 The ReBAC Admin API is a REST API that provides various endpoints to query or

reference/jaas/jaas-security-scope.md

@@ -1,4 +1,5 @@
-# Security Scope
+(jaas-security-scope)=
+# Security scope
 
 <!--   TODO (Kian):
    Much of this document's content is now covered in the security doc in reference/security and reused where possible.

reference/jaas/jaas-security.md

@@ -1,3 +1,4 @@
+(jaas-security-overview)=
 # Security overview
 
 This document provides an overview of JAAS security measures, focusing on areas related to

reference/jaas/jaas-supported-juju-versions.md

@@ -1,4 +1,4 @@
-(supported-juju-versions)=
+(jaas-supported-juju-versions)=
 # Supported Juju versions
 
 The following sections describe which version of the Juju CLI or controller is required for different scenarios.

reference/audit_logs.md renamed to reference/jimmctl-audit-events.md

@@ -1,6 +1,4 @@
-# JAAS: Understanding Audit Logs
-
-## Introduction
+# `jimmctl audit-events` details
 
 JIMM provides audit logging functionality, tracking all requests/responses into the system.
 This gives administrators of JIMM the ability to audit changes at a very granular level.