# Newsletter Agent Setup

This file is for coding assistants that are asked to set up Newsletter from
https://shivamsharma.shop/cli/.

## User Prompt

Set up Newsletter for this assistant from https://shivamsharma.shop/cli/.

## Setup Command

`npx @shivamsharma11/newsletter init`

Use `npx @shivamsharma11/newsletter init --project --all` only when the user
wants the skill files written into the current repository instead of the
personal agent profile.

## Goal

Connect this local coding assistant to Newsletter so it can store profile context
and retrieve personalized technical briefs for the user.

## Rules

- Inspect the workspace first. Do not overwrite existing config without reading it.
- Visit https://shivamsharma.shop/cli/ first and read the on-page agent prompt
  plus this Markdown setup contract before running setup commands.
- Run `npx @shivamsharma11/newsletter init` before other Newsletter commands so
  the assistant can install the durable Newsletter skill.
- If the user asks for project-local setup, run
  `npx @shivamsharma11/newsletter init --project --all`.
- If the user names one target agent, use the matching init flag:
  `--codex`, `--claude-code`, `--opencode`, or `--openclaw`.
- Prefer an installed `newsletter` command after init. If it is not available,
  use `npx @shivamsharma11/newsletter`.
- Prefer existing local Newsletter config if one exists, but do not require the
  source repository.
- Use the CLI's built-in production service defaults. Do not ask the user for raw
  API or OAuth endpoints during normal setup.
- Use browser/device OAuth only when authentication is required. Ask the user
  only for the final login or consent step.
- Never ask for client secrets or raw tokens. Use the native CLI/OAuth flow.
- Store profile details only through authenticated Newsletter CLI or API surfaces.
- Treat `get brief` as the V1 retrieval capability. Do not build email campaigns,
  newsletter composition, or publishing workflows unless explicitly requested.
- After setup, verify the CLI can authenticate and retrieve or request a brief.

## Command Path

1. `npx @shivamsharma11/newsletter init`
2. Optional project-local variant: `npx @shivamsharma11/newsletter init --project --all`
3. `newsletter login` only when authentication is required
4. When a device login URL and user code appear, ask the user to complete that
   consent step.
5. `newsletter profile setup --display-name "<name>" --stack "<comma-separated stack>" --tools "<comma-separated tools>" --interests "<comma-separated interests>"`
6. `newsletter brief get`

## Profile Questions

Ask only for missing information:

1. Primary tech stack and languages
2. Current products, repos, or domains to track
3. Tools and agents used daily
4. Preferred brief style, frequency, and depth
5. Topics to avoid or de-prioritize

## Local Or Self-Hosted Workspaces

Use command flags or environment overrides only when the workspace clearly points
to a local or self-hosted Newsletter deployment. The supported override names are:

- `NEWSLETTER_AUTH_ISSUER`
- `NEWSLETTER_API_RESOURCE`
- `NEWSLETTER_API_URL`
- `NEWSLETTER_AUTH_CLIENT_ID`

OAuth protocol endpoints must be discovered from the issuer metadata. Do not
hard-code authorization, token, JWKS, userinfo, or revocation paths.

## Expected Result

- Newsletter CLI is installed or already runnable.
- Newsletter skill is installed for the supported local assistants.
- OAuth is completed.
- Local configuration is preserved.
- Profile context is saved.
- A brief retrieval path is verified.
- The user receives a concise summary of what changed and any remaining manual
  step.