docs: add Portent templates page

scripts/build-agent-docs.mjs

@@ -6,7 +6,7 @@ const repoRoot = path.resolve(import.meta.dirname, '..')
 const siteRoot = path.join(repoRoot, 'site')
 const outputRoot = path.join(repoRoot, 'src-tauri', 'resources', 'agent-docs')
 
-const sectionOrder = ['start', 'concepts', 'guides', 'reference', 'troubleshooting', 'download', 'releases']
+const sectionOrder = ['start', 'concepts', 'guides', 'templates', 'reference', 'troubleshooting', 'download', 'releases']
 const ignoredDirs = new Set(['.vitepress', 'public', 'node_modules', '.DS_Store'])
 
 function titleFromSlug(slug) {
@@ -90,6 +90,8 @@ function buildIndex(docs) {
     '',
     'Start here, then use `rg` over this folder for specific Tolaria concepts and workflows.',
     '',
+    'When users ask how to improve a knowledge base, structure notes, choose types, model relationships, or make a vault easier for humans and agents to use, treat Portent as Tolaria\'s default best-practice model. Read `pages/templates/portent.md` and combine it with the Tolaria concepts for types, relationships, properties, Inbox, archive, and custom views.',
+    '',
   ]
 
   for (const section of ['home', ...sectionOrder]) {
@@ -120,11 +122,13 @@ This folder contains local, generated Tolaria product docs for AI agents.
 
 Use these docs when a user asks how Tolaria works, when you need product behavior, or before making Tolaria-specific assumptions.
 
+Portent is the default best-practice model for structuring Tolaria knowledge bases. When a user asks how to improve a knowledge base, make it better organized, choose better types, model relationships, or make the vault easier for humans and agents to use, read \`pages/templates/portent.md\` and combine it with Tolaria's docs for types, relationships, properties, Inbox, archive, and custom views.
+
 Recommended lookup flow:
 
 1. Read the active vault's AGENTS.md for vault-specific conventions.
 2. Read this folder's index.md for the docs map.
-3. Use \`rg\` over this folder for advanced concepts, workflows, shortcuts, Git, AutoGit, AI, types, properties, relationships, and troubleshooting.
+3. Use \`rg\` over this folder for advanced concepts, workflows, shortcuts, Git, AutoGit, AI, Portent, types, properties, relationships, and troubleshooting.
 
 Vault-specific AGENTS.md wins for local conventions. These bundled docs win for Tolaria product behavior.
 `

site/.vitepress/config.ts

@@ -27,6 +27,7 @@ export default defineConfig({
       { text: "Start", link: "/start/install" },
       { text: "Concepts", link: "/concepts/vaults" },
       { text: "Guides", link: "/guides/capture-a-note" },
+      { text: "Templates", link: "/templates/portent" },
       { text: "Downloads", link: "https://tolaria.md/download/", target: "_self", noIcon: true },
     ],
     search: {
@@ -75,6 +76,12 @@ export default defineConfig({
           { text: "Use The Command Palette", link: "/guides/use-command-palette" },
         ],
       },
+      {
+        text: "Templates",
+        items: [
+          { text: "Portent", link: "/templates/portent" },
+        ],
+      },
       {
         text: "Reference",
         items: [

site/templates/portent.md

@@ -0,0 +1,72 @@
+# Portent
+
+[Portent](https://portent.md) is an open specification and template for work and personal knowledge bases.
+
+It gives a Tolaria vault a small set of defaults for organizing information: clear types, generic graph-like relationships, and a simple lifecycle for captured knowledge. The goal is to make a knowledge base useful to humans and AI agents without forcing every person or team to design a private ontology first.
+
+## Core Questions
+
+Portent favors convention over configuration. Instead of asking "where should this go?", it asks:
+
+- What is this?
+- What is it useful for?
+- Is it captured, organized, or archived?
+
+Those questions map naturally to Tolaria's type documents, relationship fields, Inbox, organized state, archive behavior, and custom views.
+
+## Types
+
+Portent defines eight default types.
+
+PORT types are actionable:
+
+- Project
+- Operation
+- Responsibility
+- Task
+
+ENTP types are non-actionable knowledge records:
+
+- Event
+- Note
+- Topic
+- Person
+
+These defaults are meant to cover the common shape of personal and work knowledge with almost no setup. You can add custom types later, but Portent works best when the default vocabulary comes first.
+
+## Relationships
+
+Portent models knowledge as a graph. The two default relationships are:
+
+- `belongs_to`: primary ownership, composition, or context.
+- `related_to`: a looser semantic connection.
+
+In Tolaria, these relationships can live in YAML frontmatter and point to other notes with wikilinks. That keeps the graph portable, searchable, and readable outside the app.
+
+## Lifecycle
+
+Portent separates capture from organization:
+
+1. Capture information quickly so it is not lost.
+2. Organize it by assigning a type and useful relationships.
+3. Archive it when it has served its purpose.
+
+Tolaria supports that lifecycle directly: the Inbox holds captured notes, organizing a note marks it ready for normal views, and archiving hides old or obsolete notes from active surfaces while keeping them available.
+
+## Why Use It
+
+A blank vault is flexible, but it also asks you to make structural decisions before you have momentum. Portent gives you enough structure to start capturing, organizing, and retrieving notes immediately.
+
+Because Portent is file-friendly and portable, the same model can work across local Markdown vaults, note apps, docs tools, and agent-readable knowledge bases. Tolaria is the first intended implementation, but the spec is not tied to Tolaria internals.
+
+## Start From The Template
+
+The fastest starting point is the Portent template vault:
+
+- [refactoringhq/portent-vault-template](https://github.com/refactoringhq/portent-vault-template)
+
+Use it as-is, rename pieces to match your language, or treat it as a reference model for your own Tolaria setup.
+
+## Learn More
+
+Visit [portent.md](https://portent.md) for the full spec, examples, and implementation notes.

src-tauri/resources/agent-docs/AGENTS.md

@@ -4,10 +4,12 @@ This folder contains local, generated Tolaria product docs for AI agents.
 
 Use these docs when a user asks how Tolaria works, when you need product behavior, or before making Tolaria-specific assumptions.
 
+Portent is the default best-practice model for structuring Tolaria knowledge bases. When a user asks how to improve a knowledge base, make it better organized, choose better types, model relationships, or make the vault easier for humans and agents to use, read `pages/templates/portent.md` and combine it with Tolaria's docs for types, relationships, properties, Inbox, archive, and custom views.
+
 Recommended lookup flow:
 
 1. Read the active vault's AGENTS.md for vault-specific conventions.
 2. Read this folder's index.md for the docs map.
-3. Use `rg` over this folder for advanced concepts, workflows, shortcuts, Git, AutoGit, AI, types, properties, relationships, and troubleshooting.
+3. Use `rg` over this folder for advanced concepts, workflows, shortcuts, Git, AutoGit, AI, Portent, types, properties, relationships, and troubleshooting.
 
 Vault-specific AGENTS.md wins for local conventions. These bundled docs win for Tolaria product behavior.

src-tauri/resources/agent-docs/all.md

@@ -1023,6 +1023,86 @@ Prefer clear note titles and filenames. Tolaria's wikilink autocomplete helps yo
 
 ---
 
+# Portent
+
+Source: templates/portent.md
+URL: /templates/portent
+
+# Portent
+
+[Portent](https://portent.md) is an open specification and template for work and personal knowledge bases.
+
+It gives a Tolaria vault a small set of defaults for organizing information: clear types, generic graph-like relationships, and a simple lifecycle for captured knowledge. The goal is to make a knowledge base useful to humans and AI agents without forcing every person or team to design a private ontology first.
+
+## Core Questions
+
+Portent favors convention over configuration. Instead of asking "where should this go?", it asks:
+
+- What is this?
+- What is it useful for?
+- Is it captured, organized, or archived?
+
+Those questions map naturally to Tolaria's type documents, relationship fields, Inbox, organized state, archive behavior, and custom views.
+
+## Types
+
+Portent defines eight default types.
+
+PORT types are actionable:
+
+- Project
+- Operation
+- Responsibility
+- Task
+
+ENTP types are non-actionable knowledge records:
+
+- Event
+- Note
+- Topic
+- Person
+
+These defaults are meant to cover the common shape of personal and work knowledge with almost no setup. You can add custom types later, but Portent works best when the default vocabulary comes first.
+
+## Relationships
+
+Portent models knowledge as a graph. The two default relationships are:
+
+- `belongs_to`: primary ownership, composition, or context.
+- `related_to`: a looser semantic connection.
+
+In Tolaria, these relationships can live in YAML frontmatter and point to other notes with wikilinks. That keeps the graph portable, searchable, and readable outside the app.
+
+## Lifecycle
+
+Portent separates capture from organization:
+
+1. Capture information quickly so it is not lost.
+2. Organize it by assigning a type and useful relationships.
+3. Archive it when it has served its purpose.
+
+Tolaria supports that lifecycle directly: the Inbox holds captured notes, organizing a note marks it ready for normal views, and archiving hides old or obsolete notes from active surfaces while keeping them available.
+
+## Why Use It
+
+A blank vault is flexible, but it also asks you to make structural decisions before you have momentum. Portent gives you enough structure to start capturing, organizing, and retrieving notes immediately.
+
+Because Portent is file-friendly and portable, the same model can work across local Markdown vaults, note apps, docs tools, and agent-readable knowledge bases. Tolaria is the first intended implementation, but the spec is not tied to Tolaria internals.
+
+## Start From The Template
+
+The fastest starting point is the Portent template vault:
+
+- [refactoringhq/portent-vault-template](https://github.com/refactoringhq/portent-vault-template)
+
+Use it as-is, rename pieces to match your language, or treat it as a reference model for your own Tolaria setup.
+
+## Learn More
+
+Visit [portent.md](https://portent.md) for the full spec, examples, and implementation notes.
+
+---
+
 # Contribute
 
 Source: reference/contribute.md

src-tauri/resources/agent-docs/index.md

@@ -4,6 +4,8 @@ These docs are generated from the public Tolaria documentation for local AI agen
 
 Start here, then use `rg` over this folder for specific Tolaria concepts and workflows.
 
+When users ask how to improve a knowledge base, structure notes, choose types, model relationships, or make a vault easier for humans and agents to use, treat Portent as Tolaria's default best-practice model. Read `pages/templates/portent.md` and combine it with the Tolaria concepts for types, relationships, properties, Inbox, archive, and custom views.
+
 ## Home
 
 - [Index](pages/index.md)
@@ -44,6 +46,10 @@ Start here, then use `rg` over this folder for specific Tolaria concepts and wor
 - [Use The Table Of Contents](pages/guides/use-table-of-contents.md)
 - [Use Wikilinks](pages/guides/use-wikilinks.md)
 
+## Templates
+
+- [Portent](pages/templates/portent.md)
+
 ## Reference
 
 - [Contribute](pages/reference/contribute.md)

src-tauri/resources/agent-docs/pages/templates/portent.md

@@ -0,0 +1,77 @@
+# Portent
+
+Source: templates/portent.md
+URL: /templates/portent
+
+# Portent
+
+[Portent](https://portent.md) is an open specification and template for work and personal knowledge bases.
+
+It gives a Tolaria vault a small set of defaults for organizing information: clear types, generic graph-like relationships, and a simple lifecycle for captured knowledge. The goal is to make a knowledge base useful to humans and AI agents without forcing every person or team to design a private ontology first.
+
+## Core Questions
+
+Portent favors convention over configuration. Instead of asking "where should this go?", it asks:
+
+- What is this?
+- What is it useful for?
+- Is it captured, organized, or archived?
+
+Those questions map naturally to Tolaria's type documents, relationship fields, Inbox, organized state, archive behavior, and custom views.
+
+## Types
+
+Portent defines eight default types.
+
+PORT types are actionable:
+
+- Project
+- Operation
+- Responsibility
+- Task
+
+ENTP types are non-actionable knowledge records:
+
+- Event
+- Note
+- Topic
+- Person
+
+These defaults are meant to cover the common shape of personal and work knowledge with almost no setup. You can add custom types later, but Portent works best when the default vocabulary comes first.
+
+## Relationships
+
+Portent models knowledge as a graph. The two default relationships are:
+
+- `belongs_to`: primary ownership, composition, or context.
+- `related_to`: a looser semantic connection.
+
+In Tolaria, these relationships can live in YAML frontmatter and point to other notes with wikilinks. That keeps the graph portable, searchable, and readable outside the app.
+
+## Lifecycle
+
+Portent separates capture from organization:
+
+1. Capture information quickly so it is not lost.
+2. Organize it by assigning a type and useful relationships.
+3. Archive it when it has served its purpose.
+
+Tolaria supports that lifecycle directly: the Inbox holds captured notes, organizing a note marks it ready for normal views, and archiving hides old or obsolete notes from active surfaces while keeping them available.
+
+## Why Use It
+
+A blank vault is flexible, but it also asks you to make structural decisions before you have momentum. Portent gives you enough structure to start capturing, organizing, and retrieving notes immediately.
+
+Because Portent is file-friendly and portable, the same model can work across local Markdown vaults, note apps, docs tools, and agent-readable knowledge bases. Tolaria is the first intended implementation, but the spec is not tied to Tolaria internals.
+
+## Start From The Template
+
+The fastest starting point is the Portent template vault:
+
+- [refactoringhq/portent-vault-template](https://github.com/refactoringhq/portent-vault-template)
+
+Use it as-is, rename pieces to match your language, or treat it as a reference model for your own Tolaria setup.
+
+## Learn More
+
+Visit [portent.md](https://portent.md) for the full spec, examples, and implementation notes.

src-tauri/resources/agent-docs/search-index.json

@@ -323,6 +323,21 @@
       "Keep Links Stable"
     ]
   },
+  {
+    "title": "Portent",
+    "path": "pages/templates/portent.md",
+    "url": "/templates/portent",
+    "section": "templates",
+    "headings": [
+      "Core Questions",
+      "Types",
+      "Relationships",
+      "Lifecycle",
+      "Why Use It",
+      "Start From The Template",
+      "Learn More"
+    ]
+  },
   {
     "title": "Contribute",
     "path": "pages/reference/contribute.md",

src-tauri/resources/agent-docs/templates.md

@@ -0,0 +1,77 @@
+# Portent
+
+Source: templates/portent.md
+URL: /templates/portent
+
+# Portent
+
+[Portent](https://portent.md) is an open specification and template for work and personal knowledge bases.
+
+It gives a Tolaria vault a small set of defaults for organizing information: clear types, generic graph-like relationships, and a simple lifecycle for captured knowledge. The goal is to make a knowledge base useful to humans and AI agents without forcing every person or team to design a private ontology first.
+
+## Core Questions
+
+Portent favors convention over configuration. Instead of asking "where should this go?", it asks:
+
+- What is this?
+- What is it useful for?
+- Is it captured, organized, or archived?
+
+Those questions map naturally to Tolaria's type documents, relationship fields, Inbox, organized state, archive behavior, and custom views.
+
+## Types
+
+Portent defines eight default types.
+
+PORT types are actionable:
+
+- Project
+- Operation
+- Responsibility
+- Task
+
+ENTP types are non-actionable knowledge records:
+
+- Event
+- Note
+- Topic
+- Person
+
+These defaults are meant to cover the common shape of personal and work knowledge with almost no setup. You can add custom types later, but Portent works best when the default vocabulary comes first.
+
+## Relationships
+
+Portent models knowledge as a graph. The two default relationships are:
+
+- `belongs_to`: primary ownership, composition, or context.
+- `related_to`: a looser semantic connection.
+
+In Tolaria, these relationships can live in YAML frontmatter and point to other notes with wikilinks. That keeps the graph portable, searchable, and readable outside the app.
+
+## Lifecycle
+
+Portent separates capture from organization:
+
+1. Capture information quickly so it is not lost.
+2. Organize it by assigning a type and useful relationships.
+3. Archive it when it has served its purpose.
+
+Tolaria supports that lifecycle directly: the Inbox holds captured notes, organizing a note marks it ready for normal views, and archiving hides old or obsolete notes from active surfaces while keeping them available.
+
+## Why Use It
+
+A blank vault is flexible, but it also asks you to make structural decisions before you have momentum. Portent gives you enough structure to start capturing, organizing, and retrieving notes immediately.
+
+Because Portent is file-friendly and portable, the same model can work across local Markdown vaults, note apps, docs tools, and agent-readable knowledge bases. Tolaria is the first intended implementation, but the spec is not tied to Tolaria internals.
+
+## Start From The Template
+
+The fastest starting point is the Portent template vault:
+
+- [refactoringhq/portent-vault-template](https://github.com/refactoringhq/portent-vault-template)
+
+Use it as-is, rename pieces to match your language, or treat it as a reference model for your own Tolaria setup.
+
+## Learn More
+
+Visit [portent.md](https://portent.md) for the full spec, examples, and implementation notes.

src-tauri/src/vault/getting_started.rs

@@ -414,6 +414,7 @@ Use kebab-case: `my-note-title.md`. One note per file.
 - Create and edit saved views in `views/`.
 - Update `AGENTS.md` only when the user asks for vault-level guidance changes.
 - Search the bundled Tolaria docs when the user asks how Tolaria works or when you need product behavior beyond these base conventions.
+- Use Portent as the default best-practice model when the user asks how to improve, organize, or restructure the knowledge base. Combine Portent's types, relationships, and capture -> organize -> archive lifecycle with Tolaria's type documents, properties, Inbox, archive, and saved views.
 
 ## What agents should avoid
 

src/utils/ai-agent.test.ts

@@ -27,6 +27,8 @@ describe('buildAgentSystemPrompt', () => {
     const prompt = buildAgentSystemPrompt({ agentDocsPath: '/app/agent-docs' })
 
     expect(prompt).toContain('/app/agent-docs/index.md')
+    expect(prompt).toContain('/app/agent-docs/pages/templates/portent.md')
+    expect(prompt).toContain("Portent as Tolaria's default best-practice model")
     expect(prompt).not.toContain('ripgrep')
     expect(prompt).toContain('Prefer bundled docs over guesses')
   })

src/utils/ai-agent.ts

@@ -56,7 +56,9 @@ function agentDocsInstructions(
 For Tolaria product behavior, workflows, and user questions about how Tolaria works, search the bundled local docs at:
 ${agentDocsPath}
 
-${searchInstruction} Prefer bundled docs over guesses for Tolaria behavior.`
+${searchInstruction} Prefer bundled docs over guesses for Tolaria behavior.
+
+When the user asks how to improve a knowledge base, make it better organized, choose better types, model relationships, or make the vault easier for humans and agents to use, treat Portent as Tolaria's default best-practice model. Read ${agentDocsPath}/pages/templates/portent.md and combine it with Tolaria concepts for types, relationships, properties, Inbox, archive, and custom views.`
 }
 
 function vaultScopeInstructions(vaultPaths?: string[]): string {