csw-tools 0.3.0__tar.gz

csw_tools-0.3.0/.python-version

@@ -0,0 +1 @@
+3.12

csw_tools-0.3.0/DEV-GUIDELINES.md

@@ -0,0 +1,241 @@
+# csw-tools developer guidelines
+
+This document describes the shared framework used by every command. End-user
+and command-specific behavior belongs in the command README linked from the
+root [README.md](README.md).
+
+## Project layout
+
+```text
+csw-tools/
+├── pyproject.toml              Project metadata, dependencies and tool settings
+├── uv.lock                     Locked development dependency graph
+├── .python-version             Project Python target used by uv/pyenv
+├── src/csw_tools/
+│   ├── cli.py                  Root Click group and command registration
+│   ├── context.py              Per-invocation AppContext
+│   ├── config.py               TOML loading and setting resolution
+│   ├── config_defaults.py      Shared constants and backend defaults
+│   ├── dashboard.py            Dashboard validation and normalization
+│   ├── dashboard_context.py    Dashboard command decorator
+│   ├── csw_api.py              tetpyclient construction and checked API facade
+│   ├── keyring_store.py        Testable operating-system keyring adapter
+│   ├── interaction.py          Interactive-terminal safeguard
+│   ├── change_control.py       Backup creation, persistence and validation
+│   ├── project_info.py         Diagnostic version metadata
+│   └── commands/               One subpackage and README per command
+└── tests/                      pytest coverage for shared and command behavior
+```
+
+`pyproject.toml` is the source of package metadata and dependency declarations.
+The package version is defined there only. `.python-version` selects the project
+interpreter; the packaged `project-python-version.txt` mirrors it so an installed
+wheel can report the same target. A test prevents those values from drifting.
+
+## Command entrypoint: inputs and outputs
+
+The console entrypoint declared in `pyproject.toml` calls `csw_tools.cli:cli`.
+The root Click group validates common inputs, builds one `AppContext`, and lets
+Click pass that object to the selected command.
+
+```text
+CLI arguments ─┐
+config.toml ────┼─> root Click group ─> AppContext ─> selected command
+backend defaults┘                         │
+                                          ├─ resolved settings
+interactive prompt (when still needed) ──┤
+OS keyring (lazy) ────────────────────────┤
+                                          ├─ Common output directory
+                                          ├─ Rich stdout console
+                                          └─ Rich stderr console
+```
+
+Settings resolve in this order:
+
+1. CLI value
+2. Command or common `config.toml` value
+3. Backend default
+4. Interactive prompt when the value is required and still unresolved
+
+Global options must precede the command. Command-specific configuration tables
+become Click `default_map` entries, so Click performs the final CLI-over-config
+selection for command options. A command can also inspect its validated table
+with `app.config_for(command_name)`.
+
+Normal results go to `app.console` on stdout. Warnings, progress, and diagnostic
+messages go to `app.error_console` on stderr. Use Rich tables and panels through
+those shared consoles; do not create new consoles inside a command. Expected
+usage, configuration, backup, or API failures should become `click.UsageError`
+or `click.ClickException` so callers receive a useful message and nonzero exit.
+
+`[common].output_dir` and the global `--output-dir` select one shared location
+for command-owned backups, journals, reports, and logs. Relative paths resolve
+from the current working directory. Commands choose their own filenames and
+formats but use `app.output_dir` instead of defining directory options.
+
+CLI transcript logging is controlled by `[common].log_cli_output` and
+`--log-cli-output/--no-log-cli-output`, and is enabled by default. The root group
+tees application-emitted stdout and stderr to one ANSI-free text file while
+preserving the original terminal streams. It suppresses entered prompt values
+and remains active through Click's final handled-error rendering. Root help,
+eager version output, unknown commands, and configuration failures that occur
+before common settings resolve are intentionally not logged.
+
+## Click command structure
+
+Each command is a subpackage under `src/csw_tools/commands/` with an
+`__init__.py`, `command.py`, and `README.md`. Export its Click command from the
+subpackage, import it in `cli.py`, and register it with `cli.add_command(...)`.
+
+A dashboard-backed interactive command normally follows this shape:
+
+```python
+@click.command("example")
+@click.option("--value")
+@pass_app_context
+@interactive_command
+@dashboard_command
+def command(app: AppContext, value: str | None) -> None: ...
+```
+
+Decorator order is significant. `pass_app_context` supplies the shared object,
+`interactive_command` rejects redirected/non-terminal stdin before prompting,
+and `dashboard_command` resolves the dashboard, activates dashboard-scoped
+services, and prints the dashboard panel. A deliberately non-interactive mode
+requires a command-specific guard and explicit safety design.
+
+Click owns option parsing and help. Keep the command docstring useful because it
+is the authoritative `COMMAND --help` text. Rich owns presentation after inputs
+are valid. Never let formatting truncate identifiers needed to review a change.
+
+## Shared context and configuration
+
+`AppContext` contains validated configuration, the selected config path, the
+base keyring service name, normalized dashboard state, TLS verification, and
+the two Rich consoles. It contains a keyring accessor, not plaintext secrets.
+
+`config.py` validates known TOML sections and common value types. Unknown
+sections and common keys fail early rather than being silently ignored. The
+removed command-level `backup_dir` setting fails with a migration message rather
+than being ignored.
+`config_defaults.py` is for true backend defaults and fixed identifiers. Add a
+command name and config section there when its options may be configured.
+
+The default user config is OS-native. An explicit `--config` path must exist for
+normal commands; the implicit default is optional. Commands should receive
+resolved values from Click/AppContext rather than reparsing TOML themselves.
+
+## Dashboard, credentials, and CSW API
+
+`dashboard.py` accepts a SaaS short name, any valid ASCII FQDN, or an HTTPS
+origin. A short name expands under `tetrationcloud.com`; a dotted non-SaaS FQDN
+normalizes to the same URL-based identity as its explicit HTTPS form. IP
+addresses and ambiguous single-label on-premises hosts require the explicit
+URL. Normalization rejects user information, paths, queries, fragments, and
+custom ports so API endpoints and keyring namespaces are unambiguous.
+
+`dashboard_command` prompts only if no dashboard was supplied, calls
+`AppContext.activate_dashboard()`, and displays the canonical selection. The
+activation appends the dashboard name to the base keyring service, isolating
+credentials between organizations. Its Rich panel shows a display name and the
+canonical URL using markup-safe text objects.
+
+`create_api_client()` retrieves the fixed API-key and secret usernames lazily
+from `KeyringStore` and constructs `tetpyclient.RestClient` with the normalized
+HTTPS endpoint and configured TLS verification. Never write credentials to
+configuration, logs, backups, exception text, or Rich output.
+
+`CswApi` is the checked facade around `tetpyclient`. It centralizes request
+encoding, HTTP status checks, JSON decoding, common CSW operations, and inventory
+pagination. Unexpected response shapes, repeated offsets, or invalid JSON fail
+closed with `CswRequestError`. Put shared, stable operations here; keep
+release-specific or command-only adapters inside that command's package.
+
+Use only the API permissions a command needs and document them in its README.
+Keep TLS verification enabled unless the user explicitly disables it for a
+trusted deployment.
+
+## Rich, interaction, and change control
+
+Use Rich for human-reviewable panels, tables, warnings, and summaries. Preserve
+full object identifiers and identifying name tails. Markup must be disabled for
+untrusted dashboard/API text when it could be interpreted as Rich markup.
+
+Most commands use `interactive_command` because their workflows can prompt for
+missing settings or approvals. Help and the eager `--version` option must remain
+usable without a terminal and before configuration or dashboard resolution.
+
+Mutating commands should default to dry-run and use the helpers in
+`commands/common.py` and `change_control.py`. Create the backup before the first
+mutation, journal attempted and completed operations atomically, verify command
+and dashboard identity during recovery, and stop further mutations if the
+journal cannot be persisted. Write those artifacts beneath `app.output_dir` and
+define recovery limitations in the command README.
+
+## Core setup commands
+
+### `init`
+
+The root CLI uses valid existing common output settings for `init`, but falls
+back to CLI/backend defaults when the existing configuration is missing or
+invalid so it can still be replaced. The command receives the resolved target
+through `AppContext.config_path`, reads the packaged example with
+`importlib.resources`, writes beside the target, and atomically replaces it only
+after confirmation. After any successful create, replace, or retain path, it
+offers to open the containing directory through the native desktop launcher.
+Launcher errors are warnings and do not turn successful initialization into a
+failure. It does not activate a dashboard or keyring.
+
+### `configure-credentials`
+
+This command uses the normal interactive and dashboard decorators. Dashboard
+activation constructs the scoped keyring service before the command checks the
+two fixed usernames. The stored API key is partially masked, and the API secret
+is never displayed. New-value prompts hide each one, collect it once, and report
+only its character count. Keyring errors must never include secrets and should
+warn that separate writes may leave an incomplete pair.
+
+See the command READMEs for complete user-facing details:
+
+- [`init`](src/csw_tools/commands/init/README.md)
+- [`configure-credentials`](src/csw_tools/commands/configure_credentials/README.md)
+
+## Adding or changing a command
+
+1. Create or update its command subpackage and README.
+2. Define Click arguments/options and their backend defaults without duplicating
+   global configuration or dashboard setup.
+3. Register new config sections/constants and the command in the root CLI.
+4. Use shared context, API, output, interaction, and backup helpers where their
+   contracts apply.
+5. Document inputs, required API capabilities, dry-run/apply semantics, failure
+   behavior, recovery limits, and command-specific architecture.
+6. Add unit tests for parsing/planning and CLI tests for help, success, failure,
+   output, interactive safety, API validation, and partial mutation handling.
+
+Do not put command-specific implementation notes in this file. Link to the
+command README instead.
+
+## Development workflow
+
+Install the Python 3.12 locked environment and run the CLI:
+
+```console
+uv sync
+uv run csw-tools --help
+uv run csw-tools --version
+```
+
+Run all checks before submitting changes:
+
+```console
+uv run ruff format --check .
+uv run ruff check .
+uv run pytest
+uv lock --check
+uv build
+```
+
+`uv build` uses the `uv_build` backend configured in `pyproject.toml`. Test the
+built wheel from outside the checkout when changing packaged resources,
+entrypoints, or version reporting.

csw_tools-0.3.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

csw_tools-0.3.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: csw-tools
+Version: 0.3.0
+Summary: A collection of automation utilities for Cisco Secure Workload (CSW), available through this single package.
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Dist: click>=8.4.2
+Requires-Dist: keyring>=25.7.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: tetpyclient>=1.0.8
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/structured-com/csw-tools
+Project-URL: Issues, https://github.com/structured-com/csw-tools/issues
+Description-Content-Type: text/markdown
+
+# csw-tools
+
+A collection of automation utilities for Cisco Secure Workload (CSW, formerly
+Tetration), available through a single command-line package.
+
+## Current utilities
+
+**These core utilities set up `csw-tools` for general use:**
+
+| Command | Description | Documentation |
+|---|---|---|
+| `init` | Create or replace the per-user `config.toml` | [Guide](src/csw_tools/commands/init/README.md) |
+| `configure-credentials` | Inspect or replace CSW API credentials in the OS keyring | [Guide](src/csw_tools/commands/configure_credentials/README.md) |
+
+**The following command is implemented for production use:**
+
+| Command | Description | Documentation |
+|---|---|---|
+| `create-scopes` | Create scopes in bulk from CSV | [Guide](src/csw_tools/commands/create_scopes/README.md) |
+
+**The following commands are in DEV/TESTING state and generally should not be used in production yet:**
+
+| Command | Description | Documentation |
+|---|---|---|
+| `clean-stale-labels` | Remove old static labels for workloads absent from current inventory | [Guide](src/csw_tools/commands/clean_stale_labels/README.md) |
+| `convert-labels` | Persist observed inventory fields as per-workload static labels | [Guide](src/csw_tools/commands/convert_labels/README.md) |
+| `prune-agents` | Preview and destructively decommission stale agents and clean explicit related objects | [Guide](src/csw_tools/commands/prune_agents/README.md) |
+| `prune-policy` | Not implemented: remove or filter entries within a workspace policy | [Guide](src/csw_tools/commands/prune_policy/README.md) |
+| `sync-collection-rules` | Not implemented: validate collection rules against scope and filter IPs | [Guide](src/csw_tools/commands/sync_collection_rules/README.md) |
+
+## Installation
+
+The project requires Python 3.12 or later. [uv](https://docs.astral.sh/uv/) is
+the preferred installation and development tool, although normal Python package
+installation also works.
+
+Once uv is installed, install the package as a tool:
+
+```console
+uv tool install csw-tools
+```
+
+## Usage
+
+List the available commands, common options, and project version information:
+
+```console
+csw-tools --help
+csw-tools --version
+```
+
+Global options must appear before the command name. The command and its own
+options follow:
+
+```console
+csw-tools create-scopes scopes.csv
+csw-tools --dashboard my-company.tetrationcloud.com prune-agents
+csw-tools -d my-company configure-credentials
+```
+
+Command-generated files use `csw-tools-outputs/` in the current working
+directory and a basic CLI log is enabled by default.
+
+Every command's guide is linked from the tables above. The command help is the
+authoritative option list:
+
+```console
+csw-tools COMMAND --help
+```
+
+## CSW Dashboard Selection
+
+A dashboard may be supplied as its short SaaS name, a full FQDN, or an HTTPS
+origin:
+
+```console
+csw-tools -d my-company COMMAND
+csw-tools -d my-company.tetrationcloud.com COMMAND
+csw-tools -d mycsw.example.org COMMAND
+csw-tools -d https://mycsw.example.org COMMAND
+```
+
+A short name is auto-appended by default with `.tetrationcloud.com`. Any FQDN is used as
+given with HTTPS. IP addresses and single-label on-premises hosts require HTTPS:// explicitly, such as `-d https://192.0.2.10` or
+`-d https://csw-local`. 
+
+TLS certificate verification is enabled by default. Use
+`--no-dashboard-verify-tls` only for a trusted deployment whose certificate
+cannot be validated normally.
+
+## Configuration
+
+Settings are resolved in this order:
+
+1. CLI arguments
+2. `config.toml` values
+3. Backend defaults from `config_defaults.py`
+4. Interactive prompt for an unresolved required value
+
+`config.toml` is optional but useful for values that are reused often. Create
+or replace it interactively with:
+
+```console
+csw-tools init
+```
+
+This copies the packaged
+[`config.example.toml`](src/csw_tools/config.example.toml) to the OS-native
+per-user location:
+
+- macOS: `~/Library/Application Support/csw-tools/config.toml`
+- Linux: `${XDG_CONFIG_HOME:-~/.config}/csw-tools/config.toml`
+- Windows: `%APPDATA%\csw-tools\config.toml`
+
+If needed, use `--config PATH` before the command name to select a different file.
+
+Common output behavior can be reused across every command:
+
+```toml
+[common]
+output_dir = "csw-tools-outputs"
+log_cli_output = true
+```
+
+Relative output paths are resolved from the current working directory. Absolute
+paths and paths beginning with `~` are also accepted. CLI transcript logging is
+enabled by default; disable it for one run with `--no-log-cli-output` before the
+command name. Each transcript combines stdout and stderr in a plain-text file
+named `csw-tools-COMMAND-YYYYMMDDTHHMMSSmmmZ.log`, prints its absolute path to
+stderr in quotes when logging starts, and never records entered prompt values.
+Root help, version output, unknown commands, and errors raised before
+configuration can be resolved do not create transcripts.
+
+## Credentials
+
+Secrets are stored through the operating system keyring and are never written
+to `config.toml` or a backup. For a dashboard named `my-company`, the default
+identifiers are:
+
+| Service name | Username | Stored value |
+|---|---|---|
+| `csw-tools:my-company` | `csw:api_key` | CSW API key |
+| `csw-tools:my-company` | `csw:api_secret` | CSW API secret |
+
+Inspect or replace the credential pair interactively:
+
+```console
+csw-tools -d my-company configure-credentials
+```
+
+(If using a CSW Dashboard that is not `.tetrationcloud.com`, then the full HTTPS url is used instead as part of the service name)
+
+## Safe Change Workflow
+
+Mutating commands default to `--dry-run`; review the complete plan before using
+`--apply`. Supported commands create a timestamped JSON backup before the first
+API mutation in the common output directory and update it around each attempted
+operation. Keep backups until the results have been validated.
+
+Rollback support and limitations differ by command. Read the individual command
+guide before applying or recovering changes. Agent decommissioning has no true
+rollback.
+
+## Development
+
+See [DEV-GUIDELINES.md](DEV-GUIDELINES.md) for architecture, shared APIs,
+contributor workflow, and project checks.