FolioMuse docs

What is FolioMuse?

FolioMuse is a portfolio-building product that helps individual creators and professionals build a portfolio that is genuinely their own. It is not a template marketplace, a cloning service, or a general-purpose website builder.

The core promise: See what works, understand why it works, and get help making your version — not a copy.

The three pillars

Who is FolioMuse for?

What makes FolioMuse different?

Compliance gate

Compliance is evaluated independently from quality. It checks whether the item meets FolioMuse’s binding rules around consent, attribution, and originality.

Mandatory compliance checks

1. Attribution completeness (R3): creatorName, sourceUrl, licenseType, and consentDate must all be present and non-empty.
2. Consent validity (R4): a ConsentRecord must exist with tier ≥ DISPLAY. The consentedBy field must identify a real entity.
3. No cross-creator cloning:the item must not be a structural copy of another creator’s item with attribution changed.
4. No fabricated credibility: the item must not present AI-generated content as verified real-world claims.
5. Attribution integrity under processing: attribution metadata must remain intact through any retrieval or embedding pipeline.

Acceptance criteria

An item is accepted into the gallery only when all of these conditions are met simultaneously:

1. Quality ≥ L2 (Adequate)
2. Compliance = PASS (or FLAG with documented rationale)
3. Consent exists with tier ≥ DISPLAY
4. Attribution is complete (all four fields present)
5. No duplicate detected
6. Coverage gap assessed (informational, does not block)

Filtering & discovery

The gallery supports multiple filtering dimensions, all powered by server-computed facet counts:

Attribution

Every gallery item carries attribution metadata that is immutable — it can never be stripped, modified, or hidden. Attribution includes:

• Creator name: the person or organization who created the portfolio.
• Source URL: the original location of the portfolio.
• License type: the terms under which the portfolio is displayed.
• Consent date: when consent was granted for gallery inclusion.

Consent & revocation

No third-party portfolio content enters the gallery without explicit consent. Consent is recorded with:

• Tier: DISPLAY, PATTERN_DERIVE, or FULL.
• Consented by: who granted consent (individual or organization).
• Consented at: when consent was granted.
• Terms: the specific terms of the consent.

Creators can revoke consent at any time. When consent is revoked, the item is archived immediately and excluded from all active queries.

Staleness policy

Gallery items can become stale over time. A portfolio from 2020 may no longer represent current design patterns.

• Threshold: 18 months since last review with no re-validation.
• Action: item is archived (status → ARCHIVED), not deleted.
• Resubmission: archived items can be resubmitted if content has been materially updated.

MCP Agent overview

The FolioMuse MCP agent is an AI assistant that helps you build, edit, and refine your portfolio through natural-language conversation. It connects via the Model Context Protocol (MCP).

The agent is nota chatbot that generates generic content. It’s a specialized tool that understands portfolio structure, analyzes patterns across real examples, and helps you improve your own work.

How the agent works

1. Pattern analysis: the agent analyzes patterns across multiple gallery examples (minimum 3) to understand what works in your field.
2. Feedback generation: based on those patterns, it gives you structural and content feedback scoped to specific sections.
3. Content refinement: it helps you refine your own draft — reordering, tightening, sharpening — never writing from scratch.
4. Edit tracking: every change the agent makes is marked in your edit history, distinguishable from your own edits.

Example conversation

Safety rules

Available tools

The MCP agent exposes these tools (all respect safe projection rules — no full-content fetch):

Code examples

const res = await fetch("/api/gallery/random");
const { id } = await res.json();
window.location.href = `/gallery/${id}`;

const res = await fetch(
  "/api/gallery/summaries?role=Front-end%20Developer&pageSize=10"
);
const { items, total } = await res.json();
console.log(`Found ${total} portfolios`);
items.forEach(item => {
  console.log(item.title, item.attribution.creatorName);
});

const res = await fetch("/api/gallery/facets");
const { facets } = await res.json();

// facets.roles: [{ value: "Designer", count: 15 }, ...]
// facets.styles: [{ value: "minimal", count: 8 }, ...]
facets.roles.forEach(r => console.log(`${r.value}: ${r.count}`));

Safe projection rules

• No full-content fetch (ADR-0001): the API never returns raw content blobs.
• Aggregated patterns only (R2): only patterns across N ≥ 3 items.
• User content only (R5): only user-authored or pattern-synthesized content.
• Attribution always included (R3): every response includes attribution metadata.

GET /api/gallery/summaries

Paginated gallery items with server-side filtering and sorting. This is the primary endpoint for browsing the gallery.

GET /api/gallery/summaries?q=react&role=Developer&sort=quality&pageSize=10

Response: {
  "items": [GalleryItemSummary, ...],
  "total": 42,
  "page": 1,
  "pageSize": 10
}

GET /api/gallery/facets

Facet counts for building filter UIs. Returns counts for roles, styles, stacks, qualities, consents, and total portfolio count.

GET /api/gallery/facets

Response: {
  "facets": {
    "total": 42,
    "roles": [{ "value": "Designer", "count": 15 }, ...],
    "styles": [{ "value": "minimal", "count": 8 }, ...],
    "stacks": [{ "value": "React", "count": 12 }, ...],
    "qualities": [{ "value": "L3", "count": 10 }, ...],
    "consents": [{ "value": "FULL", "count": 30 }, ...]
  }
}

GET /api/gallery/random

Returns a random accepted portfolio ID. Use this for discovery features or “surprise me” buttons.

GET /api/gallery/random

Response: { "id": "clx..." }

// 404 if no accepted portfolios exist
// 500 if gallery is unavailable

GET /api/gallery/items/[id]

Full portfolio detail for a specific item. Includes sections, strengths, stack evidence, and all metadata.

GET /api/gallery/items/clx...

Response: {
  "id": "clx...",
  "title": "Portfolio Title",
  "creatorRole": "Front-end Developer",
  "sections": [...],
  "strengths": [...],
  "stackEvidence": [...],
  ...
}

Query parameters

Response shape

// GalleryItemSummary (returned in /summaries responses)
{
  "id": "clx...",
  "title": "Portfolio Title",
  "creatorRole": "Front-end Developer",
  "styleTags": ["minimal", "editorial"],
  "qualityLevel": "L3",
  "complianceStatus": "PASS",
  "status": "ACCEPTED",
  "attribution": {
    "creatorName": "Jane Doe",
    "sourceUrl": "https://janedoe.com",
    "licenseType": "DISPLAY",
    "consentDate": "2025-01-15T00:00:00.000Z"
  },
  "consentTier": "FULL",
  "reviewedAt": "2025-01-20T00:00:00.000Z",
  "mediaUrl": "https://...",
  "githubUrl": "https://github.com/...",
  "stackTags": ["React", "TypeScript", "Tailwind"]
}