# get-entity-status

Free; owner-only read. The full state of a managed entity in one artifact — works in **every** lifecycle state, including terminal `dissolved` and `released` (read access never dies).

## Input

| Field | Required | Notes |
|---|---|---|
| `entity` | one of | Handle, e.g. `"US-WY:daski-labs-llc"`. |
| `assetId` | one of | Immutable UUID from the formation artifact. Use it to disambiguate when a legal name was re-formed after a dissolution (the handle then points at the new entity). |

## Result artifact — `entity_status`

```jsonc
{
  "assetId": "5f0c2f6a-…",
  "entity": "US-WY:daski-labs-llc",
  "status": "active",                    // active | suspended | expired | ra_cancelled | released | dissolved
  "raRenewalDue": true,                  // computed: paid-through inside the renewal window (60 days)
  "legalName": "Daski Labs LLC",
  "country": "US",
  "state": "WY",
  "entityType": "Limited Liability Company",
  "classification": "LLC",
  "formationDate": "2026-07-04",
  "raPaidThrough": "2026-08-20",
  "einPresent": true,
  "publicationObligation": false,
  "openFilingTasks": [
    { "taskId": "…", "skill": "file-compliance", "stage": "awaiting state processing" }
  ],
  "documentCount": 4,
  "upcomingComplianceEvents": [
    { "filing": "Annual Report", "dueDate": "2027-07-01", "status": "active" }
  ],
  "attentionItems": [
    { "kind": "compliance_due", "filing": "Annual Report", "dueDate": "2027-07-01", "skillToPurchase": "file-compliance" },
    { "kind": "ra_renewal_window", "raPaidThrough": "2026-08-20", "skillToPurchase": "renew-registered-agent" }
  ],
  "clientObligations": [ /* federal + state disclosures */ ],
  "notSupported": [ /* exclusions */ ]
}
```

## Reading the response

- `raRenewalDue: true` — the RA paid-through is inside the renewal window (default 60 days) and the entity is `active` or `expired`: buy `renew-registered-agent`.
- `openFilingTasks[].stage` is coarse by design: `validating`, `preparing filing`, `submitting to the state`, `awaiting state processing`, `needs your input`, `finalizing`.
- `attentionItems[]` name the exact skill to purchase in `skillToPurchase` — they are the machine-readable to-do list.
- `documentCount` says how much paper is waiting; enumerate it with `list-entity-documents`.

## While under review

A `suspended` entity answers with a reduced artifact and nothing else — no mechanics, no reasons:

```jsonc
{
  "assetId": "5f0c2f6a-…",
  "entity": "US-WY:daski-labs-llc",
  "status": "suspended",
  "message": "This entity is under review. No action is needed."
}
```

## Failure modes

- Unknown `entity` / `assetId`, or an entity not owned by the calling agent: `not_found` with a message. No detail leaks about other tenants' assets.

## Next step

- `list-entity-documents` / `download-entity-document` for the records.
- Whatever `attentionItems[].skillToPurchase` names, when present.

## Address and mail benefits

Owner-authorized `get-entity-status` returns the actual `registeredAgent`,
`businessAddress` and `ordinaryMail` details. Availability is `active`, `inactive`
or `unknown`, with an observation time. An old address is historical evidence,
not permission to keep using it after cancellation. Filing profiles preserve
what was submitted even when the supplier office later changes.

Ordinary mail includes five pieces per supplier service year, excluding
state/legal mail. Activation is reported independently as `pending`, `active`,
`inactive` or `unknown`. Unavailable term dates and used/remaining allowance are omitted until
supplier evidence verifies them. `usageStatus` is `unknown`, `verified`, or
`stale`; verified zero usage is returned as zero. `observedOrdinaryPieces` counts deduplicated
local scans across local history; it is not remaining supplier allowance.
Use the returned support email and entity/document reference for activation,
extra mail, locked scans or originals. A support request does not authorize a
supplier charge. Original-request deadlines are omitted until the applicable
account terms and time basis are confirmed. Unavailable addresses, observation
times, RA paid-through dates, and filing-profile IDs are also omitted; use the
explicit availability state to distinguish unknown evidence from an active service.