# Getting started with the Shadstone Handbook

Use this public guide before signing in. The Handbook itself is private, and
what you can read depends on your approved GFAVIP identity and handbook roles.

## Choose your path

- **I am a person:** follow **For humans** below.
- **I am an AI agent:** follow **For agents** below. Do not use the browser
  sign-in intended for people.
- **We are working together:** the person can send the copy-and-paste prompt
  near the end of this guide to their agent.

## For humans

1. Open [https://handbook.shadstone.com](https://handbook.shadstone.com) and choose **Continue with GFAVIP**.
2. Sign in to GFAVIP Wallet with your normal account.
3. On a first visit, your identity may be known but not approved for the
   Handbook yet. Send your exact GFAVIP username to a Handbook administrator
   and ask for the roles you need. Do not create another account.
4. After approval, sign in again. Use **Search** when you know what you need,
   **Browse** for a department or tool, and **Explore** to see how documents
   connect.
5. Once signed in, open [https://handbook.shadstone.com/humans](https://handbook.shadstone.com/humans) for the full guide to
   reading, finding, and maintaining Handbook material.

If you are asking an agent to use the Handbook, do not share your password,
browser cookie, or token. The agent should use its own PowerLobster identity.

## For agents

The Handbook does not issue a separate API key, and its human browser login is
not an agent authentication method.

1. Read [https://wallet.gfavip.com/skill.md](https://wallet.gfavip.com/skill.md) and follow its PowerLobster
   headless SSO flow using your existing agent identity.
2. Obtain a GFAVIP session token. Never print, log, paste into chat, put into a
   URL, or save that token in Handbook content.
3. Send the token to the Handbook identity check:

   ```http
   GET https://handbook.shadstone.com/api/me
   Authorization: Bearer <gfavip-session-token>
   Accept: application/json
   ```

4. If the identity is not approved, tell your human collaborator the exact
   GFAVIP username you authenticated as. A Handbook administrator must approve
   that identity and assign its roles. Do not create a replacement identity.
5. After approval, retry `/api/me`, then read [https://handbook.shadstone.com/skill.md](https://handbook.shadstone.com/skill.md)
   before searching, reading, or editing.

Always search before listing the entire collection. A missing document may be
invisible to your identity; do not create a duplicate to work around a `404`.

## Human and agent together

Send this prompt to the agent:

> Read https://handbook.shadstone.com/skill_gettingstarted.md and follow the **For agents** path. Use
> your own PowerLobster identity, not my browser login. Check `/api/me`, then
> tell me the exact GFAVIP username you used and whether the Handbook says you
> are approved. Never show me or log any token.

Once the agent is approved, continue with:

> Read https://handbook.shadstone.com/skill.md. Search the Handbook for what I asked about before
> deciding it is missing. Respect the access returned for your own identity.

## If something goes wrong

| What you see | What it usually means | What to do |
| --- | --- | --- |
| Human sign-in returns to the login page | The GFAVIP sign-in did not complete or the browser session was lost | Try once more, then send the displayed error and your username to an administrator |
| `401 Unauthorized` from the API | The token is missing, invalid, expired, or the identity has no Handbook role | Refresh the GFAVIP session; if it persists, report the exact agent username for approval |
| `403 Editor role required` | The identity may read but may not edit | Ask an administrator only if editing is part of the assigned job |
| `403 Agent writes are disabled` | This deployment permits agent reads but not writes | Give the proposed change to a human editor |
| `404 Not found` | The address is wrong, or the document is not visible to this identity | Search first, then ask a human; do not infer that private content exists |
| `412 Precondition Failed` while editing | The document changed after it was read | Read it again and reconcile the changes; never overwrite blindly |

## Privacy boundary

This public guide intentionally contains no procedure names, private paths,
staff lists, credentials, access assignments, or internal operating details.
Authentication proves who you are; it does not guarantee access to every
Handbook document.