diff --git a/scripts/build-agent-docs.mjs b/scripts/build-agent-docs.mjs index aab9fe80..55f10e31 100644 --- a/scripts/build-agent-docs.mjs +++ b/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. ` diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index c599eb70..9e9eabcd 100644 --- a/site/.vitepress/config.ts +++ b/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: [ diff --git a/site/templates/portent.md b/site/templates/portent.md new file mode 100644 index 00000000..b2161214 --- /dev/null +++ b/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. diff --git a/src-tauri/resources/agent-docs/AGENTS.md b/src-tauri/resources/agent-docs/AGENTS.md index 44904c3a..a0907762 100644 --- a/src-tauri/resources/agent-docs/AGENTS.md +++ b/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. diff --git a/src-tauri/resources/agent-docs/all.md b/src-tauri/resources/agent-docs/all.md index 58886a47..552c65e6 100644 --- a/src-tauri/resources/agent-docs/all.md +++ b/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 diff --git a/src-tauri/resources/agent-docs/index.md b/src-tauri/resources/agent-docs/index.md index e48916ed..efcb75c6 100644 --- a/src-tauri/resources/agent-docs/index.md +++ b/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) diff --git a/src-tauri/resources/agent-docs/pages/templates/portent.md b/src-tauri/resources/agent-docs/pages/templates/portent.md new file mode 100644 index 00000000..e07e1362 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/src-tauri/resources/agent-docs/search-index.json b/src-tauri/resources/agent-docs/search-index.json index a6ccf1a4..7783add4 100644 --- a/src-tauri/resources/agent-docs/search-index.json +++ b/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", diff --git a/src-tauri/resources/agent-docs/templates.md b/src-tauri/resources/agent-docs/templates.md new file mode 100644 index 00000000..e07e1362 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/src-tauri/src/vault/getting_started.rs b/src-tauri/src/vault/getting_started.rs index a21f203f..5951bed0 100644 --- a/src-tauri/src/vault/getting_started.rs +++ b/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 diff --git a/src/utils/ai-agent.test.ts b/src/utils/ai-agent.test.ts index 038284b3..65c9f1b9 100644 --- a/src/utils/ai-agent.test.ts +++ b/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') }) diff --git a/src/utils/ai-agent.ts b/src/utils/ai-agent.ts index 3a10ef4b..2e4d1990 100644 --- a/src/utils/ai-agent.ts +++ b/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 {