adobe/handover-author

Project Handover - Authoring

Generate a complete authoring guide for content authors and content managers. Analyzes the project and produces actionable documentation.

---

Step 0: Navigate to Project Root (CONDITIONAL)

Skip if allGuides is set in .claude-plugin/project-config.json (orchestrator already validated).

ALL_GUIDES=$(cat .claude-plugin/project-config.json 2>/dev/null | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  try { console.log(JSON.parse(d).allGuides ? 'true' : ''); } catch(e) { console.log(''); }
")
if [ -z "$ALL_GUIDES" ]; then
  cd "$(git rev-parse --show-toplevel)"
  ls scripts/aem.js
fi

If scripts/aem.js does not exist, tell the user this skill requires an AEM Edge Delivery Services project and stop.

All subsequent steps operate from project root. Guides are created at project-guides/.

---

Execution Checklist

- [ ] Phase 0: Get org name and authenticate
- [ ] Phase 1: Gather project information from Config Service API
- [ ] Phase 2: Analyze content structure
- [ ] Phase 3: Document blocks and templates
- [ ] Phase 4: Document configuration sheets
- [ ] Phase 5: Generate PDF

---

Phase 0: Get Organization Name and Authenticate

0.1 Check for Saved Organization

cat .claude-plugin/project-config.json 2>/dev/null | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  try { const o = JSON.parse(d).org; if(o) console.log('org: ' + o); } catch(e) {}
"

0.2 Prompt for Organization Name (If Not Saved)

If no org name is found, ask the user:

"What is your Config Service organization name? This is the {org} part of your Edge Delivery Services URLs (e.g., https://main--site--{org}.aem.page). The org name may differ from your GitHub organization."

Ask as a plain text question — not AskUserQuestion with options. Organization name is mandatory.

0.3 Save Organization Name

mkdir -p .claude-plugin
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore

if [ -f .claude-plugin/project-config.json ]; then
  cat .claude-plugin/project-config.json | sed 's/"org"[[:space:]]*:[[:space:]]*"[^"]*"/"org": "{ORG_NAME}"/' > /tmp/project-config.json && mv /tmp/project-config.json .claude-plugin/project-config.json
else
  echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json
fi

Replace {ORG_NAME} with the actual organization name.

0.4 Check Auth Token

AUTH_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    if (t.authToken && t.authTokenExpiry > Math.floor(Date.now()/1000) + 60) {
      process.stdout.write(t.authToken);
    }
  } catch (e) {}
")

if [ -z "$AUTH_TOKEN" ]; then
  echo "AUTH_REQUIRED"
fi

If AUTH_REQUIRED, invoke the auth skill before proceeding:

Skill({ skill: "aem-project-management:auth" })

---

Phase 1: Gather Project Information

1.1 Fetch Sites via Config Service API

The Config Service API is the only reliable source for site information. Do not use fstab.yaml, README, or git remote URLs.

ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")
AUTH_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    process.stdout.write(t.authToken || '');
  } catch (e) {}
")

curl -s -H "x-auth-token: ${AUTH_TOKEN}" -H "Accept: application/json" \
  "https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json

node -e "
  const d = require('fs').readFileSync('.claude-plugin/sites-config.json', 'utf8');
  const j = JSON.parse(d);
  if (!j.sites || !j.sites.length) {
    console.error('No sites returned — verify org name and re-authenticate if needed');
    process.exit(1);
  }
  console.log('Found ' + j.sites.length + ' site(s): ' + j.sites.map(s => s.name).join(', '));
"

If validation fails, verify the org name is correct, re-authenticate, and retry.

Fetch per-site config for content details:

curl -s -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"

Extract:

• code.owner / code.repo — GitHub repository
• content.source.url — Content mountpath (e.g., https://content.da.live/org/site/)
• content.source.type — Content source type (markup, onedrive, google)

Build DA and Block Library URLs from content source:

• DA URL: https://da.live/#/{org}/{site}/
• Block Library: https://da.live/#/{org}/{site}/.da/library

Multiple sites = repoless setup. Single site = standard setup.

1.2 Check Multi-Language Support

ls -la /en /fr /de /es /it 2>/dev/null || echo "Check DA for language folders"

Record whether the project is multi-lingual and which languages are supported.

---

Phase 2: Analyze Content Structure

Read site config from Phase 1:

cat .claude-plugin/sites-config.json

2.1 Analyze Navigation and Footer

ls nav.md footer.md 2>/dev/null || echo "Nav/footer likely in DA"

Document: Navigation and footer location (DA path or local file), menu structure, mobile behavior.

2.2 Identify Page Templates

ls -la templates/ 2>/dev/null && ls templates/

For each template, document: name, purpose, how to apply (metadata setting).

2.3 Section Styles

grep -E "\.section\." styles/styles.css 2>/dev/null | head -15

Document available section styles (e.g., dark, highlight, narrow) for the guide's "Available Section Styles" table.

---

Phase 3: Document Blocks and Templates

3.1 List and Analyze Blocks

ls blocks/

Run block analysis silently. For each block determine: purpose, variants (from CSS .blockname.variant), and when authors should use it. Document all blocks so authors know what's available.

3.2 Document Templates

For each template found in Phase 2.2, document: name, purpose, required metadata fields, and how to apply (template: name in Metadata block).

3.3 DA and Block Library Paths

Get the content path from the Config Service site config. Block Library URL is https://da.live/#/{content-owner}/{content-path}/.da/library — the path varies by project.

---

Phase 4: Document Configuration Sheets

4.1 Placeholders

ls placeholders.json 2>/dev/null

Document: location in DA, language sheets, key strings authors might need to update.

4.2 Redirects

ls redirects.json 2>/dev/null

Document: location in DA, format (source → destination columns), when to use.

4.3 Bulk Metadata

ls metadata.json 2>/dev/null

Document: location in DA, URL patterns, which metadata properties are set in bulk.

4.4 Other Configuration Sheets

ls -la *.xlsx *.json 2>/dev/null | grep -v package

---

Phase 5: Generate Author Guide

5.1 Output File

Save to project-guides/AUTHOR-GUIDE.md (run mkdir -p project-guides first).

---
title: "[Project Name] - Author Guide"
date: "[Full Date — e.g., February 17, 2026]"
---

# [Project Name] - Author Guide

## Quick Reference

| Resource | URL |
|----------|-----|
| Document Authoring | https://da.live/#/{content-owner}/{content-path}/ |
| Preview (per site) | https://main--{site}--{org}.aem.page/ |
| Live (per site) | https://main--{site}--{org}.aem.live/ |
| Block Library | https://da.live/#/{content-owner}/{content-path}/.da/library |
| Bulk Operations | https://da.live/apps/bulk |

(**Content path** comes from the Config Service site config — e.g., `content.da.live/org/site/` → use `org/site` for the path after `#/`. This varies by project.)

### Sites

| Site | Content Source (DA) | Preview | Live |
|------|---------------------|---------|------|
| {site1} | [from site config] | https://main--{site1}--{org}.aem.page/ | https://main--{site1}--{org}.aem.live/ |

## Getting Started

### Access Requirements
- [ ] DA access (request from admin)
- [ ] Preview/publish permissions

### Your First Page
1. Go to DA: [link]
2. Navigate to the correct folder
3. Create new document
4. Use blocks from Library sidebar
5. Add Metadata block at bottom
6. Preview → Publish

## Content Organization

### Site Structure
[Describe the folder structure in DA]

### Languages
[List supported languages if multi-lingual]

## Block Library

The Block Library is the sidebar in Document Authoring where you browse and insert blocks and templates.

| What | Details |
|------|---------|
| **Open in DA** | Use the Library icon in the DA editor sidebar, or go directly to: `https://da.live/#/{content-owner}/{content-path}/.da/library` |
| **How to use** | Click a block or template in the library to insert it at the cursor position |

## Available Blocks

| Block | Purpose | Variants | Usage |
|-------|---------|----------|-------|
| [name] | [what it's for] | [variant1, variant2] | [when to use] |

[Generate table rows for all blocks]

## Page Templates

| Template | Purpose | Required Metadata | How to Apply |
|----------|---------|-------------------|--------------|
| [name] | [what type of pages] | [key fields] | `template: [name]` in Metadata |

[Generate table rows for all templates]

## Configuration Sheets

| Sheet | Location | Purpose | When to Update |
|-------|----------|---------|----------------|
| Placeholders | `/placeholders` | Reusable text strings, translations | Changing labels, button text |
| Redirects | `/redirects` | Forward old URLs to new URLs | After deleting/moving pages |
| Bulk Metadata | `/metadata` | Apply metadata to multiple pages | Setting defaults by folder |

## Publishing Workflow

| Environment | Domain | Purpose |
|-------------|--------|---------|
| Preview | `.aem.page` | Test changes before going live |
| Live | `.aem.live` | Production site |

**Workflow:** Edit in DA → Preview → Publish → Live immediately

**Bulk:** https://da.live/apps/bulk

## Common Tasks

| Task | Steps |
|------|-------|
| **Create a Page** | Navigate to folder → New → Document → Add content → Add Metadata → Preview → Publish |
| **Edit a Page** | Open in DA → Make changes → Preview → Publish |
| **Delete a Page** | Add redirect first → Delete document → Publish redirects |
| **Update Navigation** | Edit `/nav` document → Preview → Publish |
| **Update Footer** | Edit `/footer` document → Preview → Publish |

## Sections and Section Metadata

Sections group content together. Create sections with horizontal rules (`---`).

Add styles with a Section Metadata block at the end of the section:

| Section Metadata | |
|------------------|-|
| style | [style-name] |

**Available Section Styles:**

| Style | Effect |
|-------|--------|
| [List project-specific styles] | |

## Page Metadata

| Property | Required | Purpose | Example |
|----------|----------|---------|---------|
| `title` | Yes | Page title for SEO | "About Us" |
| `description` | Yes | SEO description | "Learn about..." |
| `image` | No | Social sharing image | /images/og.jpg |
| `template` | No | Apply page template | project-article |
| [Add project-specific fields] | | | |

## Images and Media

| Method | How |
|--------|-----|
| Drag & drop | Drag images directly into DA editor |
| AEM Assets | Use Assets sidebar in DA |

Best practices: descriptive filenames, always add alt text, images auto-optimized.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Page not updating after publish | Wait 1-2 min for cache, hard refresh (Cmd+Shift+R) |
| Block not displaying correctly | Check structure matches expected format, verify variant spelling |
| Images not showing | Verify image uploaded to DA, check path is correct |
| Wrong template styling | Check `template` value in Metadata matches template name exactly |

## Resources

| Resource | URL |
|----------|-----|
| DA Documentation | https://docs.da.live/ |
| Authoring Guide | https://www.aem.live/docs/authoring |
| Placeholders Docs | https://www.aem.live/docs/placeholders |
| Redirects Docs | https://www.aem.live/docs/redirects |

## Support Contacts

[Add project-specific contacts]

5.2 Convert to Professional PDF

Save the completed markdown to project-guides/AUTHOR-GUIDE.md with YAML frontmatter (title, date using full date format e.g., "February 17, 2026"). Then immediately invoke PDF conversion:

Skill({ skill: "aem-project-management:whitepaper", args: "project-guides/AUTHOR-GUIDE.md project-guides/AUTHOR-GUIDE.pdf" })

The whitepaper skill auto-cleans source files. Final output: project-guides/AUTHOR-GUIDE.pdf.

Inform the user: "Author guide complete: project-guides/AUTHOR-GUIDE.pdf"

---

Success Criteria

| Category | Check | |----------|-------| | Data Source | Config Service API called (https://admin.hlx.page/config/{ORG}/sites.json) | | Data Source | Site list from API response, not fstab.yaml or codebase analysis | | Data Source | DA/Block Library URLs derived from Config Service content source, not assumed from code.owner/repo | | Content | Quick Reference table with all project URLs | | Content | All blocks documented in table format | | Content | All templates documented with required metadata | | Content | Configuration sheets documented | | Content | Publishing workflow explained | | Content | Common tasks documented | | Content | Section/page metadata options listed | | Content | Troubleshooting included | | Output | PDF generated at project-guides/AUTHOR-GUIDE.pdf | | Output | All source files cleaned up (only PDF remains) |

---

Communication: Never use "EDS" as an acronym — always write "Edge Delivery Services" or "AEM Edge Delivery Services" in all output and documentation.