Skip to content

site: split docs into 4 pages, fix nav consistency, add notebook mock #148

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AkashGoenka merged 1 commit into from
Aug 10, 2026
Merged

site: split docs into 4 pages, fix nav consistency, add notebook mock #148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,5 @@
scripts/probe-output/

# Internal design/research docs — kept locally, not tracked
docs/
/docs/
.coldstart/
68 changes: 68 additions & 0 deletions site-astro/src/components/DocsSidebar.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
---
interface Props { active: 'getting-started' | 'navigation' | 'notebook' | 'under-the-hood' }
const { active } = Astro.props;

const groups = [
{
id: 'getting-started', label: 'Getting started', href: '/docs/',
anchors: [
{ href: '#overview', label: 'Overview' },
{ href: '#install', label: 'Install & setup' },
{ href: '#flow', label: 'The intended flow' },
],
},
{
id: 'navigation', label: 'Navigation', href: '/docs/navigation/',
anchors: [
{ href: '#find', label: 'find', code: true },
{ href: '#gs', label: 'gs', code: true },
],
},
{
id: 'notebook', label: 'Notebook', href: '/docs/notebook/',
anchors: [
{ href: '#notebook', label: 'The notebook, in depth' },
{ href: '#kb-search', label: 'kb search', code: true },
{ href: '#kb-lookup', label: 'kb lookup', code: true },
{ href: '#kb-write', label: 'kb write', code: true },
{ href: '#kb-commit', label: 'kb commit', code: true },
{ href: '#kb-view', label: 'kb view', code: true },
{ href: '#kb-maint', label: 'kb status / lint / repair / render', code: true },
{ href: '#sharing', label: 'Sharing with a team' },
],
},
{
id: 'under-the-hood', label: 'Under the hood', href: '/docs/under-the-hood/',
anchors: [
{ href: '#freshness', label: 'How the index stays fresh' },
{ href: '#lifecycle', label: 'Lifecycle commands' },
{ href: '#mcp', label: 'MCP tools' },
{ href: '#semantics', label: 'Bring your own semantics' },
{ href: '#languages', label: 'Supported languages' },
],
},
];
---
<aside class="side">
<button class="side-toggle" id="sideToggle" type="button" aria-expanded="false" aria-controls="sideList">
<span class="chev" aria-hidden="true">&rsaquo;</span> Menu
</button>
<div class="side-list" id="sideList">
{groups.map((g) => (
<div class="side-group">
<a href={g.href} class={`gh gh-link${active === g.id ? ' active' : ''}`}>{g.label}</a>
{active === g.id && (
<>
{g.anchors.map((a) => (
<a href={a.href}>{a.code ? <code>{a.label}</code> : a.label}</a>
))}
</>
)}
</div>
))}
</div>
</aside>
<style>
.gh-link { display: block; text-decoration: none; transition: color .12s; background: none; border-left-color: transparent; }
.gh-link:hover, .gh-link.active { color: var(--frost); opacity: 1; background: none; border-left-color: transparent; }
</style>
10 changes: 6 additions & 4 deletions site-astro/src/components/Nav.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
interface Props { variant?: 'home' | 'docs' | 'blog' | 'how' }
const { variant = 'docs' } = Astro.props;
const installHref = variant === 'home' ? '#install' : '/#install';
---
<div class="progress" id="prog"></div>
<nav>
Expand All @@ -15,10 +14,11 @@ const installHref = variant === 'home' ? '#install' : '/#install';
<a href="/how-it-works/" class={variant === 'how' ? 'active' : ''}>How it works</a>
<a href="/docs/" class={variant === 'docs' ? 'active' : ''}>Docs</a>
<a href="/blog/" class={variant === 'blog' ? 'active' : ''}>Blog</a>
<a href="https://github.com/AkashGoenka/coldstart">GitHub</a>
<a href="https://github.com/AkashGoenka/coldstart" class="nav-icon" aria-label="GitHub">
<svg width="18" height="18" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>
</a>
<a href="https://www.npmjs.com/package/@cstart/coldstart">npm</a>
</div>
<a class="nav-cta" href={installHref}>Install</a>
<button type="button" class="nav-burger" id="nav-burger" aria-label="Open menu" aria-expanded="false" aria-controls="nav-mobile">
<span></span><span></span><span></span>
</button>
Expand All @@ -29,9 +29,11 @@ const installHref = variant === 'home' ? '#install' : '/#install';
<a href="/blog/" class={variant === 'blog' ? 'active' : ''}>Blog</a>
<a href="https://github.com/AkashGoenka/coldstart">GitHub</a>
<a href="https://www.npmjs.com/package/@cstart/coldstart">npm</a>
<a class="nav-cta" href={installHref}>Install →</a>
</div>
</nav>
<style>
.nav-links a.nav-icon{display:inline-flex;align-items:center;}
</style>
<script>
(function(){
var prog = document.getElementById('prog');
Expand Down
2 changes: 1 addition & 1 deletion site-astro/src/content/blog/why-coldstart-makes-zero-llm-calls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ The determinism problem is quieter but I think it matters more for a tool an age

Files already declare their own identity. A filename, the segments of its path, the names it exports. Most of the time, the thing you're looking for is named close to what you'd call it, because someone wrote that name for exactly the reason you're now searching for it: so the next person reading the codebase could find it. coldstart ranks files by how many of your query terms they actually cover, using that declared identity plus a real repo-wide grep pass, backed by ripgrep where it's available, git grep where it isn't.

This is a worse tool than embeddings for a genuinely fuzzy conceptual query, one where nothing in your vocabulary overlaps with anything in the file. I don't think that's a gap worth pretending away. If you want that kind of retrieval, point an embedding-based tool at the same repo. coldstart isn't trying to be the same thing done differently, it's trying to be exact where exactness is available, and honest about the rest.
This is a worse tool than embeddings for a genuinely fuzzy conceptual query, one where nothing in your vocabulary overlaps with anything in the file. I don't think that's a gap worth pretending away. If you want that kind of retrieval, point an embedding-based tool at the same repo. coldstart isn't trying to be the same thing done differently, it's trying to be exact where exactness is available, and honest about the rest. ([More on where that line actually falls.](/vs/vector-rag/))

## Why the tradeoff wins for the common case

Expand Down
Loading
Loading