Setup Kiro, docs/, web_app_template, and Inventory_Dashboard

Author: phate999

.kiro/hooks/check-docs-before-write.kiro.hook

@@ -0,0 +1,16 @@
+{
+  "enabled": true,
+  "name": "Check Docs Before Writing",
+  "description": "Before writing any Python file, the agent checks the NCM API documentation and known issues to ensure the code follows documented patterns and avoids known gotchas.",
+  "version": "1",
+  "when": {
+    "type": "preToolUse",
+    "toolTypes": [
+      "write"
+    ]
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "Check if the file being written is a Python (.py) file. If it is NOT a .py file (e.g., it's a .md, .json, .css, .html, or other non-Python file), skip this check entirely and proceed with the write. If it IS a .py file, verify: (1) Have you consulted the relevant docs in docs/ for the API endpoints being used? (2) Have you checked docs/known-issues.md for gotchas? (3) Are you following the patterns in docs/common-patterns.md? (4) Are all API URLs using trailing slashes? (5) Is error handling with retries included? (6) Does the script call check_env() from utils.env_check at startup? If you haven't consulted the docs yet, read the relevant ones now before proceeding."
+  }
+}

.kiro/hooks/fix-errors-after-run.kiro.hook

@@ -0,0 +1,16 @@
+{
+  "enabled": true,
+  "name": "Fix Errors After Run",
+  "description": "After running any shell command (typically tests or script execution), the agent reviews the output for errors and iterates on fixes until the code runs clean.",
+  "version": "1",
+  "when": {
+    "type": "postToolUse",
+    "toolTypes": [
+      "shell"
+    ]
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "Review the output of the command that just ran. If there are any errors (syntax errors, import errors, runtime exceptions, API errors), diagnose the root cause and fix the code. Re-run until clean. If the error reveals something about the API that isn't documented, make a note to update docs in the reflexion step."
+  }
+}

.kiro/hooks/reflexion-update-docs.kiro.hook

@@ -0,0 +1,13 @@
+{
+  "enabled": true,
+  "name": "Reflexion: Update Docs",
+  "description": "After the agent stops, it reviews whether any new API behaviors, gotchas, or patterns were discovered during the session and updates docs/known-issues.md, docs/common-patterns.md, and docs/CHANGELOG.md accordingly. Only updates docs for generally applicable discoveries, not app-specific ones.",
+  "version": "1",
+  "when": {
+    "type": "agentStop"
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "Review the work you just completed. Did you discover any new API behaviors, gotchas, workarounds, or reusable patterns that are NOT already documented in docs/known-issues.md or docs/common-patterns.md? If yes, and if the discovery applies generally (not just to this specific app), update the relevant docs file and append an entry to docs/CHANGELOG.md. If nothing new was discovered, do nothing."
+  }
+}

.kiro/steering/code-standards.md

@@ -0,0 +1,134 @@
+---
+inclusion: auto
+---
+
+# Code Standards for NCM Scripts
+
+## Virtual Environment
+
+**Always use the project `.venv`**. Never run scripts with the system Python.
+
+When running any script or command, use:
+```bash
+.venv/bin/python scripts/my_script.py
+```
+
+When installing packages:
+```bash
+.venv/bin/pip install -r requirements.txt
+```
+
+The venv uses Python 3.12 and is located at the project root `.venv/`.
+
+## Required Environment Variables
+
+All scripts require these environment variables for API authentication:
+
+| Variable | Description |
+|----------|-------------|
+| `CP_API_ID` | Cradlepoint API ID |
+| `CP_API_KEY` | Cradlepoint API Key |
+| `ECM_API_ID` | ECM API ID |
+| `ECM_API_KEY` | ECM API Key |
+
+Optional (for v3 API):
+
+| Variable | Description |
+|----------|-------------|
+| `CP_API_TOKEN` | Bearer token for API v3 |
+
+### If env vars are not set, scripts must detect this and print setup instructions.
+
+Use the helper at `scripts/utils/env_check.py` (see below) to validate at script startup.
+
+### How to set env vars by OS:
+
+**Recommended: Use the setup script**
+```bash
+.venv/bin/python setup_env.py
+```
+This prompts for all keys (including v3 token), injects them into the `.venv/bin/activate`
+scripts, and they load automatically every time you `source .venv/bin/activate`.
+Run it again anytime to update credentials.
+
+**Manual setup — macOS / Linux (bash/zsh):**
+```bash
+export CP_API_ID="your_cp_api_id"
+export CP_API_KEY="your_cp_api_key"
+export ECM_API_ID="your_ecm_api_id"
+export ECM_API_KEY="your_ecm_api_key"
+export CP_API_TOKEN="your_v3_token"  # optional, for v3 API
+```
+To persist, add these to `~/.zshrc` (macOS) or `~/.bashrc` (Linux).
+
+**Windows (PowerShell):**
+```powershell
+$env:CP_API_ID = "your_cp_api_id"
+$env:CP_API_KEY = "your_cp_api_key"
+$env:ECM_API_ID = "your_ecm_api_id"
+$env:ECM_API_KEY = "your_ecm_api_key"
+$env:CP_API_TOKEN = "your_v3_token"  # optional, for v3 API
+```
+To persist, use System Properties → Environment Variables, or add to your PowerShell profile.
+
+**Windows (Command Prompt):**
+```cmd
+set CP_API_ID=your_cp_api_id
+set CP_API_KEY=your_cp_api_key
+set ECM_API_ID=your_ecm_api_id
+set ECM_API_KEY=your_ecm_api_key
+set CP_API_TOKEN=your_v3_token  &REM optional, for v3 API
+```
+
+## File Structure
+
+All new scripts should follow this structure:
+```python
+"""
+Script description.
+"""
+import os
+import sys
+
+# Add project root to path if needed
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
+
+from utils.env_check import check_env
+from utils.credentials import get_credentials
+from utils.session import APISession
+from utils.logger import get_logger
+
+def main():
+    """Main entry point."""
+    check_env()  # Always call first — exits with instructions if vars missing
+    # ... implementation
+
+if __name__ == '__main__':
+    main()
+```
+
+## Authentication
+
+- Never hardcode API keys in source files
+- Use environment variables (preferred) or `scripts/utils/credentials.py` as fallback
+- For the NCM SDK: pass keys as a dictionary
+- For direct API calls: use `scripts/utils/session.py`
+
+## Error Handling
+
+- Always wrap API calls in try/except
+- Implement retry logic for transient errors (408, 429, 503, 504)
+- Log errors with context (which endpoint, what parameters)
+
+## Output
+
+- Use CSV for tabular data exports
+- Use JSON for structured data
+- Print progress for long-running operations
+- Store output files in `scripts/script_manager/csv_files/` when using script_manager
+
+## Dependencies
+
+- Core: `requests`, `ncm` (SDK)
+- Check `requirements.txt` before adding new dependencies
+- If a new dependency is needed, add it to `requirements.txt`

.kiro/steering/ncm-api-development.md

@@ -0,0 +1,74 @@
+---
+inclusion: auto
+---
+
+# NetCloud Manager API Development Guide
+
+## Reflexion Workflow
+
+When building any application that uses the Cradlepoint NetCloud Manager API, follow this workflow:
+
+### 1. Consult Documentation First
+Before writing any code, read the relevant documentation in `docs/`:
+- `docs/api-overview.md` — for auth, base URLs, pagination, filtering
+- `docs/api-v2-endpoints.md` — for v2 endpoint details
+- `docs/api-v3-endpoints.md` — for v3 endpoint details
+- `docs/api-configuration.md` — for device/group configuration
+- `docs/api-webhooks.md` — for webhook setup
+- `docs/ncm-sdk-reference.md` — for Python SDK methods
+- `docs/common-patterns.md` — for reusable code patterns
+- `docs/known-issues.md` — for gotchas and workarounds
+
+### 2. Choose the Right Approach
+- Use the NCM SDK (`from ncm import ncm`) when possible — it handles pagination, retries, auth
+- Use `scripts/utils/session.py` for direct API calls with automatic retry/pagination
+- Use raw `requests` only when SDK/session don't cover the use case
+
+### 3. Build and Test
+- Write the code following patterns in `docs/common-patterns.md`
+- Run the code and check for errors
+- Fix errors iteratively until clean
+
+### 4. Reflexion — Update Documentation
+After completing any task, evaluate whether you discovered anything new:
+- **New API behavior** not documented → update the relevant `docs/*.md` file
+- **Bug or gotcha** discovered → append to `docs/known-issues.md`
+- **New reusable pattern** → add to `docs/common-patterns.md`
+- **Documentation was wrong** → fix it and log the change in `docs/CHANGELOG.md`
+- **Only applies to this specific app** → do NOT update docs (keep docs general)
+
+## Endpoint Routing Guide
+
+Use this to quickly find which doc and SDK method to use for a given task:
+
+| Task | Doc File | SDK Methods |
+|------|----------|-------------|
+| List/manage routers | api-v2-endpoints.md → routers | `get_routers()`, `get_router_by_id()` |
+| Router online/offline status | api-v2-endpoints.md → router_state_samples | `get_router_state_samples()` |
+| Push device config | api-configuration.md | `patch_configuration_managers()`, `put_configuration_managers()` |
+| Push group config | api-configuration.md | `patch_group_configuration()`, `put_group_configuration()` |
+| Get/set locations | api-v2-endpoints.md → locations | `get_locations()`, `get_historical_locations()` |
+| Manage alerts | api-v2-endpoints.md → alerts | `get_alerts()`, `get_router_alerts()` |
+| Setup webhooks | api-webhooks.md | Direct API calls to `alert_push_destinations` |
+| Manage groups | api-v2-endpoints.md → groups | `get_groups()`, `create_group_by_parent_id()` |
+| Network device info | api-v2-endpoints.md → net_devices | `get_net_devices()`, `get_net_device_metrics()` |
+| Signal/usage data | api-v2-endpoints.md → net_device_signal/usage | `get_net_device_signal_samples()`, `get_net_device_usage_samples()` |
+| Firmware info | api-v2-endpoints.md → firmwares | `get_firmwares()` |
+| Reboot devices | api-v2-endpoints.md → reboot_activity | `reboot_device()`, `reboot_group()` |
+| Speed tests | api-v2-endpoints.md → speed_test | `create_speed_test()` |
+| Manage users | api-v3-endpoints.md → users | `get_users()`, `create_user()` |
+| Subscriptions | api-v3-endpoints.md → subscriptions | `get_subscriptions()`, `regrade()` |
+| Private cellular | api-v3-endpoints.md → private_cellular_* | `get_private_cellular_networks()`, etc. |
+| NCX sites/resources | api-v3-endpoints.md → exchange_* | `get_exchange_sites()`, `create_exchange_site()` |
+| Export data to CSV | common-patterns.md | `export_to_csv()` pattern |
+| Batch operations | common-patterns.md | `batch_operation()` pattern |
+
+## Critical Rules (Always Follow)
+
+1. **Trailing slash**: ALL v2 URLs must end with `/`
+2. **Config manager ID ≠ Router ID**: Always look up the config manager ID first
+3. **PATCH vs PUT**: PATCH merges, PUT replaces. Use PATCH for incremental changes
+4. **_id_ fields**: When using UUID keys, include `_id_` inside the object too
+5. **Check deprecations**: Before using any endpoint, verify it's not deprecated in `docs/api-deprecations.md`
+6. **Error handling**: Always implement retry logic with exponential backoff
+7. **Pagination**: Always handle pagination for list endpoints (SDK does this automatically)

.kiro/steering/reflexion-workflow.md

@@ -0,0 +1,91 @@
+---
+inclusion: auto
+---
+
+# Reflexion Workflow System
+
+## Purpose
+
+This steering file defines the reflexion loop: a self-improving workflow where the AI
+updates its own documentation and steering rules when it discovers new information
+during development.
+
+## The Reflexion Loop
+
+```
+User Request → Consult Docs → Build Code → Test → Fix Errors → Reflect → Update Docs
+                  ↑                                                          |
+                  └──────────────────────────────────────────────────────────┘
+```
+
+## When Building Any NCM Application
+
+### Step 1: Understand the Request
+- Identify which API endpoints are needed
+- Check `#[[file:docs/api-overview.md]]` for API basics
+- Use the Endpoint Routing Guide in the NCM steering to find the right docs
+
+### Step 2: Check Known Issues
+- Read `#[[file:docs/known-issues.md]]` before writing code
+- Avoid known pitfalls
+
+### Step 3: Write Code
+- Follow patterns from `#[[file:docs/common-patterns.md]]`
+- Use the NCM SDK when possible
+- Include proper error handling and retry logic
+
+### Step 4: Test
+- Run the code
+- Check for syntax errors, import errors, runtime errors
+- Verify output matches expectations
+
+### Step 5: Fix Errors
+- If errors occur, diagnose and fix
+- Re-run until clean
+- If the error reveals a documentation gap, note it for Step 6
+
+### Step 6: Reflect and Update
+After completing the task, ask yourself:
+
+**Should I update documentation?** Update if:
+- You discovered an API behavior not documented in `docs/`
+- You found a documentation error
+- You created a reusable pattern others could benefit from
+- You hit a gotcha that should be warned about
+
+**Should I NOT update documentation?** Skip if:
+- The discovery is specific to this one application
+- It's a user-specific configuration issue
+- It's already documented
+
+**What to update:**
+- `docs/known-issues.md` — append new gotchas under "Discovered Issues Log"
+- `docs/common-patterns.md` — add new reusable patterns
+- `docs/CHANGELOG.md` — log what changed and why
+- Relevant `docs/*.md` file — fix errors or add missing info
+- `.kiro/steering/*.md` — update routing guide if new endpoint patterns discovered
+
+## Documentation Update Format
+
+When appending to `docs/known-issues.md`:
+```markdown
+### [Short Title] (discovered YYYY-MM-DD)
+[Description of the issue and workaround]
+```
+
+When appending to `docs/CHANGELOG.md`:
+```markdown
+## YYYY-MM-DD — [Brief Description]
+- [What changed and why]
+```
+
+## Quality Gates
+
+Before considering any NCM application complete:
+1. Code runs without errors
+2. All API calls use proper authentication
+3. All URLs have trailing slashes
+4. Pagination is handled for list operations
+5. Error handling with retries is implemented
+6. No deprecated endpoints are used
+7. Documentation has been updated if applicable