awesome-agents 0.1.5 → 0.1.8

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 This file is maintained by `npm run changelog` and `npm run release`. Release entries are generated from git commit history.
 
+## 0.1.8 - 2026-07-08
+
+Changes since `v0.1.6`.
+
+### Added
+
+- Add "What is an agent?" marketing page and link it site-wide (fa8255e)
+- Add Goose to site harness surfaces (7a444cf)
+- Add Goose harness support (#9) (c4049f2)
+- Add public builder profile prototype (e78202e)
+- Add plan for public-builder-profiles-agent-model-cards (64e254a)
+- Add generated docs site (8eb21ba)
+
+### Changed
+
+- Prepare 0.1.7 release (342e93d)
+- Link hosted artifacts for public-builder-profiles-agent-model-cards (0f76238)
+- Update tenex-edge launch commands (cc304e2)
+
+### Documentation
+
+- rebuild /docs in the shadcn-docs layout (878803c)
+
+## 0.1.7 - 2026-07-07
+
+Changes since `v0.1.6`.
+
+### Added
+
+- Add generated docs site (8eb21ba)
+
+### Changed
+
+- Update tenex-edge launch commands (cc304e2)
+
+## 0.1.6 - 2026-07-06
+
+Changes since `v0.1.5`.
+
+### Changed
+
+- Align harness detection docs (70a1f8e)
+- Improve agent install workflow (61470fc)
+
 ## 0.1.5 - 2026-07-06
 
 Changes since `v0.1.4`.

package/README.md

@@ -7,7 +7,7 @@ agent profile instead of a skill.
 Supported sources are GitHub repos, Git URLs, or local checkouts that use the
 agent-profile source layout. Profiles are read from YAML or Markdown files under
 `agents/<slug>/`, adapted for the selected harness, and installed into the
-right place for Codex, Claude Code, or OpenCode.
+right place for Codex, Claude Code, OpenCode, Goose, or tenex-edge.
 
 ## Install And Run
 
@@ -15,7 +15,7 @@ Use the CLI with `npx`:
 
 ```bash
 npx awesome-agents add owner/repo --agent triage-agent
-npx awesome-agents add owner/repo --agent triage-agent --harness opencode
+npx awesome-agents add owner/repo --agent triage-agent --harness tenex-edge
 ```
 
 From this repo during development:
@@ -43,19 +43,25 @@ Useful install options:
 - `--agent <slug>` to select an agent profile, for example `--agent triage-agent`
 - `--profile <slug>` or `--skill <slug>` as explicit profile aliases; `--skill`
   is command-shape compatibility and does not mean the artifact is a skill
-- `--harness codex|claude-code|opencode|*` to select target harnesses; without
-  it, the CLI installs to every harness whose CLI it finds on `PATH`
-  (falling back to Codex if none are found)
+- omit a profile selector in an interactive terminal to choose source profiles
+  from a checkbox list; every profile is selected by default
+- `--yes` to accept detected profile and harness selections without opening selectors
+- `--harness codex|claude-code|opencode|goose|tenex-edge|*` to select target harnesses;
+  without it, the CLI detects harness CLIs on `PATH`; interactive multi-detect
+  opens a checkbox selector with every detected harness selected, and
+  noninteractive installs use every detected harness. If none are detected, pass
+  `--harness`.
 - `--all` to install all profiles to all supported harnesses
 - `--dry-run` to preview writes
-- `--project` for project-level install where supported; Codex profiles install globally
+- `--project` for project-level install where supported; Codex and tenex-edge install globally
 - `--global` for user-level install
 - `--list` to inspect available source profiles without installing
 
 Human-readable output uses subtle ANSI color. Set `NO_COLOR=1` to disable color,
-or pass `--json` for machine-readable output. After an install, the CLI also
-prints run commands for target harness CLIs it finds on `PATH`, such as
-`codex --profile <profile>` or `claude --agent <profile>`.
+or pass `--json` for machine-readable output. After an install, the CLI groups
+run commands by profile for target harness CLIs it finds on `PATH`, such as
+`codex --profile <profile>`, `claude --agent <profile>`,
+`tenex-edge launch <profile>`, or `goose session` then `@<profile>`.
 
 ## Harness Targets
 
@@ -64,12 +70,16 @@ Project installs write to:
 - Codex: not supported; Codex profiles load from user config
 - Claude Code: `.claude/agents/<profile>.md`
 - OpenCode: `.opencode/agents/<profile>.md`
+- Goose: `.agents/agents/<profile>.md`
+- tenex-edge: not supported; tenex-edge agents are machine-local
 
 Global installs write to:
 
 - Codex: `$CODEX_HOME/<profile>.config.toml`, or `~/.codex/<profile>.config.toml`
 - Claude Code: `$CLAUDE_HOME/agents/<profile>.md`, or `~/.claude/agents/<profile>.md`
 - OpenCode: `$OPENCODE_CONFIG_DIR/agents/<profile>.md`, or `~/.config/opencode/agents/<profile>.md`
+- Goose: `$GOOSE_HOME/agents/<profile>.md`, or `~/.agents/agents/<profile>.md`
+- tenex-edge: `$TENEX_EDGE_HOME/agents/<profile>.json`, or `~/.tenex-edge/agents/<profile>.json`
 
 The CLI keeps its own registry at `.awesome-agents/installed.json` for project
 installs or `~/.awesome-agents/installed.json` for global installs. `list`,
@@ -95,6 +105,9 @@ agents/
     agent.yaml
   ops-agent/
     agent.agf.yaml
+    skills/
+      gh-pages-publisher/
+        SKILL.md
     scripts/
       heartbeat.sh
     references/
@@ -105,6 +118,19 @@ YAML profile files are preferred. The loader also accepts Markdown files with
 YAML frontmatter for compatibility with tools that use `.agent.md`-style
 profiles. Agent-owned `scripts/` and `references/` are installed into
 `~/.agents/homes/<slug>/scripts` and `~/.agents/homes/<slug>/references`.
+Profiles may also declare immediately relevant skills:
+
+```yaml
+skills:
+  - gh-pages-publisher
+  - pablof7z/tenex-edge basic-skill
+```
+
+Bare skill names are resolved from the profile directory, then the source
+checkout, then `~/.agents/skills`. Source-qualified entries use the same source
+plus skill selector shape as `npx skills add <source> --skill <skill>`.
+Declared skills are copied into `~/.agents/homes/<slug>/skills/<skill>` and
+listed with complete paths in the installed agent prompt.
 
 ## Examples
 
@@ -112,6 +138,7 @@ profiles. Agent-owned `scripts/` and `references/` are installed into
 npx awesome-agents add owner/repo --list
 npx awesome-agents add owner/repo --agent triage-agent
 npx awesome-agents add owner/repo --agent triage-agent --harness codex --global
+npx awesome-agents add owner/repo --agent triage-agent --harness tenex-edge
 npx awesome-agents add owner/repo --all --dry-run
 npx awesome-agents use owner/repo --agent triage-agent --harness claude-code
 npx awesome-agents list --json

package/docs/cli.md

@@ -10,11 +10,18 @@
 - `update` / `upgrade` reinstalls from the recorded source.
 - `init` creates a profile source skeleton.
 
-The CLI is noninteractive for the initial scaffold. Options such as `--yes` are
-accepted for parity, but command behavior should be fully scriptable. Installs
-default to project scope where the selected harness supports project-local
-profiles. Codex is the exception: Codex `--profile` loads named config layers
-from `CODEX_HOME`, so Codex profile installs are user-level.
+The CLI stays scriptable by default. In an interactive terminal, `add` opens a
+checkbox selector when no profile selector is provided; every source profile is
+selected by default. When no target harness is provided, `add` detects supported
+harness CLIs on `PATH`; multiple detected harnesses open a checkbox selector
+with every harness selected by default. Non-TTY runs, `--json`, and `--yes` use
+all detected selections without prompting. Installs default to project scope
+where the selected harness supports project-local profiles. Codex and tenex-edge
+are exceptions: Codex `--profile` loads named config layers from `CODEX_HOME`,
+while tenex-edge agents live in its machine keystore under
+`$TENEX_EDGE_HOME/agents/` or `~/.tenex-edge/agents/`. Goose uses
+`~/.agents/agents/<profile>.md` (global) or `.agents/agents/<profile>.md`
+(project).
 
 ## Source Resolution
 
@@ -51,20 +58,39 @@ generated profile is installed:
 npx awesome-agents add owner/repo --agent triage-agent --harness opencode
 ```
 
-For backward compatibility, `--agent codex`, `--agent claude-code`, and
-`--agent opencode` are still accepted as harness selectors.
+For backward compatibility, `--agent codex`, `--agent claude-code`,
+`--agent opencode`, `--agent goose`, and `--agent tenex-edge` are still accepted as harness
+selectors.
+
+When no harness selector is provided, `add` detects `codex`, `claude`,
+`opencode`, `goose`, and `tenex-edge` on `PATH`. If none are found, the command fails and
+asks for `--harness`.
+
+When no profile selector is provided in an interactive terminal, `add` prompts
+with a checkbox list of source profiles and their summaries. Pressing Enter
+accepts the default of installing every listed profile. Scripts can use `--yes`,
+`--json`, or a non-TTY stdin/stdout path to keep the same noninteractive default.
 
 The `--skill` flag is accepted only as a command-shape alias for `--profile`.
 Installed artifacts remain operational agent profiles.
 
+Profiles may still declare immediately relevant skills in their source
+definition. Those dependencies are copied into
+`~/.agents/homes/<profile>/skills/<skill>` and appended to the installed prompt
+with complete paths; this does not make the profile itself a skill.
+
 After install, human-readable output should show the CLI command to run each
 installed profile through any matching harness CLI found on `PATH`. Examples:
 
 ```bash
 codex --profile triage-agent
 claude --agent triage-agent
+goose session
+tenex-edge launch triage-agent
 ```
 
+For Goose, start `goose session` and invoke the agent by name with `@<profile>`.
+
 ## Install Safety
 
 Generated files contain the marker `Generated by awesome-agents`. The CLI refuses

package/docs/plans/public-builder-profiles-agent-model-cards/plan.md

@@ -0,0 +1,105 @@
+# Public Builder Profiles And Agent Model Cards
+
+## Summary
+
+Add the first public site slice for builder profiles and repository-scoped agent model cards, using GitHub identity assumptions and README-backed content where available while keeping the CLI source format repo-neutral.
+
+## Boundaries
+
+```mermaid
+flowchart LR
+  GitHub[GitHub identity] --> Builder[Builder profile /handle]
+  Repo[Agent source repo] --> AgentYaml[agents/slug/agent.yaml]
+  Repo --> Readme[optional agents/slug/README.md]
+  AgentYaml --> Card[Model card route]
+  Readme --> Card
+  Builder --> Card
+  Card --> Install[npx awesome-agents add owner/repo --agent slug]
+  User[Logged-in user] --> Reviews[Reviews later persisted by backend]
+  Reviews --> Card
+```
+
+## Detailed Plan
+
+## Summary
+
+Implement the first public social-profile slice for `awesome-agents.com`: a builder profile route and repository-scoped agent model-card route. Keep it frontend-first and static-data-backed in this repo, while documenting the future backend contract for GitHub login, handle claiming, ownership verification, and reviews.
+
+## Implementation Scope
+
+1. Add site data structures for builders, repos, and agent cards.
+2. Add `/pablof7z` style builder route support through `site/vercel.json` rewrites and a static page/controller.
+3. Add `/pablof7z/touch-grass/chief-of-staff` style model-card route support.
+4. Preserve the existing `/agents/:slug` page as compatibility or redirect-like behavior where practical.
+5. Render optional README-backed model-card content when available in seeded data; render generated fallback sections when absent.
+6. Add visible login/claim/review affordances as nonfunctional or mocked states only if clearly labeled by behavior, not by insecure fake auth.
+7. Use the requested high-design frontend direction for the profile/model-card surfaces while keeping controls usable and text readable.
+
+## Backend Boundary
+
+Future GitHub auth should request basic profile and email access only, such as `read:user` plus `user:email`. The persisted user identity should include GitHub id, login, display name, avatar URL, and verified email where available. Handle claims are first-come-first-served. Repo ownership verification should be done through GitHub identity or GitHub App installation, not through user-entered claims alone. Reviews should require login; MVP has no spam filtering.
+
+## Rollout
+
+Ship the static route/content slice first. Keep existing directory links working. Once the UX holds up, add backend endpoints for auth callback, session, handle claims, repo imports, and review creation.
+
+## Validation
+
+Run `npm run lint` and `npm test` for the Node package. For site work, serve `site/` locally and inspect desktop and mobile routes with Playwright or a browser. Verify no horizontal overflow, route rewrites resolve, copy buttons still work, and old `/agents/:slug` pages are not broken.
+
+## Rollback
+
+Because the first slice is static, rollback is removing the new site page/controller/data entries and rewrites. CLI behavior should remain unaffected.
+
+## Observability
+
+No runtime observability is needed for the static slice. Future backend work should log OAuth callback failures, handle-claim conflicts, repo import failures, and review creation outcomes without logging tokens or private email values unnecessarily.
+
+## Migration
+
+No data migration is required for the first slice. Future migration should reserve existing GitHub usernames as default handles only when a user signs in or claims them, because handle policy is first-come-first-served.
+
+## Risks
+
+The main risk is making the prototype look like real auth or real persisted reviews. Keep those boundaries visually clear. The second risk is route collision between docs, assets, agent compatibility routes, and builder handles; rewrites should reserve known top-level paths before treating a path as a handle.
+
+## Open Questions
+
+Should launch support custom handles beyond GitHub usernames? Which metrics are platform-verified versus self-reported? What review moderation controls should be added once real volume exists?
+
+## Rule And ADR Check
+
+- Respects AGENTS.md by keeping runtime CLI behavior in `src/` untouched for the first site slice.
+- Preserves source independence: no runtime CLI behavior, tests, or examples should hard-code one source repository.
+- Matches product docs: README model-card content is optional, GitHub login requests basic profile plus email, reviews have no MVP spam filtering, and handles are first-come-first-served.
+- Keeps examples that can write user directories behind dry-run or outside CLI examples.
+
+## Possible Rule Or ADR Loosening
+
+- No existing rule needs loosening for the frontend prototype.
+- A future backend may need a new repository rule separating public site source fixtures from runtime CLI source fixtures so real showcased builders do not leak into CLI tests.
+
+## Possible Rule Tightening
+
+- Consider adding a rule that public site routes must prefer repo-neutral fixtures unless a page intentionally demonstrates a real claimed profile.
+- Consider requiring auth-related docs to name requested OAuth scopes and stored identity fields before any backend implementation lands.
+
+## Alternatives Considered
+
+- Full backend now: enables real login and reviews, but expands scope into persistence, secrets, deployment, and security before route/content UX is validated.
+- Only update product docs: too slow for the user's request to start building and does not test whether the social profile concept works on the site.
+- Replace the existing directory with social profiles immediately: cleaner long-term shape, but risks breaking current static pages and install-directory behavior.
+
+## Certainty
+
+86 percent.
+
+## Decision
+
+ready
+
+## Hosted Artifacts
+
+- Plan page: https://pablof7z.github.io/awesome-agents/plans/public-builder-profiles-agent-model-cards/
+
+- TTS audio: https://blossom.primal.net/2faa2fde8c6b962e1b629f2fb2e212aa6fd5e2e61b07e89e43c63475e0d8c195.mp3

package/docs/product/README.md

@@ -11,7 +11,8 @@ unless the user confirms them.
 - `product-scope.md`: What `awesome-agents` is for and how it differs from skills.
 - `command-model.md`: Command shape, `npx skills` parity, defaults, and scriptability.
 - `profile-source-format.md`: Source repositories, canonical profiles, adapters, and install sources.
-- `harness-targets.md`: Codex, Claude Code, and OpenCode rendering/target behavior.
+- `site-profiles-and-model-cards.md`: Public builder profiles, agent model cards, GitHub login, and README-backed site content.
+- `harness-targets.md`: Codex, Claude Code, OpenCode, Goose, and tenex-edge rendering/target behavior.
 - `safety-and-publishing.md`: Install safety, registry behavior, verification, and npm/GitHub publish state.
 - `open-questions.md`: Unresolved product questions.
 

package/docs/product/command-model.md

@@ -24,9 +24,9 @@ The CLI supports:
   language such as `npx awesome-agents add owner/repo --agent triage-agent`.
 - `--profile <slug>` to select profiles explicitly.
 - `--skill <slug>` as a compatibility alias, even though the artifact is a profile.
-- `--harness <codex|claude-code|opencode|*>` to select target harnesses.
-- `--agent <codex|claude-code|opencode|*>` remains accepted as a legacy harness
-  selector when the value is a known harness or harness alias.
+- `--harness <codex|claude-code|opencode|goose|tenex-edge|*>` to select target harnesses.
+- `--agent <codex|claude-code|opencode|goose|tenex-edge|*>` remains accepted as a
+  legacy harness selector when the value is a known harness or harness alias.
 - `--all` to install every profile.
 - `--list` to inspect source profiles before installing.
 
@@ -36,16 +36,17 @@ Accepted implementation decision:
 
 - Install scope defaults to project where the target harness supports project-local profiles.
 - Codex is an exception because `codex --profile <name>` loads
-  `$CODEX_HOME/<name>.config.toml`. Codex profile installs should use that
-  user-level config-layer target.
+  `$CODEX_HOME/<name>.config.toml`. tenex-edge is also global because invitable
+  local agents live under `$TENEX_EDGE_HOME/agents/` or `~/.tenex-edge/agents/`.
 - When no `--harness` or legacy harness-valued `--agent` is provided, the CLI
-  installs to every supported harness whose CLI is detected on `PATH` (checks
-  for `codex`, `claude`, `opencode`). If none are detected, it falls back to
-  Codex only.
-- `--harness <harness>` (or a harness-valued `--agent`) narrows the install to
-  that single harness, overriding detection.
-- The CLI is noninteractive in the initial scaffold.
-- `--yes` is accepted for command-shape parity, but prompts are not currently required.
+  detects supported harness CLIs on `PATH` (`codex`, `claude`, `opencode`,
+  `goose`, and `tenex-edge`).
+- If one harness is detected, install to it. If multiple harnesses are detected,
+  interactive installs open a checkbox selector with every detected harness
+  selected by default; noninteractive, `--json`, and `--yes` installs use every
+  detected harness.
+- If no harness is detected, fail with a clear message asking for `--harness`.
+- `--harness <harness>` (or a harness-valued `--agent`) overrides detection.
 
 ## Scriptability
 

package/docs/product/harness-targets.md

@@ -9,6 +9,8 @@ Initial harness targets:
 - Codex
 - Claude Code
 - OpenCode
+- Goose
+- tenex-edge
 
 ## Codex
 
@@ -53,8 +55,55 @@ Generated OpenCode agents install to:
 
 OpenCode output is Markdown with frontmatter and a generated marker.
 
+## Goose
+
+Generated Goose custom agents install to:
+
+- Project: `.agents/agents/<profile>.md`
+- Global: `$GOOSE_HOME/agents/<profile>.md`, or `~/.agents/agents/<profile>.md`
+
+Run with:
+
+```bash
+goose session
+```
+
+Then invoke the agent by name in the chat session:
+
+```
+@<profile>
+```
+
+Goose output is Markdown with YAML frontmatter (`name`, `description`, optional
+`model`) and a generated marker. The agent body reuses the Claude Code adapter
+when a Goose-specific adapter is not present.
+
+## tenex-edge
+
+Generated tenex-edge agents install to:
+
+- Project: not supported; tenex-edge agents are machine-local
+- Global: `$TENEX_EDGE_HOME/agents/<profile>.json`, or `~/.tenex-edge/agents/<profile>.json`
+
+Run with:
+
+```bash
+tenex-edge launch <profile>
+```
+
+The generated JSON is a tenex-edge local agent keystore entry with:
+
+- a generated Nostr keypair, preserved across reinstalls
+- `commands` entries with launch argv that load the installed profile, such as
+  `codex --profile <profile>` or `claude --agent <profile>`
+- an inline Claude `agent` definition passed by tenex-edge as `--agents` for
+  the generated fallback command when no Claude Code profile command is present
+- a byline derived from the profile summary
+
 ## Adapter Gaps
 
 Some source repositories may provide Codex adapters first. Claude Code and
 OpenCode use generated defaults unless a source repository adds native adapters
-for those harnesses.
+for those harnesses. Goose reuses the Claude Code adapter when no Goose-specific
+adapter is present. tenex-edge uses a native adapter when present, otherwise it
+reuses the Claude Code adapter before falling back to the base profile.

package/docs/product/open-questions.md

@@ -14,6 +14,12 @@ These are unresolved product questions for `awesome-agents`.
 - Should remote installs record commit pins or lockfiles for reproducible updates?
 - Should there eventually be a registry or curated index of profile sources?
 
+## Site And Identity
+
+- Should public builder handles always begin as GitHub usernames, or should
+  custom handles be supported from the start?
+- What moderation or spam controls should be added after real review volume?
+
 ## Harness Support
 
 - Should future versions also support Codex custom-agent files in addition to

package/docs/product/product-scope.md

@@ -9,7 +9,7 @@ These notes capture what `awesome-agents` is and why it exists.
 - Its command structure should mirror `npx skills`, but for agent profiles.
 - It should install profiles from any explicit source repository that follows
   the `agents/<slug>/agent.yaml` source layout.
-- Initial harness targets are Codex, Claude Code, and OpenCode.
+- Harness targets are Codex, Claude Code, OpenCode, Goose, and tenex-edge.
 - The package should be published after the scaffold works.
 
 ## Product Boundary
@@ -42,6 +42,6 @@ Product correction:
   source resolution itself.
 - Source repositories should use one agent definition format per agent directory:
   `agents/<slug>/agent.yaml` plus colocated support material.
-- `awesome-agents` installs that local support material into
-  `~/.agents/homes/<slug>/` and transcribes the agent definition to the target
-  harness.
+- `awesome-agents` installs local support material and declared immediately
+  relevant skills into `~/.agents/homes/<slug>/` and transcribes the agent
+  definition to the target harness.

package/docs/product/profile-source-format.md

@@ -10,6 +10,8 @@ The source format is intentionally repo-neutral:
 agents/
   <profile>/
     agent.yaml
+    README.md  # optional site model-card body
+    skills/
     scripts/
     references/
 ```
@@ -27,6 +29,31 @@ agents/<profile>/scripts/*
 agents/<profile>/references/*
 ```
 
+Optional site-facing documentation lives at:
+
+```text
+agents/<profile>/README.md
+```
+
+This README is intended for the public model-card page on
+`awesome-agents.com/<handle>/<repo>/<profile>`. It complements the runtime
+profile definition; it should not be treated as the installable prompt. It is
+not required for a valid source profile.
+
+Immediately relevant skills can be declared in the profile definition:
+
+```yaml
+skills:
+  - gh-pages-publisher
+  - pablof7z/tenex-edge basic-skill
+```
+
+Bare skill names resolve from the profile directory, then the source checkout,
+then from `~/.agents/skills`. Source-qualified entries use the same source plus
+skill selector shape as `npx skills add <source> --skill <skill>`. Installed
+skills are copied into `~/.agents/homes/<profile>/skills/<skill>` and appended
+to the rendered agent prompt with complete paths.
+
 ## Profile Files
 
 YAML profile files are preferred. The loader should support a pragmatic subset
@@ -43,6 +70,8 @@ The CLI should preserve canonical profile content and generate harness-specific
 Agent-owned scripts and references should be installed into
 `~/.agents/homes/<profile>/scripts` and
 `~/.agents/homes/<profile>/references`.
+Declared skills should be installed into
+`~/.agents/homes/<profile>/skills/<skill>`.
 
 Profile source files are intentionally under `agents/`, not `skills/`, because
 the source format models agent profiles separately from loadable skills.

package/docs/product/site-profiles-and-model-cards.md

@@ -0,0 +1,135 @@
+# Site Profiles And Model Cards
+
+These notes capture the requested direction for the public
+`awesome-agents.com` experience.
+
+## Core Direction
+
+The site should become a social profile and discovery index for people who
+build with agent fleets, not only a static CLI directory.
+
+Primary route shape:
+
+```text
+awesome-agents.com/<handle>
+awesome-agents.com/<handle>/<repo>/<agent-slug>
+```
+
+`/<handle>` is a builder profile: a public place to show the operator behind the
+agents. It should include owned profiles, agent fleets, source repos, installs,
+shipped examples, reviews, and activity.
+
+This page should feel closer to a GitHub profile than a landing page. The core
+content is profile information: about details, connected repos, agent templates,
+recent activity, artifacts created with specific fleets, reviews,
+discussion/forum participation, and cross-references between builders, agents,
+and artifacts.
+
+`/<handle>/<repo>/<agent-slug>` is an agent template page, comparable to a
+Hugging Face model card. It should show what the agent is, why it exists, how to
+install it, where its source lives, and what other users say about it.
+
+This page should feel closer to a repository page than a marketing page. Users
+should be able to inspect the template, install or download it, eventually fork
+it, comment on it, review it, and see artifacts shared by other builders who
+used or adapted the agent.
+
+Profile and model-card navigation should be route-backed subpages, not in-page
+anchor tabs. For example:
+
+```text
+awesome-agents.com/<handle>/agents
+awesome-agents.com/<handle>/artifacts
+awesome-agents.com/<handle>/activity
+awesome-agents.com/<handle>/<repo>/<agent-slug>/reviews
+awesome-agents.com/<handle>/<repo>/<agent-slug>/forks
+```
+
+## Agent Model Card Source
+
+Agent source repositories should support optional site-facing README content
+next to the runtime profile definition:
+
+```text
+agents/
+  <agent-slug>/
+    agent.yaml
+    README.md  # optional site model-card body
+    scripts/
+    references/
+```
+
+`agents/<agent-slug>/README.md` is not required. When present, it is the
+canonical source for the public model-card body on the site. It complements
+`agent.yaml`; it is not the runtime prompt. The YAML profile remains the
+installable agent definition, while the README can explain intended use,
+operating model, examples, limitations, changelog notes, and other human-facing
+documentation.
+
+The site should render this README on the model-card route when it exists:
+
+```text
+awesome-agents.com/<handle>/<repo>/<agent-slug>
+```
+
+When no README exists, the site should still allow the agent page and generate a
+fallback model card from `agent.yaml` metadata and profile content.
+
+## Identity And Login
+
+GitHub login is the preferred starting point.
+
+Initial identity assumptions:
+
+- The public handle can default to the GitHub username.
+- Requested GitHub OAuth access should be limited to basic user profile and
+  email address information, such as `read:user` plus `user:email`.
+- GitHub auth can verify repo ownership and let builders claim/import agent
+  source repositories.
+- Repo and agent routes should be derived from GitHub ownership plus the
+  `agents/<agent-slug>/` layout.
+- Reviews should require a logged-in identity.
+- Public handle claims are first-come-first-served.
+
+## Social Surface
+
+Builder profiles should make agent operation legible and impressive without
+turning into a conventional resume page.
+
+Useful signals:
+
+- published agent templates;
+- repos connected to the builder;
+- recent activity related to agent work;
+- artifacts the builder publishes, including which fleet produced them;
+- fleet or team size where the builder chooses to disclose it;
+- installs, stars, reviews, and shipped samples;
+- badges for verified GitHub ownership or claimed source repos;
+- featured agents and examples of work produced with them;
+- discussion/forum participation that can reference builders, repos, agents,
+  and artifacts.
+
+Useful profile metrics:
+
+- agent templates published or maintained;
+- installs across templates and source repos;
+- forks, remixes, and adaptations by other builders;
+- artifacts shipped with explicit fleet tags;
+- average review score from logged-in users;
+- discussion karma or useful answers;
+- verified source ownership and verified artifact links.
+
+Agent model cards should support reviews and reputation signals so users can
+judge an agent before installing it.
+
+The first release should not include spam filtering for reviews. Reviews can
+ship with logged-in identity as the baseline constraint, then add moderation
+controls only after there is real usage pressure.
+
+## Open Questions
+
+- Which metrics are verified by the platform versus self-reported by builders?
+- Should custom handles be supported at launch, or should the first version use
+  GitHub usernames only?
+- What later moderation or spam controls are needed once real review volume
+  exists?