feat(FN-1451): update documentation for team-aware agent import

- Add Agent Import section to README with team hierarchy docs
- Update CLI reference with import source formats and examples
- Add changeset for @gsxdsm/fusion patch release

.changeset/team-aware-agent-import.md

@@ -0,0 +1,5 @@
+---
+"@gsxdsm/fusion": patch
+---
+
+Add team-aware Agent Companies import that preserves manager/report hierarchy from companies.sh packages. The CLI and dashboard now resolve TEAM.md and AGENTS.md references into real reportsTo agent IDs instead of manifest paths.

README.md

@@ -269,8 +269,8 @@ fn mission activate-slice <slice-id>        # Manually activate a pending slice
 ```bash
 fn agent stop <id>                          # Stop a running agent
 fn agent start <id>                         # Start/resume a stopped agent
-fn agent import <file> [--dry-run] [--skip-existing]
-                                            # Import agents from a companies.sh manifest
+fn agent import <source> [--dry-run] [--skip-existing]
+                                            # Import agents from companies.sh packages
 fn agent mailbox <id>                       # View one agent's mailbox
 
 fn message inbox                            # List inbox messages
@@ -415,10 +415,55 @@ Each prompt shows its built-in description, allows text editing, and provides a
 ```bash
 fn agent stop <id>
 fn agent start <id>
-fn agent import <file> [--dry-run] [--skip-existing]
+fn agent import <source> [--dry-run] [--skip-existing]
 fn agent mailbox <id>
 ```
 
+### Agent Import
+
+Fusion can import agents from [companies.sh](https://companies.sh) packages. The importer supports:
+
+- **Single manifest import** — Import a single `AGENTS.md` file as an independent agent
+- **Team package import** — Import a full companies.sh package with `COMPANY.md`, `TEAM.md`, and `AGENTS.md` files
+- **Archive import** — Import from `.tar.gz`, `.tgz`, or `.zip` archives
+
+#### Team Hierarchy
+
+When importing a companies.sh package with team structure, Fusion preserves the manager/report hierarchy:
+
+- Team managers are imported with their defined capabilities and instructions
+- Reports are linked to their manager via the `reportsTo` field using Fusion agent IDs
+- The import summary shows team count and hierarchy links
+
+#### CLI Usage
+
+```bash
+# Import a single agent manifest
+fn agent import ./path/to/AGENTS.md
+
+# Import a full companies.sh package
+fn agent import ./path/to/companies-package/
+
+# Import from archive
+fn agent import ./path/to/package.tar.gz
+
+# Preview without creating
+fn agent import ./path/to/package/ --dry-run
+
+# Skip agents that already exist
+fn agent import ./path/to/package/ --skip-existing
+```
+
+#### Dashboard Import
+
+The Agents view provides a directory picker for importing companies.sh packages:
+
+1. Click **Import** in the Agents view header
+2. Select **Import from Directory** or paste a manifest directly
+3. Choose a companies.sh package folder or single manifest
+4. Preview the import with company/team metadata
+5. Confirm to create agents with hierarchy
+
 ### Per-Agent Heartbeat Configuration
 
 Each agent can override heartbeat behavior through `runtimeConfig`:

docs/cli-reference.md

@@ -219,12 +219,48 @@ Agent runtime operations.
 fn agent stop AGENT-001
 fn agent start AGENT-001
 fn agent mailbox AGENT-001
-fn agent import ./companies-manifest.yaml --dry-run
+fn agent import <source> [--dry-run] [--skip-existing]
 fn agent export ./output-dir --company-name "My Company" --company-slug my-company
 ```
 
 Subcommands: `stop`, `start`, `mailbox`, `import`, `export`.
 
+### `fn agent import`
+
+Import agents from [companies.sh](https://companies.sh) packages. Supports single manifest files, team packages, and archives.
+
+**Source formats:**
+- Single `AGENTS.md` manifest file
+- Companies.sh package directory with `COMPANY.md`, `TEAM.md`, and `AGENTS.md`
+- Archive files (`.tar.gz`, `.tgz`, `.zip`)
+
+**Options:**
+| Option | Description |
+|---|---|
+| `--dry-run` | Preview import without creating agents |
+| `--skip-existing` | Skip agents with names that already exist in Fusion |
+
+**Team hierarchy:**
+When importing a companies.sh package with team structure, the importer preserves manager/report relationships. Agents are linked using Fusion agent IDs (not manifest paths).
+
+**Examples:**
+```bash
+# Import a single agent manifest
+fn agent import ./ceo/AGENTS.md
+
+# Import a full companies.sh package
+fn agent import ./my-company/
+
+# Import from archive
+fn agent import ./package.tar.gz
+
+# Preview without creating
+fn agent import ./package/ --dry-run
+
+# Skip existing agents
+fn agent import ./package/ --skip-existing
+```
+
 ---
 
 ## `fn message`