agentlab.in v1 spec — locked decisions (canonical)

[harshitsinghbhandari]

agentlab.in — v1 Locked Spec

This is the consolidated, locked v1 spec for agentlab.in — a community publishing platform for AI agent infrastructure knowledge (patterns, playbooks, deep dives), modeled on what Martin Fowler's catalog did for enterprise software patterns, but community-owned and agent-focused.

This thread is the canonical reference. It consolidates every decision from the master question thread (#1) plus the follow-up clarifications. Anything not specified here is deferred or open.

---

1. Auth & Identity

• GitHub OAuth only. Possibly never any other auth method.
• Username = GitHub login. Immutable. agentlab.in/<id> always maps to github.com/<id>. No custom handles, ever. (Impersonation risk: anyone could otherwise name themselves karpathy.)
• Editable profile fields: anything except display-name and username.
• Sign-up gate: GitHub account must be ≥30 days old AND have ≥1 public repo.
• Org accounts allowed and required to be supported (e.g. @anthropic can be an author).

---

2. Content Types & Structure

Three permanent content types. Type is permanent post-publish — copying across types is allowed; in-place conversion is not.

Patterns — soft structure

Prefilled template headings (Problem / Structure / Trade-offs / Related); user can delete them. Otherwise free-form markdown.

Playbooks — hard structure

Four mandatory sections (can be revised later):

1. Environment / Target — what this playbook teaches an agent to operate in
2. Prerequisites — what the agent must already have/know
3. Core Instructions — the actual AGENTS.md-style body
4. Safety / Failure Modes — what to refuse, what to escalate

Deep Dives — 2 mandatory sections at top

1. TL;DR (3–5 lines, the takeaway)
2. The Question (what this deep dive is exploring)

Rest is free-form.

Required fields on every post

• Title
• Body
• Type
• Summary (1-line dek)
• ≥1 Tag

Optional: cover image (URL embed or upload, ≤2MB).

---

3. Writing Experience

• Editor: split-pane markdown (CodeMirror left, live preview right).
• Drafts: saved to browser localStorage only, auto-saved every 30s. Clearing browser cache wipes drafts. No server-side draft persistence in v1. Server-side draft sync is reserved for a future paid tier.
• MDX: supported, but only with an allowlist of components we ship (Callouts, embeds, etc.). No arbitrary React.
• Edit history: track edits, show "edited" timestamp on posts. No public version browser.
• Syntax highlighter: Prism.
• Math (KaTeX): not in v1.
• Mermaid diagrams: yes.
• Image uploads: allowed, max 2MB per image. URL embeds also allowed. Storage = Supabase Storage.
• Slug: auto-generated from title. User cannot edit.

URL structure

agentlab.in/<github-username>/<type>/<slug>

Where <type> ∈ {post, dive, playbook} (singular).

Examples:

• agentlab.in/harshitsinghbhandari/post/trust-gate
• agentlab.in/harshitsinghbhandari/dive/ollama-shaped-problem
• agentlab.in/harshitsinghbhandari/playbook/legacy-university-portals

---

4. Tags & Taxonomy

• Curated tag list. Anyone can submit a new tag; admins approve.
• Nested tags — tag/sub-tag hierarchy supported.
• Max 5 tags per post.
• Tag landing pages: yes (/tag/<slug>).
• Featured/pinned tag starter set: security, local-first, orchestration, memory, evals, tooling, prompting, multi-agent.

---

5. Discoverability

• Homepage layout:
  • Three columns: For You / Playbooks / Deep Dives
  • Plus a mixed heat-ranked feed below
• "For You" algorithm (v1): heat-ranked feed (recency + likes + bookmarks + tag affinity from the user's own posts). Real personalization deferred.
• Search backend: Postgres full-text. (Revisit when post count nears 10k — we won't hit that for 3–4 months minimum.)
• RSS feed: yes.
• Newsletter / email digest: not in v1.
• Sitemap + robots.txt: full indexing.

---

6. Engagement & Social

• Comments: native threaded.
• Reactions: Like only (single heart, Instagram-style).
• Bookmarks: yes — flagship feature.
• Follow authors: yes.
• View counts: shown only to the post author.
• Related posts: automatic, tag-overlap based.
• Cross-references between posts:
  • Authors can write [[Pattern Name]] and have it auto-link to that post's page (wiki-style).
  • Each post page automatically shows a "Referenced by" section listing other posts that link to it (backlinks).

---

7. Moderation & Trust

• Mod model: community flagging + admin (Harshit) adjudicates. Admin can block users and delete posts.
• Report button on posts, comments, and users: yes.
• Content policy: required. Harshit will draft (also drafting Terms of Use, Privacy Policy, and a Support URL — we use GitHub data so privacy matters).
• Author actions: authors can delete their own posts.

Plagiarism / attribution rule

• Distilled posts must credit the original source with a link.
• Post is authored under the distiller's name; the distiller is responsible for the content.
• agentlab.in itself is not responsible for user content. Strong content policy will codify this.

---

8. Bootstrap / Seed Strategy

• Authorship split:
  • Original work → under Harshit's personal GitHub handle (@harshitsinghbhandari)
  • Distilled work → under a dedicated @agentlab curator account
• Pacing: start slow. 1–2 seed posts first, then ramp.

Distillation core policy (Harshit's verbatim)

Allowed: summaries, explanations, critiques, comparisons, architectural breakdowns, "what I learned from", independent reimplementations, short quotations with attribution.

Not allowed: full reposts, excessive copying, paywalled content dumps, entire threads mirrored, raw scraped archives, proprietary leaks.

---

9. Visual Design & Brand

• Theme vibe: Vercel.com — pure black, sharp.
• Both dark and light modes at launch.
• Typography: mono everywhere. Hacker / Berkshire-Hathaway-meets-Vercel aesthetic.
• Logo: skip. Wordmark-only for v1.
• Code block theme: GitHub Dark.

---

10. Profile Pages — /<username>

Shows:

• Avatar + bio from GitHub
• Posts list (filterable: all / patterns / dives / playbooks)
• Linked GitHub repos — auto-fetched, top N by stars
• Pinned posts — user-selected
• Stats: post count, total views, follower count

Username changes: never allowed.

---

11. Technical / Infra

Layer	Choice
Framework	Next.js 14 (App Router)
Auth	NextAuth.js + GitHub OAuth
Database	Supabase (Postgres) — region ap-south-1 (Mumbai)
Image storage	Supabase Storage
Styling	Tailwind CSS
Hosting	Vercel (already connected to agentlab.in)
Analytics	Vercel Analytics
Error tracking	Skip at launch
CI/CD	Vercel previews on every PR
Branching	feature → PR → staging branch → production

---

12. Launch Strategy

• Sign-ups: open immediately at launch. No waitlist, no coming-soon page.
• Build window: ~2 weeks to ship v1 properly.
• Launch channels: Harshit will pick (HN, ProductHunt, Twitter, Composio, Anthropic-adjacent communities) closer to launch.

---

13. Project Governance

• Source code: closed source at start. Open later, not now.
• External code contributions: not accepted at start.
• Content license: CC BY 4.0 (reuse with attribution).

---

14. Monetization

No monetization decisions until 1k DAU. Path TBD then.

---

15. Post-v1 / Noted for Later

• AI-agent-friendly platform layer: great public API endpoints + documentation so agents can read and write agentlab content programmatically. Not v1 scope, but a north-star.
• Pre-launch deliverables Harshit owns: Content Policy, Terms of Use, Privacy Policy, Support URL.
• Server-side draft sync as a paid feature later.
• Real "For You" personalization model later.

---

What's Not in v1 (explicit)

• Email/password auth
• Custom usernames / username changes
• Server-side drafts (localStorage only)
• KaTeX/math rendering
• Newsletter
• Real personalization
• Logo
• Error tracking
• Sponsorships / paid tiers
• Open-source platform code
• External code contributions
• Pre-launch waitlist

---

This thread supersedes the open question state of #1. Any further changes get a comment here so the spec stays one read away.