feat: update iam docs

docs/administration/creating-accounts/README.md

@@ -1,55 +0,0 @@
----
-title: "Creating Accounts"
-description: "Create and manage isolated user accounts with their own resources."
-category: "Administration"
-tags:
-  - accounts
-  - iam
-  - admin
-resources:
-  - title: "Spinifex Repository"
-    url: "https://github.com/mulgadc/spinifex"
----
-
-# Creating Accounts
-
-> Create and manage isolated user accounts with their own resources.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Instructions](#instructions)
-- [Troubleshooting](#troubleshooting)
-
----
-
-## Overview
-
-Spinifex supports multi-tenant account isolation. Each account gets its own IAM credentials, AWS CLI profile, and isolated resource namespace.
-
-## Instructions
-
-## Create Account
-
-```bash
-spx admin account create --name myteam
-export AWS_PROFILE=spinifex-myteam
-```
-
-## Troubleshooting
-
-## Credentials Not Working
-
-Verify the AWS CLI configuration files exist and contain the correct profile:
-
-```bash
-cat ~/.aws/config
-cat ~/.aws/credentials
-```
-
-Ensure the `AWS_PROFILE` environment variable matches the profile name:
-
-```bash
-echo $AWS_PROFILE
-export AWS_PROFILE=spinifex-myteam
-```

docs/identity/creating-accounts/README.md

@@ -0,0 +1,96 @@
+---
+title: "Creating Accounts"
+description: "Create and manage isolated user accounts with their own resources."
+category: "Identity"
+tags:
+  - accounts
+  - iam
+  - admin
+resources:
+  - title: "Spinifex Repository"
+    url: "https://github.com/mulgadc/spinifex"
+---
+
+# Creating Accounts
+
+> Create and manage isolated user accounts with their own resources.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Instructions](#instructions)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+Spinifex supports multi-tenant account isolation. Each account gets its own IAM credentials, AWS CLI profile, and isolated resource namespace.
+
+Creating an account provisions a sequential 12-digit account ID, an `admin` user with an `AdministratorAccess` policy attached, and an access key pair. The credentials are written to `~/.aws/credentials` and `~/.aws/config` under a `spinifex-<name>` profile automatically.
+
+## Instructions
+
+## Create Account
+
+Requires a running cluster. Run from a cluster node:
+
+```bash
+spx admin account create --name myteam
+```
+
+```
+Account created successfully!
+  Account ID:        000000000002
+  Account Name:      myteam
+  Admin User:        admin
+  Access Key ID:     AKIA1A2B3C4D5E6F7890ABCD
+  Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+  AWS Profile:       spinifex-myteam
+
+Use with:
+  AWS_PROFILE=spinifex-myteam aws ec2 describe-instances
+```
+
+> **The secret access key is only shown once.** It is saved to `~/.aws/credentials` on the node where you ran the command; copy it from there if you need it elsewhere.
+
+Set the profile to start using the account:
+
+```bash
+export AWS_PROFILE=spinifex-myteam
+aws sts get-caller-identity
+```
+
+To create additional users and scoped permissions within the account, see [IAM Users and Policies](/docs/iam-users-and-policies).
+
+## List Accounts
+
+```bash
+spx admin account list
+```
+
+```
+ACCOUNT ID     NAME                 STATUS     CREATED
+----------     ----                 ------     -------
+000000000000   system               ACTIVE     2026-07-03 02:17
+000000000001   spinifex             ACTIVE     2026-07-03 02:17
+000000000002   myteam               ACTIVE     2026-07-03 03:32
+```
+
+## Troubleshooting
+
+## Credentials Not Working
+
+Verify the AWS CLI configuration files exist and contain the correct profile:
+
+```bash
+cat ~/.aws/config
+cat ~/.aws/credentials
+```
+
+Ensure the `AWS_PROFILE` environment variable matches the profile name:
+
+```bash
+echo $AWS_PROFILE
+export AWS_PROFILE=spinifex-myteam
+```

docs/identity/iam-users-and-policies/README.md

@@ -1,7 +1,7 @@
 ---
 title: "IAM Users and Policies"
 description: "Create IAM users, manage access keys, and control permissions with policies."
-category: "Administration"
+category: "Identity"
 tags:
   - iam
   - users
@@ -37,14 +37,12 @@ resources:
 
 ## Overview
 
-Spinifex implements AWS-compatible IAM with 16 operations covering user management, access key lifecycle, policy CRUD, and policy attachment. All IAM resources are scoped to the account that creates them — users in one account cannot see or modify resources in another.
+Spinifex implements AWS-compatible IAM covering user management, access key lifecycle, policy CRUD, and policy attachment. Inline user policies (`put-user-policy`), user and policy tagging, and IAM roles for EC2 instances (see [IMDS](/docs/imds)) are also supported. All IAM resources are scoped to the account that creates them — users in one account cannot see or modify resources in another.
 
 When you create an account with `spx admin account create`, Spinifex bootstraps a root user with an `AdministratorAccess` policy and writes the credentials to `~/.aws/credentials`. From there, you use the standard AWS CLI to manage additional users and permissions.
 
 **How authentication works:** Every AWS CLI request is signed with SigV4 using an access key pair. The gateway verifies the signature, resolves the caller's account, and evaluates attached policies before routing the request. The root user (account `000000000000`) bypasses policy evaluation entirely.
 
-## Instructions
-
 ## Prerequisites
 
 - A running Spinifex cluster with the AWS gateway started
@@ -55,6 +53,8 @@ When you create an account with `spx admin account create`, Spinifex bootstraps
 export AWS_PROFILE=spinifex-myteam
 ```
 
+## Instructions
+
 ## Users
 
 ### Create a User
@@ -458,6 +458,7 @@ AWS_PROFILE=spinifex-carol aws ec2 terminate-instances --instance-ids i-123
 | `create-policy`               | `--policy-name`, `--policy-document`         | Max 6144 bytes                    |
 | `get-policy`                  | `--policy-arn`                               | Metadata only                     |
 | `get-policy-version`          | `--policy-arn`, `--version-id`               | Use `v1`; includes document       |
+| `list-policy-versions`        | `--policy-arn`                               |                                   |
 | `list-policies`               |                                              |                                   |
 | `delete-policy`               | `--policy-arn`                               | Must not be attached              |
 | `attach-user-policy`          | `--user-name`, `--policy-arn`                | Idempotent                        |