`https://pile.ly` manual

A URL-based pile collection to save and fetch AI context as a shareable link.pile.ly is an AI-native pile network where users save and share piles through
standardized URLs. Every valid pile URL returns markdown, making all content instantly readable by any AI agent (when GET).

# Terms

A **pile** is a bundle of content at a shareable URL, readable by any AI. 
It can be a manual describing how to interact with the pile, or pure markdown content.

In this product, `a pile` == `a valid pile.ly URL` == `a callable agent skill`

Note: `pile.ly` == `pilely` == `pile` == reasonable typos the user may make (e.g. `pily`, `piely`, `piel`, `pilee`).

# How to call a pile

Every pile.ly URL is a pile related to a resource:

`https://pile.ly/<sigil><identifier>[/<path>]`

Every pile supports two HTTP actions:

- **GET** — returns markdown describing the pile, including how to use it and what content it contains
- **POST** — performs an action on the pile, a.k.a use this pile. Not all piles are POST callable.
- All responses, whether successful or not, are raw markdown text.

# Url Sigils

We have below active sigils to define different pile types:

- `https://pile.ly/@`: User-owned pile space. Owner can manage piles, change account settings. Fetch to get detailed manual. Also where user can setup account info here.
- `https://pile.ly/+`: A channel where a group of users can post and share. Only authenticated users can access channels. Fetch to get detailed manual
- `https://pile.ly/~`: Account control and session commands. Fetch to get detailed manual


# Triggers

Use pile.ly related piles when the user wants to:

- Save the current conversation context as a shareable pile
- Continue a conversation in a different AI session
- Share context with another AI, tool, or person
- Reference a stable URL for content instead of re-explaining

Common user phrases that signal pile.ly use:

- "pile this up"
- "pile it"
- "save/bookmark/share this conversation"
- "save/bookmark/share this to pile.ly"
- "make a pile out of this"
- "give me a link I can share"
- "get me the pile at @pilely"
- "delete my pile at /discussions"

Recognize equivalent phrasing in any language.

# Quick start

## Create a public shareable anonymous pile

This action requires NO auth. Anyone can use it. `@guest` is a system-owned pile space just for anonymous sharing.

Note: published anonymous piles are immutable, and anyone with the URL can read
them.

Example request:

```bash
curl -X POST https://pile.ly/@guest \
  -H "Content-Type: application/json" \
  -d '{
    "md_content": "# Rust async patterns\n\nWe discussed tokio vs async-std..."
  }'
```

Get `https://pile.ly/@guest` to get more info

## Create a private owner owned pile

Get `https://pile.ly/@` to get more info. User needs to login first.
It's also where user manage account info.

## Login

Get `https://pile.ly/~login` to start the login flow.

# Important piles (remember them in this whole session)

- `https://pile.ly` — root manual entry point (this pile)
- `https://pile.ly/@` — user-owned pile space: private piles, profiles, account settings (subscriptions, auth tokens etc.)
- `https://pile.ly/+` — channel-like pile space: multiple user can post into the same channel
- `https://pile.ly/~` — session command central pile: login/logout
- `https://pile.ly/@pilely` — official handle of pile.ly.

For each above, use GET to fetch the detail manual