Hospitable Ops

Operate and automate Hospitable properties, reservations, and calendars with safe read-first API workflow, focusing on non-price calendar controls and write...

Security Scan

The skill's code and SKILL.md expect a HOSPITABLE_TOKEN and reference loading a user-specific .env file, but the registry metadata omits required credentials and the instructions suggest reading a host filesystem path — this mismatch and the filesystem guidance are concerning even though the included scripts look functionally aligned with the stated purpose.

Purpose & Capability

The skill claims to operate Hospitable via its Public API, which legitimately requires an API token. However, the registry metadata lists no required environment variables or primary credential, while both JS scripts and SKILL.md require HOSPITABLE_TOKEN (and optionally HOSPITABLE_BASE_URL). The omission in the declared requirements is an incoherence that could mislead users or automated reviewers.

Instruction Scope

SKILL.md is generally scoped to reading properties/reservations/calendars and cautious write probes, which matches the scripts. However it explicitly instructs loading a local env file at an absolute path (/Users/admin-ai/.openclaw/workspace-qiang/.env.local). Directing the agent to read a specific host filesystem path for secrets is risky and workspace-specific; the scripts themselves only read process.env (they do not implement file loading), creating a mismatch between instructions and code.

Install Mechanism

No install spec and only two small Node scripts are included. There are no downloads, no external install steps, and no obscure third-party packages — low installation risk.

Credentials

The runtime requires HOSPITABLE_TOKEN (and optionally HOSPITABLE_BASE_URL) but the package metadata declares no required env vars. SKILL.md's direction to load a local .env file suggests the token may be stored in a host file; requesting that file without declaring the credential is disproportionate and could lead to accidental exposure of secrets. The number of env items is small and reasonable for the task, but the non-declaration and file path guidance are problematic.

Persistence & Privilege

always is false and the skill does not request persistent system-wide privileges or attempt to modify other skills or agent configuration. The scripts only perform HTTPS calls to the Hospitable API and print responses.

What to consider before installing

Before installing, note these issues and take precautions: - The code and instructions require HOSPITABLE_TOKEN, but the skill metadata does not declare it. Expect to provide that token manually; do not assume the platform will supply it safely. - SKILL.md tells you to load a specific host file (/Users/admin-ai/…/.env.local). That is workspace- and user-specific and could expose other local secrets; avoid automatically loading arbitrary host files. Prefer using the platform's secret store or setting a token scoped to read-only access for testing. - The included scripts look benign: they perform HTTPS requests to Hospitable and do not print tokens. Still review any edits carefully — the write-probe script accepts method/path/body arguments and can perform writes if invoked with PUT and a body. Require explicit human confirmation for any write operations and consider using a token with limited permissions for automation. - Ask the skill author or registry maintainer to update metadata to declare HOSPITABLE_TOKEN (and any other required env vars) so reviewers and automated systems know what secrets are needed. - If you will run this in automation, explicitly audit who/what can invoke write actions and consider running first with a read-only token to validate behavior. If you want higher assurance, request that the author remove the absolute filesystem path from instructions, document exactly how tokens should be provided, and mark write operations as human-only or protected by explicit consent steps.

Use Hospitable as the unified operational base. Prefer read-first, then safe write verification, then controlled non-price writes.

Core rules

• Treat Hospitable as the system of operational judgment, especially for unified property UUIDs, calendar state, reservations, and parent/child exclusion logic.
• Never expose tokens in chat, logs, screenshots, or shared files.
• Use Hospitable Public API v2 as the only active execution path for reads and automation in this workspace.
• MCP has been removed from the current Hospitable operating path; do not route or describe Hospitable work through MCP.
• Use persistent config or local scripts; avoid session-only ad hoc setup when building repeatable workflows.
• Default to non-price actions only. Price, currency, and money-related changes must be discussed first and then changed manually by the human.
• Assume write effects may be asynchronous. Do not judge failure from an immediate readback alone.
• In this workspace, do not rely on OpenClaw runtime inheriting shell env automatically; prefer script-level loading from /Users/admin-ai/.openclaw/workspace-qiang/.env.local for repeatable Hospitable execution.
• HOSPITABLE_TOKEN must contain the token body only; never include a leading Bearer prefix in the env value.

Standard workflow

1. Verify HOSPITABLE_TOKEN is available in the current execution environment without printing it.
2. If runtime inheritance is uncertain, use local script loading from .env.local instead of re-debugging shell/profile inheritance.
3. Read data first:
   • properties
   • reservations
   • calendar
4. Save JSON with statusCode and body envelope.
5. Build operational judgments from Hospitable first; layer Booking/Airbnb exceptions after.
6. For writes, probe safely:
   • identify method
   • identify minimal body
   • test on low-risk future date
   • re-read after delay
7. Only after semantics are clear, apply controlled non-price changes.

Known API behavior

Read

Use bearer auth plus Accept: application/json.

Current workspace rule:

• default to the current validated token
• treat older/previous Hospitable tokens as deprecated unless the human explicitly restores one
• prefer local env file loading over shell-history fallback or session-only manual export

Common read paths:

• properties
• reservations?properties[]=<uuid>
• properties/<uuid>/calendar?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD

Runtime inheritance readback (validated)

Validated facts in this workspace:

• host-side token is valid and can return statusCode: 200 on properties
• OpenClaw agent runtime did not automatically inherit HOSPITABLE_TOKEN
• repeatable workaround: load /Users/admin-ai/.openclaw/workspace-qiang/.env.local directly inside Hospitable scripts
• after enabling script-level env loading, node scripts/hospitable-read.js properties --per-page 1 returned statusCode: 200

Current script CLI contract

/Users/admin-ai/.openclaw/workspace-qiang/scripts/hospitable-read.js

Supported commands:

• properties [--per-page N]
• reservations --property <uuid> [--per-page N]
• calendar --property <uuid> --start YYYY-MM-DD --end YYYY-MM-DD

Important:

• calendar uses --start and --end
• do not use --start-date / --end-date with this script
• keep #!/usr/bin/env node on line 1 if editing the script header

Write

For calendar writes:

• route: properties/<uuid>/calendar
• supported method: PUT
• PATCH is not supported
• request body must include dates
• minimal accepted structure:

{
  "dates": [
    { "date": "YYYY-MM-DD" }
  ]
}

Verified non-price semantics

Block a whole date

{
  "dates": [
    { "date": "YYYY-MM-DD", "available": false }
  ]
}

Expected eventual readback:

• status.reason = BLOCKED
• status.source = api
• status.source_type = VENDOR
• status.available = false

Restrict check-in / check-out

{
  "dates": [
    {
      "date": "YYYY-MM-DD",
      "closed_for_checkin": true,
      "closed_for_checkout": true
    }
  ]
}

Expected eventual readback:

• closed_for_checkin = true
• closed_for_checkout = true
• day may still remain AVAILABLE

Operational boundaries

Allowed direct actions

• non-price calendar block/unblock
• check-in/check-out restrictions
• non-price operational lock windows
• parent/child exclusion enforcement
• cross-channel conflict prevention using non-price controls
• one-time cleanup of legacy order occupancy when the business rule is already confirmed

Human-only actions

• price
• currency
• money-related changes
• pricing strategy decisions

Long-term operating model

Reduce the property system into three stable forms whenever possible:

1. Airbnb-only
2. dual-channel managed by Hospitable native mechanisms
3. main-house gate open/closed

Treat legacy exceptions as temporary cleanup layers, not permanent structure.

Current NXM cleanup model

• mute(booking) is a historical order source only and should not take new sales.
• 206 -> 201 is a temporary operational occupancy transfer caused by legacy mute orders.
• customer-visible order display can remain original while operational occupancy moves internally for anti-overbooking control.
• after cleanup, return to the three stable forms above.

Recommended local files

• scripts/hospitable-read.js
• scripts/hospitable-write-probe.js
• exported JSON snapshots with statusCode/body
• rule config files for object tiers and lock windows

Delay-aware verification

After a write returns 202 accepted:

1. wait before declaring failure
2. re-read the same date window
3. compare operational fields, not only high-level availability
4. check whether the change is semantic (blocked vs closed_for_checkin/checkout)

Good output pattern

Report in this order:

1. current status
2. exact object/date tested
3. request accepted or rejected
4. delayed readback result
5. operational conclusion
6. single biggest remaining gap