# Gridfox API Skill

Use this skill when you need to inspect a Gridfox project and seed realistic, relationship-aware demo data.

Prefer the `Gridfox.ApiSkill` PowerShell module and declarative seed plans. Do not write one-off API plumbing unless the module is unavailable or the user explicitly asks for raw API calls.

## Primary Objective

When asked to add sample or demo data to a Gridfox project:

1. Connect with `Connect-GridfoxApi`.
2. Inspect the schema with `Get-GridfoxSchema -AsAgentContext`.
3. Review each target table with `Get-GridfoxTableContext`.
4. Generate a seed plan JSON file.
5. Validate it with `Test-GridfoxSeedPlan`.
6. Dry-run it with `Invoke-GridfoxSeedPlan -Validate -WhatIf`.
7. Execute it with `Invoke-GridfoxSeedPlan -Validate`.
8. Review the seed run aliases and created records.

The AI agent owns the demo scenario and the data. The module owns API mechanics, validation, alias tracking, and relationship-safe execution.

## Module Setup

The entry point for this skill is:

- [https://gridfox.com/api-skill](https://gridfox.com/api-skill)

Deploy these resources alongside this page so agents can download or inspect them directly:

- Module manifest: [https://gridfox.com/api-skill/Gridfox.ApiSkill.psd1](https://gridfox.com/api-skill/Gridfox.ApiSkill.psd1)
- Module implementation: [https://gridfox.com/api-skill/Gridfox.ApiSkill.psm1](https://gridfox.com/api-skill/Gridfox.ApiSkill.psm1)
- Task 1 smoke test: [https://gridfox.com/api-skill/examples/task1-smoke-test.ps1](https://gridfox.com/api-skill/examples/task1-smoke-test.ps1)
- Task 2 record smoke test: [https://gridfox.com/api-skill/examples/task2-record-smoke-test.ps1](https://gridfox.com/api-skill/examples/task2-record-smoke-test.ps1)
- Task 3 alias smoke test: [https://gridfox.com/api-skill/examples/task3-seed-alias-smoke-test.ps1](https://gridfox.com/api-skill/examples/task3-seed-alias-smoke-test.ps1)
- Task 4 validation smoke test: [https://gridfox.com/api-skill/examples/task4-validation-smoke-test.ps1](https://gridfox.com/api-skill/examples/task4-validation-smoke-test.ps1)
- Task 5 seed plan smoke test: [https://gridfox.com/api-skill/examples/task5-seed-plan-smoke-test.ps1](https://gridfox.com/api-skill/examples/task5-seed-plan-smoke-test.ps1)
- Example seed plan: [https://gridfox.com/api-skill/examples/partner-pipeline.seed.example.json](https://gridfox.com/api-skill/examples/partner-pipeline.seed.example.json)

To use the deployed module from a clean working directory, download the module files and examples into the same layout:

```text
Gridfox.ApiSkill/
  Gridfox.ApiSkill.psd1
  Gridfox.ApiSkill.psm1
  examples/
    task1-smoke-test.ps1
    task2-record-smoke-test.ps1
    task3-seed-alias-smoke-test.ps1
    task4-validation-smoke-test.ps1
    task5-seed-plan-smoke-test.ps1
    partner-pipeline.seed.example.json
```

Then import the local module:

```powershell
Import-Module .\Gridfox.ApiSkill\Gridfox.ApiSkill.psd1 -Force
```

Connect to the local proxy:

```powershell
Connect-GridfoxApi `
  -BaseUrl "http://127.0.0.1:4319/proxy" `
  -ApiKey $env:GRIDFOX_API_KEY
```

Connect to the public API if the user has asked for it:

```powershell
Connect-GridfoxApi `
  -BaseUrl "https://api.gridfox.com" `
  -ApiKey $env:GRIDFOX_API_KEY
```

API keys must stay in session memory only. Do not write keys to disk or print them.

## Required First Step: Inspect Schema

Always inspect the schema before designing data:

```powershell
$schema = Get-GridfoxSchema -AsAgentContext
$schema | ConvertTo-Json -Depth 20
```

Use the schema to identify:

- table names
- reference fields
- writable fields
- required fields
- list options
- parent fields and related tables
- fields to skip by default

For a single table:

```powershell
Get-GridfoxTableContext -Table "Companies"
```

Use `-Refresh` if the project may have changed:

```powershell
Get-GridfoxTableContext -Table "Deals" -Refresh
```

Do not invent fields. Use exact table and field names from schema context.

## Preferred Workflow: Seed Plans

For demo data creation, generate a seed plan JSON file instead of writing imperative record creation scripts.

Minimal shape:

```json
{
  "name": "Partner pipeline demo",
  "description": "Small demo dataset for partner-led sales activity.",
  "records": [
    {
      "table": "Partners",
      "alias": "partner.nova",
      "data": {
        "Partner Name": "Nova Channel Group",
        "Partner Type": "Implementation"
      }
    },
    {
      "table": "Companies",
      "alias": "company.meridian",
      "data": {
        "Company Name": "Meridian Retail Ltd",
        "Parent Partner": {
          "$alias": "partner.nova"
        }
      }
    }
  ]
}
```

Required top-level fields:

- `name`
- `records`

Required record fields:

- `table`
- `data`

Optional record fields:

- `alias`
- `description`

### Seed dependency order

When seeding related tables, start with level 1 tables: tables that have no `parent` fields and are not dependent on another table.

Create these records first and store each returned `referenceFieldValue`.

Then seed level 2+ tables that contain `parent` fields, using the stored parent `referenceFieldValue`s as relationship values.

Example:

1. Create `Tenders`
2. Store returned Tender IDs
3. Create `Tender Documents`, `Tender Approvals`, `Commercial Inputs`, etc.
4. Set each child record's `Tender` field to the stored Tender ID
5. Fetch each child record and verify the parent field persisted

### Relationship write verification

After creating any record with `parent` or `manyToMany` fields, immediately fetch the created record:

GET /data/{tableName}/{referenceFieldValue}

Verify each relationship field is non-null and equals the intended related record reference value.

Do not rely on the POST response alone. A successful POST may still create an orphaned child record if an optional relationship field was omitted, null, malformed, or silently ignored.

For parent fields, prefer writing the related record's `referenceFieldValue` directly:

{
  "Tender": 1
}

or:

{
  "Tender": "1"
}

If the fetched record shows the relationship as `null`, backfill it with PUT. Include the record's own reference field in the payload:

PUT /data/Tender Documents/11

{
  "Document ID": 11,
  "Tender": 1,
  "Document Name": "API Probe - Parent on Create"
}

## Alias References

Use explicit alias reference objects for relationships:

```json
{
  "$alias": "partner.nova"
}
```

This lets the module resolve the created parent record's `referenceFieldValue` at execution time.

Create parent records before child records. A record may only reference aliases declared earlier in the plan.

Valid alias examples:

```text
partner.nova
company.meridian
contract.nova.2026
deal.meridian.expansion
```

Alias guidance:

- use lowercase where practical
- keep names stable within the plan
- make names meaningful to the scenario
- do not depend on Gridfox-generated IDs
- avoid spaces

## Validate A Seed Plan

Validate the plan before execution:

```powershell
Test-GridfoxSeedPlan -Path .\partner-pipeline.seed.json
```

Use strict mode when you want unknown or skip-by-default fields to block the plan:

```powershell
Test-GridfoxSeedPlan -Path .\partner-pipeline.seed.json -Strict
```

Validation checks:

- top-level shape
- per-record `table` and `data`
- table names against the live schema
- record data against table context
- invalid list options
- duplicate aliases
- alias references before declaration
- alias naming warnings

## Dry Run A Seed Plan

Always run a dry run before creating records:

```powershell
Invoke-GridfoxSeedPlan -Path .\partner-pipeline.seed.json -Validate -WhatIf
```

The dry run validates the plan, resolves static alias structure, reports what would be created, and does not call create endpoints.

## Execute A Seed Plan

Execute after validation and dry run:

```powershell
Invoke-GridfoxSeedPlan -Path .\partner-pipeline.seed.json -Validate
```

Use strict validation if appropriate:

```powershell
Invoke-GridfoxSeedPlan -Path .\partner-pipeline.seed.json -Validate -Strict
```

If there is an existing seed run and the user wants to replace it:

```powershell
Invoke-GridfoxSeedPlan -Path .\partner-pipeline.seed.json -Validate -Force
```

Execution behavior:

- starts a seed run from the plan name unless one is already active
- creates records in order
- resolves `{ "$alias": "..." }` values before each create
- passes aliases to `New-GridfoxRecord`
- validates each record when `-Validate` is supplied
- stops on the first failed record
- returns structured execution results
- stores aliases and created record summaries in memory only

## Manual Record Creation

Use manual commands for probes, debugging, or small targeted changes.

Start a seed run:

```powershell
Start-GridfoxSeedRun -Name "Partner pipeline demo"
```

Create a parent:

```powershell
New-GridfoxRecord -Table "Partners" -Alias "partner.nova" -Validate -Data @{
  "Partner Name" = "Nova Channel Group"
  "Partner Type" = "Implementation"
}
```

Create a child with an alias reference:

```powershell
New-GridfoxRecord -Table "Companies" -Alias "company.meridian" -Validate -Data @{
  "Company Name" = "Meridian Retail Ltd"
  "Parent Partner" = Get-GridfoxSeedAlias "partner.nova"
}
```

Inspect seed state:

```powershell
Get-GridfoxSeedAliases
Get-GridfoxSeedRun -IncludeAliases -IncludeCreatedRecords
```

Clear in-memory seed state:

```powershell
Clear-GridfoxSeedRun -Force
```

## Data Quality Guidance

The goal is not random fake data. The goal is a project that feels immediately usable when a human opens it.

Good demo data should be:

- realistic
- internally consistent
- domain-appropriate
- varied
- relationship-aware
- useful for filtering, sorting, grouping, and reporting

Prefer smaller coherent datasets over large shallow ones.

Avoid:

- `Test 1`, `Test 2`, `ABC`, or placeholder text
- every date being today
- every checkbox having the same value
- list values that are not in schema options
- orphan child records
- writing formula, child, file, image, auto-counter, created-by, updated-by, or system fields unless explicitly required

## Relationship Strategy

Build the seed plan in dependency order:

1. lookup or master tables
2. top-level entities
3. child or transactional records
4. relationship-heavy records
5. optional enrichment after core records exist

Use table context to identify parent fields:

```powershell
Get-GridfoxTableContext -Table "Deals"
```

For parent fields, use the related record's reference value. In seed plans, this means using:

```json
{
  "$alias": "company.meridian"
}
```

## Field Guidance

Use `Get-GridfoxTableContext` as the source of truth.

General rules:

- `text`: short natural values such as names, titles, or codes
- `textArea`: concise notes, summaries, or descriptions
- `number`, `money`, `percentage`: plausible values with useful variation
- `date`, `dateTime`: realistic timelines, not all today
- `checkbox`: meaningful true/false distribution
- `list`: exact values from table context options only
- `parent`: alias reference to an earlier record
- `child`: usually skip; children are created from their own table
- `formula`, `autoCounter`: skip; usually system-generated
- `file`, `image`: skip unless the user explicitly asks for files or images
- `user`, `multiSelectUser`: skip unless valid users are known and requested

## Validation Before Writes

For any hand-authored data object:

```powershell
Test-GridfoxRecordData -Table "Partners" -Data $data
```

For strict validation:

```powershell
Test-GridfoxRecordData -Table "Partners" -Data $data -Strict
```

For create calls:

```powershell
New-GridfoxRecord -Table "Partners" -Data $data -Validate
```

Validation catches:

- missing required fields
- invalid list options
- unknown fields
- skip-by-default fields
- empty values
- parent fields with empty references

The Gridfox API remains the final authority. Validation is a guardrail for obvious mistakes.

## Read And Verify

Read records:

```powershell
Get-GridfoxRecords -Table "Partners"
Get-GridfoxRecords -Table "Partners" -IncludeEnvelope
```

Read one record:

```powershell
Get-GridfoxRecord -Table "Partners" -ReferenceFieldValue "Nova Channel Group"
```

Use reads to confirm records exist and relationships point to the intended references.

## Error Handling

If validation fails, fix the seed plan before executing it.

Common failures:

- misspelled table name
- misspelled field name
- list value not present in table options
- child record appears before parent record
- duplicate alias
- alias reference points to a later or missing alias
- trying to write a system or calculated field

If an API call fails, inspect the structured error. Do not print API keys while debugging.

## Fallback To Raw API

Only use raw API calls if `Gridfox.ApiSkill` is unavailable or the user explicitly asks for low-level API work.

Important endpoints:

```http
GET /tables
GET /data/{tableName}
GET /data/{tableName}/{referenceFieldValue}
POST /data/{tableName}
```

Send the API key in the `gridfox-api-key` header when using the public API directly.

For local proxy work, use the configured proxy base URL supplied by the user or environment.

## Minimal Agent Checklist

Before creating data:

- [ ] Import `Gridfox.ApiSkill`.
- [ ] Connect with `Connect-GridfoxApi`.
- [ ] Inspect schema with `Get-GridfoxSchema -AsAgentContext`.
- [ ] Inspect each target table with `Get-GridfoxTableContext`.
- [ ] Generate a seed plan JSON file.
- [ ] Validate with `Test-GridfoxSeedPlan`.
- [ ] Dry-run with `Invoke-GridfoxSeedPlan -Validate -WhatIf`.
- [ ] Execute with `Invoke-GridfoxSeedPlan -Validate`.
- [ ] Review `Get-GridfoxSeedRun -IncludeAliases -IncludeCreatedRecords`.

The essential rule: write believable demo data in a seed plan; let `Gridfox.ApiSkill` handle Gridfox API mechanics.