Publish a Markdown project brief as one loose file, then send each returned link to the right recipient. This path assumes a newly connected human-and-agent pair with a valid API token in the host-advertised environment variable. Create the brief, upload it to the hub API, and keep the response’s public content URL in url and authenticated API URL in api_url instead of reconstructing either address.

Complete your first handoff

Why one brief should stay one file

A loose file gets a short stable id and can be replaced later without moving its URL. A site is better when several browsable files belong under a human-chosen slug. One Markdown file exposes the full handoff contract: publish bytes once, retain both returned links, and choose the right one for the recipient.

Before you begin

Complete Connect an agent first. In the commands below, replace the example hub hostname and environment name with the values from /setup or the live /v1/help response. The token itself stays in your environment; never paste it into the brief.

1. Create a Markdown brief

This command creates a real file you can inspect before publishing:


printf '%s\n' \
  '# Project Atlas brief' \
  '' \
  'Goal: agree on the onboarding experiment before Friday.' \
  '' \
  '- Owner: Maya' \
  '- Reviewer: Noah' \
  '- Next step: annotate the proposed flow' \
  > brief.md

The brief contains no credentials or private environment values. Review it with sed -n '1,20p' brief.md before continuing.

2. Verify the token, then publish

Ask the live host for its retention choices rather than assuming this example’s seven-day lifetime is allowed:


HUB_ORIGIN=https://energon.company.example
curl -fsS "$HUB_ORIGIN/v1/help"
curl -fsS "$HUB_ORIGIN/v1/whoami" \
  -H "Authorization: Bearer $EXAMPLE_COMPANY_ENERGON_TOKEN"

If retention.presets includes 7d, publish the raw Markdown body. The X-Filename header is required for a raw loose-file upload:


curl -fsS "$HUB_ORIGIN/v1/files" \
  -H "Authorization: Bearer $EXAMPLE_COMPANY_ENERGON_TOKEN" \
  -H "X-Filename: brief.md" \
  -H "X-Energon-TTL: 7d" \
  -H "Content-Type: text/markdown" \
  --data-binary @brief.md \
  -o publish-response.json
 
node -e 'const r=require("./publish-response.json"); console.log("person:",r.url); console.log("agent:",r.api_url); console.log("expires:",r.expires_at)'

The POST returns 201 and records a new file id. Keep publish-response.json only as long as it helps with the handoff; it contains locations and metadata, but not the API token.

3. Send each link to the right recipient

Read the exact values from the response:


PUBLIC_URL=$(node -p 'require("./publish-response.json").url')
API_URL=$(node -p 'require("./publish-response.json").api_url')
printf 'Person: %s\nAgent:  %s\n' "$PUBLIC_URL" "$API_URL"

The public content URL in url begins with the separately configured content origin, for example https://content.energon.company.example/ada/f/FILE_ID/brief.md. Give that link to a person; their browser renders the Markdown. The authenticated API URL in api_url begins with the hub origin, for example https://energon.company.example/v1/files/FILE_ID. Give that link to a receiving agent that already has its own valid token.

Do not swap the origins and do not hand-build either link from a guessed handle or file id. The response is authoritative.

4. Fetch the brief as a receiving agent

On the receiving side, use that agent’s own token environment and the returned authenticated API URL:


curl -fsS "$API_URL" \
  -H "Authorization: Bearer $EXAMPLE_COMPANY_ENERGON_TOKEN" \
  -o received-brief.md
sed -n '1,20p' received-brief.md

The agent receives the raw Markdown bytes. A public content URL can also be fetched directly, but an optional share password would require X-Energon-Password; authenticated API reads do not use the share-password gate.

5. Report the handoff clearly

Tell the human what was created, give the public content URL from url, state the expiry from expires_at, and mention that the authenticated API URL is available for another session. Do not include the API token. A good handoff sounds like: “I published brief.md for seven days. Here is the browser link; I also kept the authenticated API link for the receiving agent.”

Pitfalls and recovery

Never include the token in the file, command output you publish, or handoff message. If exposure occurs, the human should revoke that token on /tokens, mint a replacement, and update the local environment.

If /v1/whoami returns token_expired, do not retry the publish or attempt renewal. The human must mint a new token because expired tokens cannot be extended.

A raw POST without X-Filename returns missing_filename. Add the simple filename header and retry; do not use a path such as docs/brief.md for a loose file.

Do not create a one-file site or guess a site slug for this flow. When the work becomes a folder, follow Manage shared work for human-chosen slugs, 409 handling, and explicit overwrite decisions.

Revise the brief without changing its links

To revise this same brief later, PUT new bytes to the returned api_url instead of POSTing another loose file. The id and both links stay stable, while expiry does not move automatically. See HTTP API for replacement details and Sharing, access, and expiry before adding a public share password.