refactor: adopt two-tier plugin layout

Align msgraph-stdlib with the template's two-tier layout. The shippable
payload now lives under plugin/ and the repo root is the build/distribution
repo. This adds the previously-missing .claude-plugin/marketplace.json, which
is what makes `/plugin install msgraph-stdlib@neilgfoster/msgraph-stdlib`
resolvable.

- Move payload under plugin/: .claude-plugin/plugin.json, hooks/, skills/,
  src/{example,msgraph}/ (CLAUDE_PLUGIN_ROOT resolves to plugin/, so internal
  references are unchanged).
- Add root build layer: marketplace.json (source ./plugin), pyproject.toml,
  CI + release workflows, PR template, CHANGELOG, CONTRIBUTING.
- Add tests: marketplace->plugin manifest resolution; client describe smoke.
- Update README / CLAUDE.md / DEFINITION_OF_DONE paths; ignore uv/ruff/pytest
  dev artifacts.

Layout-only; no runtime behaviour change. Tests pass (3/3). Pre-existing ruff
findings in the in-progress kernel are left for /speckit-implement.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: neilgfoster

.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "msgraph-stdlib",
+  "owner": {
+    "name": "Neil Foster",
+    "url": "https://github.com/neilgfoster"
+  },
+  "plugins": [
+    {
+      "name": "msgraph-stdlib",
+      "source": "./plugin",
+      "description": "Stdlib-only, zero-backend Claude Code plugin for Microsoft Graph: read Outlook mail and author/verify native Outlook message rules. Read-only by default, with a least-privilege scope ratchet and read-only catch-set verification before any rule is installed."
+    }
+  ]
+}

.github/pull_request_template.md

@@ -0,0 +1,26 @@
+<!--
+PR title should be a Conventional Commit (e.g. `feat: ...`, `fix: ...`, `docs: ...`).
+-->
+
+## What and why
+
+<!-- One paragraph: what this changes and why. -->
+
+## Conventions
+
+- [ ] Runtime stays **stdlib-only, zero-dependency, zero-backend** (`urllib`/`json`; ruff/pytest are
+  dev tooling only).
+- [ ] No secrets/tokens in the repo — they live outside it in an XDG path (`0600`).
+- [ ] Any new/changed skill follows `docs/AGENT-FRIENDLY.md` (description + CLI I/O are the contract).
+- [ ] Read-only safety model intact: `Mail.Read`-only read path, scope ratchet for writes,
+  verify-then-install (read-only catch-set), file-to-folder (never delete).
+
+## Verification
+
+```sh
+ruff check . && ruff format --check .
+python3 -m pytest -q
+```
+
+- [ ] `ruff check .` and `ruff format --check .` pass.
+- [ ] `python3 -m pytest -q` passes.

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dev tooling
+        run: pip install ruff pytest
+      - name: Lint
+        run: ruff check .
+      - name: Format check
+        run: ruff format --check .
+      - name: Test
+        run: python3 -m pytest -q

.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: release
+
+# Cut a GitHub Release from a vX.Y.Z tag. The version in
+# plugin/.claude-plugin/plugin.json is the single source of truth; this workflow refuses to
+# release if the tag and that version disagree, then publishes notes from CHANGELOG.md.
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify tag matches plugin.json version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          ver=$(python3 -c "import json; print(json.load(open('plugin/.claude-plugin/plugin.json'))['version'])")
+          if [ "$tag" != "$ver" ]; then
+            echo "tag $GITHUB_REF_NAME does not match plugin.json version $ver" >&2
+            exit 1
+          fi
+
+      - name: Extract release notes from CHANGELOG
+        run: |
+          ver="${GITHUB_REF_NAME#v}"
+          awk -v v="$ver" '
+            $0 ~ "^## \\[" v "\\]" {grab=1; next}
+            grab && /^## \[/ {exit}
+            grab {print}
+          ' CHANGELOG.md > RELEASE_NOTES.md
+          if [ ! -s RELEASE_NOTES.md ]; then
+            echo "No CHANGELOG section for $ver." > RELEASE_NOTES.md
+          fi
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file RELEASE_NOTES.md

.gitignore

@@ -2,6 +2,12 @@ __pycache__/
 *.pyc
 .DS_Store
 
+# Local dev-tooling artifacts (ruff/pytest via uv) — never shipped.
+.venv/
+uv.lock
+.ruff_cache/
+.pytest_cache/
+
 # Secrets/tokens NEVER live in the repo — they belong outside it (XDG, 0600).
 # These patterns are belt-and-braces only; the real guarantee is storing tokens
 # at ${XDG_STATE_HOME:-~/.local/state}/<plugin>/ outside the project tree.
@@ -20,3 +26,20 @@ specs/
 .github/agents/speckit*
 .github/prompts/speckit*
 # --- end ---
+
+# --- tredl (solo trial) ---
+# tredl is installed transparently for one person: the Spec Kit and tredl artifacts below stay
+# local, so adopting tredl leaves (almost) no footprint on the team. When the value is proven,
+# delete this block and commit the artifacts to graduate the team. See
+# docs/adr/0003-transparent-solo-by-default.md.
+# Caveat: if your repo already tracks a CLAUDE.md, Spec Kit appends a small SPECKIT pointer
+# block to it - a tracked edit a .gitignore cannot cover. Run `git checkout CLAUDE.md` to drop
+# it for a zero tracked footprint, or keep it.
+.tredl/
+.specify/
+specs/
+.claude/skills/speckit-*/
+.agents/skills/speckit-*/
+.github/agents/speckit*
+.github/prompts/speckit*
+# --- end tredl ---

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this plugin are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this plugin uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Pre-1.0, breaking changes may land on a
+minor bump and are called out explicitly.
+
+The `version` in `plugin/.claude-plugin/plugin.json` is the single source of truth; the release
+workflow refuses to publish a tag that disagrees with it.
+
+## [Unreleased]
+
+<!--
+Add notes here under Added / Changed / Fixed / Removed. On release, move them under a new
+## [X.Y.Z] - YYYY-MM-DD heading and bump plugin/.claude-plugin/plugin.json to match.
+-->

CLAUDE.md

@@ -10,8 +10,8 @@ to "done" is in this repo. The target is `DEFINITION_OF_DONE.md`; read it first.
 `msgraph-stdlib` — a Claude Code plugin that lets an agent **read Outlook mail** and **author native
 Outlook message rules** via Microsoft Graph, with no third-party dependencies and no backend.
 
-The `src/example/` package and `skills/example-subject-verb/` skill are the **inert template
-reference pattern**. Your first build step is to replace them (see "Build plan" below). Keep them as
+The `plugin/src/example/` package and `plugin/skills/example-subject-verb/` skill are the **inert
+template reference pattern**. Your first build step is to replace them (see "Build plan" below). Keep them as
 a reference while you work; delete them once the real skills exist.
 
 ## Non-negotiable conventions (inherited from the template — do not relax)
@@ -46,13 +46,13 @@ This is the heart of the plugin; do not weaken it for convenience.
 
 ## Capabilities to build (the verbs)
 
-Group into skills under `skills/<subject>-<verb>/`, all backed by the `src/msgraph/` kernel:
+Group into skills under `plugin/skills/<subject>-<verb>/`, all backed by the `plugin/src/msgraph/` kernel:
 
 | Skill | Scope | Notes |
 |---|---|---|
-| `auth-login` | `Mail.Read` (default) or `+MailboxSettings.ReadWrite` (opt-in) | device-code flow; cache token at the XDG path; refresh via refresh-token |
+| `auth-login` | `Mail.Read + MailboxSettings.Read` (default read-only) or `Mail.Read + MailboxSettings.ReadWrite` (opt-in) | device-code flow; cache token at the XDG path; refresh via refresh-token |
 | `mail-list` / `mail-get` | `Mail.Read` | list/get messages incl. headers (`internetMessageHeaders`); concise/detailed; pagination default |
-| `rule-list` | `Mail.Read` *(rules are mailbox settings — confirm exact read scope during `plan`)* | enumerate existing `messageRule`s, agent-legible |
+| `rule-list` | `MailboxSettings.Read` *(rules are mailbox settings; included in read-only mode — resolved during `plan`)* | enumerate existing `messageRule`s, agent-legible |
 | `rule-verify` | `Mail.Read` | given candidate predicates (e.g. `headerContains: ["List-Unsubscribe"]`), compute and return the **read-only catch-set** — no write |
 | `rule-create` | `MailboxSettings.ReadWrite` | install a verified rule (predicate → move-to-folder action). Refuse unless a catch-set was verified |
 | `rule-remove` | `MailboxSettings.ReadWrite` | delete a rule by id (the reversibility primitive) |
@@ -63,10 +63,10 @@ Graph endpoints are simple REST over `urllib`; `messageRule` lives under
 ## Prerequisite the human must do once (free)
 
 Azure AD **app registration**: public client, device-code/public-client flow enabled, delegated
-permission `Mail.Read` (+ `MailboxSettings.ReadWrite` for rule authoring). Personal accounts need no
-admin consent. The session should read `MSGRAPH_CLIENT_ID` / `MSGRAPH_TENANT_ID` (default tenant
+permissions `Mail.Read` + `MailboxSettings.Read` (read-only: read mail and list rules) (+
+`MailboxSettings.ReadWrite` for rule authoring). Personal accounts need no admin consent. The session should read `MSGRAPH_CLIENT_ID` / `MSGRAPH_TENANT_ID` (default tenant
 `consumers` or `common`) from the environment — never hardcode them. Document this in
-`skills/auth-login` and the README. **This is not blocking** for `specify`/`clarify`/`plan`/`tasks`
+`plugin/skills/auth-login` and the README. **This is not blocking** for `specify`/`clarify`/`plan`/`tasks`
 or for offline-testable code; only live auth/integration testing needs it.
 
 ## Build plan (spec-first; this is the work)
@@ -80,16 +80,28 @@ or advertise it.
 2. `/speckit-specify` — one feature: **Graph device-code auth + Outlook mail read + message-rule
    CRUD with read-only catch-set verification.** Carry the safety model above as hard requirements.
 3. `/speckit-clarify` → `/speckit-plan` → `/speckit-tasks` → `/speckit-implement`.
-4. Replace `src/example/` → `src/msgraph/` (update `APP`); replace the example skill with the real
-   ones; make `python3 -m msgraph.client describe` emit the `TOOLS` catalog.
+4. Replace `plugin/src/example/` → `plugin/src/msgraph/` (update `APP`); replace the example skill
+   with the real ones; make `python3 -m msgraph.client describe` emit the `TOOLS` catalog.
 5. Validate against `DEFINITION_OF_DONE.md`. Open a PR for review.
 
 ## Where things are
 
 | Path | Purpose |
 |---|---|
 | `DEFINITION_OF_DONE.md` | **The build target** — read first |
-| `.claude-plugin/plugin.json` | Plugin manifest |
-| `skills/<subject>-<verb>/SKILL.md` | Agent-facing commands |
-| `src/msgraph/client.py` | Stdlib kernel — importable AND runnable; owns the `describe` catalog |
+| `.claude-plugin/marketplace.json` | Marketplace entry — plugin `source` points at `./plugin` |
+| `plugin/.claude-plugin/plugin.json` | Plugin manifest (lives inside the shippable payload) |
+| `plugin/skills/<subject>-<verb>/SKILL.md` | Agent-facing commands |
+| `plugin/src/msgraph/client.py` | Stdlib kernel — importable AND runnable; owns the `describe` catalog |
 | `docs/AGENT-FRIENDLY.md` | **Required reading** — agent-tool design principles |
+| `pyproject.toml`, `tests/`, `.github/` | Dev tooling, tests, CI/release — never shipped in `plugin/` |
+
+**Two-tier layout.** `plugin/` is the shippable payload (its own `.claude-plugin/plugin.json` +
+`skills/`, `src/`, `hooks/`); the repo root is the build/distribution repo. Inside the plugin,
+reference bundled files via `${CLAUDE_PLUGIN_ROOT}/...` — it resolves to `plugin/`.
+
+<!-- SPECKIT START -->
+Active feature plan: `specs/001-msgraph-mail-rules/plan.md` (spec, research, data-model,
+contracts/tools.md, quickstart alongside it). Read it for the technical context, the stdlib-only
+device-code design, the `TOOLS` catalog contract, and the safety-model decisions before implementing.
+<!-- SPECKIT END -->

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+`msgraph-stdlib` is a standalone, public, MIT plugin. The few rules that earn their keep:
+
+## Standards
+
+- **Python 3.11+, stdlib only at runtime.** `urllib` for HTTP, `json` for parsing. `ruff` and
+  `pytest` are dev tooling — they never ship in `plugin/`. No third-party runtime dependencies, no
+  backend/server process. The constraint is the product: portable, auditable, no supply-chain surface.
+- **Two-tier layout.** `plugin/` is the shippable payload (its own `.claude-plugin/plugin.json` +
+  `skills/`, `src/`, `hooks/`); the repo root is the build/distribution repo
+  (`.claude-plugin/marketplace.json`, `pyproject.toml`, `tests/`, `.github/`, docs). Inside the
+  plugin, reference bundled files via `${CLAUDE_PLUGIN_ROOT}/...` — it resolves to `plugin/`.
+- **Command naming: `<subject>-<verb>`.** Skills are named subject-then-verb (e.g. `mail-list`,
+  `rule-verify`). Keep the convention.
+- **Secrets live OUTSIDE the repo** — a user-level XDG path
+  (`${XDG_STATE_HOME:-~/.local/state}/msgraph-stdlib/`) with `0600` perms. Never committed, not even
+  encrypted. Do not add an in-repo secrets path or a git-crypt dependency.
+- **Safety model is structural.** Read path requests only `Mail.Read`; rule authoring uses the
+  separate `MailboxSettings.ReadWrite` scope; a rule is verified against a read-only catch-set before
+  install; rule actions file to a folder and never delete. Do not weaken these for convenience.
+- **Agent-friendly by design.** Every skill follows `docs/AGENT-FRIENDLY.md` — read it before adding
+  or changing a skill. The skill `description` and the CLI's inputs/outputs **are** the tool contract
+  an agent reads.
+- **Conventional Commit messages and PR titles.**
+
+## Verify before claiming done
+
+```sh
+ruff check . && ruff format --check .
+python3 -m pytest -q
+```
+
+CI (`.github/workflows/ci.yml`) runs exactly these; green CI is part of the Definition of Done.
+
+## Cutting a release
+
+SemVer, tag-driven. The version in `plugin/.claude-plugin/plugin.json` is the single source of truth.
+
+1. Bump `version` in `plugin/.claude-plugin/plugin.json`.
+2. In `CHANGELOG.md`, move `## [Unreleased]` notes under a new `## [X.Y.Z] - YYYY-MM-DD` heading.
+3. `ruff check . && ruff format --check . && python3 -m pytest -q`.
+4. Merge, then `git tag vX.Y.Z && git push origin vX.Y.Z`. The release workflow publishes it.

DEFINITION_OF_DONE.md

@@ -40,8 +40,12 @@ plugin is "done" for its first release when **every** box below is true. Read `C
 
 - [ ] **Offline-testable.** Classification/verification/output-shaping logic is unit-tested without
       network (Graph HTTP boundary mockable). Tests pass with stdlib only.
-- [ ] **Template residue gone.** `src/example/` and `skills/example-subject-verb/` replaced by the
-      real `src/msgraph/` and real skills; placeholders (`{{NAME}}`/`{{DESCRIPTION}}`) all filled.
+- [ ] **Two-tier layout.** Shippable payload lives under `plugin/` (`plugin/.claude-plugin/plugin.json`,
+      `plugin/skills/`, `plugin/src/msgraph/`); the root carries `.claude-plugin/marketplace.json`
+      whose plugin `source` resolves to `./plugin`.
+- [ ] **Template residue gone.** `plugin/src/example/` and `plugin/skills/example-subject-verb/`
+      replaced by the real `plugin/src/msgraph/` and real skills; placeholders
+      (`{{NAME}}`/`{{DESCRIPTION}}`) all filled.
 - [ ] **Docs honest.** `README.md` reflects the shipped verbs; `auth-login` documents the one-time
       Azure app-registration prerequisite and the `MSGRAPH_CLIENT_ID`/`MSGRAPH_TENANT_ID` env vars.
 - [ ] **SDD trail stays local.** `.specify/`, `specs/`, `.tredl/` remain gitignored; the public

README.md

@@ -32,13 +32,17 @@ with no supply-chain surface beyond the standard library.
 
 ## Layout
 
+Two-tier: `plugin/` is the shippable payload; the repo root is the build/distribution repo.
+
 ```
-.claude-plugin/plugin.json        # manifest
-skills/<subject>-<verb>/SKILL.md  # agent-facing commands (auth, mail-read, rule-*)
-src/msgraph/client.py             # stdlib kernel — importable + runnable, exposes a `describe` catalog
-docs/AGENT-FRIENDLY.md            # REQUIRED READING before adding/changing a skill
-DEFINITION_OF_DONE.md             # what "working" means — the build target
-CLAUDE.md                         # grounding + build plan for a Claude Code session in this repo
+.claude-plugin/marketplace.json          # marketplace entry — points at ./plugin
+plugin/.claude-plugin/plugin.json        # plugin manifest
+plugin/skills/<subject>-<verb>/SKILL.md  # agent-facing commands (auth, mail-read, rule-*)
+plugin/src/msgraph/client.py             # stdlib kernel — importable + runnable, exposes a `describe` catalog
+docs/AGENT-FRIENDLY.md                   # REQUIRED READING before adding/changing a skill
+pyproject.toml  tests/  .github/         # dev tooling, tests, CI/release (never shipped)
+DEFINITION_OF_DONE.md                    # what "working" means — the build target
+CLAUDE.md                                # grounding + build plan for a Claude Code session in this repo
 ```
 
 ## Prerequisite (one-time, free)