​

Site Redesign Strategy

This strategy resets the docs site around two deliberately different surfaces:

• a Tremor landing page for narrative orientation
• a knowledge base for stable Paperclip and Tremor reference material

The current site blurs those jobs together. The result is inconsistent framing, uneven information density, and unstable rendering when theatrical or custom layouts leak into the reference shell.

​

Problem Statement

The existing docs experience has three structural issues:

1. the site shell still presents itself as a Paperclip manual while several pages behave like a Tremor-first microsite
2. the knowledge-base pages and the narrative/landing content do not have clear boundary rules
3. fragile presentation layers such as raw HTML islands create rendering drift and make the docs harder to maintain

This is not only a visual problem. It is an information-architecture problem.

​

Target State

The redesigned site should feel like one system with two modes.

​

1. Tremor landing page

The landing page is the front door. It should answer only:

• what Tremor is
• why it exists
• what makes it distinct
• what systems support it
• where to go next

It should be:

• visual
• restrained
• short
• curated
• link-heavy in the right places

It should not become a second wiki, a roster dump, or a raw data appendix.

​

2. Knowledge base

The knowledge base is the manual. It should be:

• markdown-first
• scan-friendly
• stable
• searchable
• low-drama

It should contain:

• Paperclip product framing
• architecture, data model, deploy, API, CLI, and adapter docs
• the Tremor operating appendix and operating corpus links
• reference pages, tables, and diagrams

It should not inherit custom landing-page presentation patterns.

​

Information Architecture

The top-level site should separate surfaces explicitly. Recommended navigation model:

1. Landing The curated Tremor narrative front door.
2. Knowledge Base The manual entrypoint for Paperclip platform and shared reference docs.
3. Operating Corpus The live Tremor operating appendix and control-plane references.
4. Reference surfaces API, deploy, adapters, CLI, architecture records.

The important rule is that landing and manual are different jobs. They can live in one site, but they must not share the same page patterns.

​

Content Boundary Rules

​

Landing page content

Allowed:

• concise studio thesis
• distinctive constraints and product stance
• short explanation of the Paperclip support layer
• curated links into the manual, operating corpus, and project pages

Disallowed:

• giant agent tables
• raw work graph dumps
• operating alerts
• live runtime baseline data
• exhaustive architecture or API reference

​

Knowledge-base content

Allowed:

• conceptual product docs
• control-plane architecture
• deploy and runtime reference
• operating appendix indexes
• tables, diagrams, and role-based guide maps

Disallowed:

• landing-page prose patterns
• promotional hero sections on normal docs pages
• raw HTML microsites as first-class entry pages

​

Technical Direction

​

Docs shell

Use docs/docs.json as the single source of truth for top-level nav and site framing. The shell should:

• present a Tremor-first entry route for the landing page
• expose a plain knowledge-base overview page as the manual entrypoint
• keep the operating corpus and reference sections separate

​

Page primitives

Use:

• plain markdown
• Mermaid for diagrams
• tables for decision and authority surfaces
• a small number of Mintlify cards for navigation

Avoid:

• raw standalone HTML pages for primary entrypoints
• custom CSS islands inside the docs corpus
• decorative sections on manual/reference pages

​

Tremor operating wiki

The operating wiki should remain useful, but it should be entered through markdown pages such as:

• operating/wiki.md
• companies/tremor/wiki/README.md

If companies/tremor/wiki/index.html remains in the repo, it should be a minimal redirect or fallback page, not a standalone styled surface.

​

Visual Direction

​

Landing page

Visual thesis:

Editorial internal brief, not marketing site and not product manual.

Use:

• one dominant visual
• tight copy
• a small number of navigation cards
• calm typography and strong spacing

​

Knowledge base

Visual thesis:

Quiet operator manual.

Use:

• predictable headings
• simple tables
• diagrams where they teach
• minimal card usage

The knowledge base should feel reliable enough that every page can be skimmed in under a minute.

​

Implementation Plan

1. Create a dedicated Tremor landing page in start/.
2. Create a separate knowledge-base overview page in start/.
3. Update docs.json to reflect the split.
4. Reframe existing intro pages so they behave like manual pages rather than homepage stand-ins.
5. Stabilize the operating-wiki entry surfaces and demote raw HTML islands.
6. Verify the config shape and rendered routes.

​

Success Criteria

The redesign is successful when:

• the first page clearly behaves like a landing page
• the knowledge base has a plain overview page that reads like a manual
• the operating corpus remains accessible but no longer feels like the homepage
• no primary docs entry surface depends on a custom standalone HTML island
• the nav makes the split obvious without explanation