Address review feedback on token CLI docs

Author: abrookins

docs/authentication.md

@@ -86,7 +86,7 @@ uv run agent-memory token remove abc12345
 # Remove a token without confirmation
 uv run agent-memory token remove abc12345 --force
 ```
-### CI / Terraform token bootstrapping
+### CI/Terraform token bootstrapping
 
 You can use the token CLI to bootstrap authentication tokens in CI pipelines and infrastructure-as-code tools like Terraform.
 
@@ -110,6 +110,21 @@ The example below generates a short-lived token during a workflow run and expose
 ```
 
 Later steps can use `AGENT_MEMORY_TOKEN` as the bearer token when calling the API.
+**JSON output format for `token add`**
+
+When you use `--format json`, `agent-memory token add` returns a JSON object with fields like:
+
+```json
+{
+  "token": "the-plaintext-token",
+  "hash": "abc12345def67890...",
+  "description": "CI bootstrap token",
+  "created_at": "2025-07-10T18:30:00.000000+00:00",
+  "expires_at": "2025-08-09T18:30:00.000000+00:00"
+}
+```
+
+You can extract any of these fields in your scripts (for example, `.token` or `.hash` with `jq`).
 
 #### Terraform example (register a pre-generated token)
 
@@ -121,22 +136,26 @@ variable "agent_memory_token" {
   sensitive = true
 }
 
-resource "null_resource" "agent_memory_token" {
+resource "terraform_data" "agent_memory_token" {
   provisioner "local-exec" {
+    environment = {
+      AGENT_MEMORY_TOKEN = var.agent_memory_token
+    }
+
     command = <<EOT
       TOKEN_JSON=$(agent-memory token add \
         --description "Terraform bootstrap" \
-        --token "${var.agent_memory_token}" \
+        --token "$AGENT_MEMORY_TOKEN" \
         --format json)
       echo "$TOKEN_JSON" > agent-memory-token.json
     EOT
   }
 }
 ```
 
-In both cases, store the plaintext token in a secure secret store (GitHub Actions secrets, Terraform variables, Vault, etc.). The server will hash it before storing, and the CLI will only ever print the plaintext once.
-
+For Terraform versions earlier than 1.4, you can use a `null_resource` instead of `terraform_data`.
 
+In both cases, store the plaintext token in a secure secret store (GitHub Actions secrets, Terraform variables, Vault, etc.). The server will hash it before storing. When the CLI generates a token (without `--token`), it displays the plaintext only once; when using `--token` with a pre-generated value, ensure you've already stored it securely.
 
 **Security Features:**
 - Tokens are hashed using bcrypt before storage

docs/cli.md

@@ -142,7 +142,7 @@ agent-memory token add --description "DESCRIPTION" [--expires-days DAYS] [--form
 - `--description TEXT` / `-d TEXT`: **Required**. Description for the token (e.g., "API access for service X")
 - `--expires-days INTEGER` / `-e INTEGER`: **Optional**. Number of days until token expires. If not specified, token never expires.
 - `--format [text|json]`: **Optional**. Output format. `text` (default) is human-readable; `json` is machine-readable and recommended for CI or scripting.
-- `--token TEXT`: **Optional**. Use a pre-generated token value instead of having the CLI generate one. The CLI will hash and store the token but only prints the plaintext once.
+- `--token TEXT`: **Optional**. Use a pre-generated token value instead of having the CLI generate one. The CLI will hash and store the provided token; make sure you've stored the plaintext securely in your secrets manager or CI system.
 
 **Examples:**
 
@@ -171,6 +171,25 @@ agent-memory token list [--format text|json]
 ```
 
 When `--format json` is used, the command prints a JSON array of token summaries suitable for scripting and CI pipelines. The default `text` format produces human-readable output like the example below.
+**JSON Output Example:**
+```json
+[
+  {
+    "hash": "abc12345def67890xyz",
+    "description": "API access token",
+    "created_at": "2025-07-10T18:30:00.000000+00:00",
+    "expires_at": "2025-08-09T18:30:00.000000+00:00",
+    "status": "Active"
+  },
+  {
+    "hash": "def09876uvw54321...",
+    "description": "Service account token",
+    "created_at": "2025-07-10T19:00:00.000000+00:00",
+    "expires_at": null,
+    "status": "Never Expires"
+  }
+]
+```
 
 **Example Output:**
 ```
@@ -197,6 +216,16 @@ agent-memory token show TOKEN_HASH [--format text|json]
 ```
 
 When `--format json` is used, the command prints a JSON object with token details (including status) suitable for scripting and CI pipelines. The default `text` format produces human-readable output.
+**JSON Output Example:**
+```json
+{
+  "hash": "abc12345def67890xyz",
+  "description": "API access token",
+  "created_at": "2025-07-10T18:30:00.000000+00:00",
+  "expires_at": "2025-08-09T18:30:00.000000+00:00",
+  "status": "Active"
+}
+```
 
 **Arguments:**