diff --git a/.github/workflows/pages-preview.yml b/.github/workflows/pages-preview.yml index f2b415a..615a006 100644 --- a/.github/workflows/pages-preview.yml +++ b/.github/workflows/pages-preview.yml @@ -83,8 +83,33 @@ jobs: timeout-minutes: 15 environment: name: preview - url: ${{ steps.pages.outputs.pages-deployment-alias-url }} + deployment: false steps: + - name: Create the exact pull-request deployment + id: deployment + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + env: + PREVIEW_HEAD_SHA: ${{ needs.identity.outputs.head_sha }} + with: + script: | + const { data: deployment } = await github.rest.repos.createDeployment({ + ...context.repo, + ref: process.env.PREVIEW_HEAD_SHA, + environment: 'preview', + auto_merge: false, + required_contexts: [], + transient_environment: true, + production_environment: false, + description: 'Cloudflare Pages pull-request preview', + }) + core.setOutput('deployment_id', String(deployment.id)) + await github.rest.repos.createDeploymentStatus({ + ...context.repo, + deployment_id: deployment.id, + state: 'in_progress', + log_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`, + }) + - name: Mark the pull-request preview pending uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 env: @@ -159,6 +184,24 @@ jobs: CLOUDFLARE_PAGES_DEPLOYMENT_URL: ${{ steps.pages.outputs.pages-deployment-alias-url }} INKCRE_PAGES_SMOKE_MODE: preview + - name: Report the exact pull-request deployment + if: ${{ always() && steps.deployment.outputs.deployment_id != '' }} + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + env: + DEPLOYMENT_ID: ${{ steps.deployment.outputs.deployment_id }} + PREVIEW_RESULT: ${{ job.status }} + PREVIEW_URL: ${{ steps.pages.outputs.pages-deployment-alias-url }} + with: + script: | + const succeeded = process.env.PREVIEW_RESULT === 'success' + await github.rest.repos.createDeploymentStatus({ + ...context.repo, + deployment_id: Number(process.env.DEPLOYMENT_ID), + state: succeeded ? 'success' : 'failure', + log_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`, + ...(process.env.PREVIEW_URL ? { environment_url: process.env.PREVIEW_URL } : {}), + }) + - name: Report the preview result on the pull-request commit if: ${{ always() }} uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 diff --git a/10-prd/_drivers/business-and-service-objectives.md b/10-prd/_drivers/business-and-service-objectives.md index 7d415ef..34d0ee7 100644 --- a/10-prd/_drivers/business-and-service-objectives.md +++ b/10-prd/_drivers/business-and-service-objectives.md @@ -1,6 +1,6 @@ # Business And Service Objectives -- business objective: provide one product that can collect information, organize it into a reusable base, and expose ways to use it later. +- business objective: help people put information to use by collecting it so people and connected tools can find and use it, and by improving collected information when that helps. - service objective: keep collection, info-base authority, organization, and application responsibilities distinct even when one service implements multiple parts. - service objective: allow extensions to add capability without forking core ownership boundaries. -- success rationale: reusable information should remain available across runtimes and downstream workflows instead of being trapped in collection-specific flows. +- success rationale: value is realized when people or connected tools can find and use collected information; it should remain available across runtimes and downstream workflows instead of being trapped in collection-specific flows. diff --git a/10-prd/_drivers/market-and-user-pressures.md b/10-prd/_drivers/market-and-user-pressures.md index 07b2cc0..70aef9f 100644 --- a/10-prd/_drivers/market-and-user-pressures.md +++ b/10-prd/_drivers/market-and-user-pressures.md @@ -1,7 +1,7 @@ # Market And User Pressures -- market pressure: information captured in external systems loses value when it cannot be collected and reused in one durable base. +- market pressure: information saved across external systems loses value when people cannot find or use it again when needed. - user pressure: people need information to be gathered automatically instead of relying on repeated manual copy or one-off retrieval. - user pressure: once collected, information must remain reusable for later retrieval, indexing, and downstream use. - user pressure: thoughts and small pieces of surrounding information should be capturable from familiar memo clients with little friction, wherever the person happens to be. -- urgency and tradeoff: the product optimizes for reusable information memory rather than source-specific ad hoc extraction. +- urgency and tradeoff: the product optimizes for putting collected information to use rather than treating capture, storage, or source-specific extraction as the outcome. diff --git a/10-prd/_drivers/operational-realities.md b/10-prd/_drivers/operational-realities.md index a887d68..ba7aa38 100644 --- a/10-prd/_drivers/operational-realities.md +++ b/10-prd/_drivers/operational-realities.md @@ -4,4 +4,4 @@ - runtime reality: a block may carry inline content or an opaque pointer to actual bytes stored elsewhere. - existing system limitation: storage-backed content access may be deferred, so consumers need one hydration contract rather than interpreting block pointers directly. - runtime reality: collection may be a tracked pull run, an event-driven record, or an extension-owned protocol request; only run-oriented collection requires a Job lifecycle. -- product boundary: an InKCre deployment is one owner context. Runtime clients are peer nodes, while users or accounts named by an external protocol remain protocol-bound projections rather than InKCre tenants. +- product boundary: an InKCre deployment is one owner context. Runtime participants are Peer nodes, while users or accounts named by an external protocol remain protocol-bound projections rather than InKCre tenants. diff --git a/10-prd/glossary.md b/10-prd/glossary.md index 05077ee..4e23ab0 100644 --- a/10-prd/glossary.md +++ b/10-prd/glossary.md @@ -52,12 +52,12 @@ - canonical business meaning: a user-facing application through which a person interacts with InKCre or a compatible product protocol. - user-visible or business lifecycle language: the app or interface a person uses. -- notes on ambiguity with framework terms: technical architecture uses `peer` for runtime nodes; product, marketing, landing, and other non-technical material may continue to say client where that is what a person experiences. +- notes on ambiguity with framework terms: use `client` only for an actual application or a protocol-native client role; it is not a product-facing synonym for an InKCre runtime Peer. ## peer - canonical business meaning: one running node that participates in a deployment around the shared info-base and may provide or consume capabilities. -- user-visible or business lifecycle language: normally hidden behind the product's clients and deployment. +- user-visible or business lifecycle language: the named runtime shown when a person manages where InKCre capabilities run. - notes on ambiguity with framework terms: peer equality describes shared authority and participation, not identical execution ability; one interaction may still have caller/provider or client/server roles. ## job diff --git a/20-product-tdd/peer-database-runtime-contract.md b/20-product-tdd/peer-database-runtime-contract.md index d8497a5..ff6442f 100644 --- a/20-product-tdd/peer-database-runtime-contract.md +++ b/20-product-tdd/peer-database-runtime-contract.md @@ -62,6 +62,19 @@ reset must converge to the same result. checked-in identifiers and is not a production-data source. Artifact-owned catalogs are reconciled independently from development seed. +## Peer Runtime Identity + +One Peer row keeps its stable identity and Human-owned display name separately from facts published +by the running application. `application_version` is the exact release version of the application +currently running that Peer. It is not a browser version, Peer protocol version, or Extension Host +SDK compatibility version. + +The application writes `application_version` when it registers and refreshes it after an upgrade. +Registration may also refresh other runtime-owned facts such as the configuration schema, but it +must not overwrite a display name that a person changed. Historical rows may have no application +version; consumers keep them usable and present the version as unknown until that Peer registers +again. + `reset-dev` requires both an explicit destructive confirmation and a database-owned development identity. It refuses production, preview, and unknown databases. diff --git a/20-product-tdd/semantic-retrieval-and-peer-capabilities.md b/20-product-tdd/semantic-retrieval-and-peer-capabilities.md index 2186e5c..0242b53 100644 --- a/20-product-tdd/semantic-retrieval-and-peer-capabilities.md +++ b/20-product-tdd/semantic-retrieval-and-peer-capabilities.md @@ -97,9 +97,9 @@ business facade - Runtime Peers are equal participants around shared database authority but may implement different executable capabilities. Caller/provider or client/server describes one interaction edge, not a fixed deployment hierarchy. -- One Peer row owns a validated full capability-advertisement snapshot and one lease expiry. - Each advertisement contains an exact capability ID plus an inbound interface whose exact - protocol ID owns its parameter schema. +- One Peer row owns its runtime application version, a validated full + capability-advertisement snapshot, and one lease expiry. Each advertisement contains an exact + capability ID plus an inbound interface whose exact protocol ID owns its parameter schema. - Discovery exposes support and Peer liveness. Readiness is internal to the business service and never becomes advertisement metadata. Lease evaluation uses database time; the lease owner chooses its TTL because always-on and scale-to-zero deployments differ. diff --git a/20-product-tdd/system-state-and-authority.md b/20-product-tdd/system-state-and-authority.md index 7cb6c02..6a967e7 100644 --- a/20-product-tdd/system-state-and-authority.md +++ b/20-product-tdd/system-state-and-authority.md @@ -65,6 +65,8 @@ Record durable ownership of authoritative state across units and distinguish it - One InKCre deployment is one owner context; the product does not currently define tenants, terminal users, or per-row user ownership. -- Technical runtime participants are Peers. User-facing applications may still be called - clients. Identities named by an external source or compatibility protocol - keep their native boundary meaning and must not silently become shared-system principals. +- Technical runtime participants are Peers and are presented as Peers wherever a person manages + their identity, configuration, liveness, or capabilities. `Client` remains valid only for an + actual application or protocol-native role. Identities named by an external source or + compatibility protocol keep their native boundary meaning and must not silently become + shared-system principals. diff --git a/website/.vitepress/config.mts b/website/.vitepress/config.mts index 02c527f..8b4bdd9 100644 --- a/website/.vitepress/config.mts +++ b/website/.vitepress/config.mts @@ -2,7 +2,7 @@ import { defineConfig, type HeadConfig } from 'vitepress' import { canonicalOrigin, defaultLanguage } from '../scripts/site-contract.mjs' const description = - 'Public documentation for InKCre, an actively developed system for reusable information.' + 'InKCre collects information from the tools you use so you can find it and put it to use.' export default defineConfig({ srcDir: 'content', @@ -48,6 +48,7 @@ export default defineConfig({ ) }, themeConfig: { + logo: '/images/inkcre-mark.svg', nav: [ { text: 'Getting Started', link: '/getting-started' }, { text: 'Developer', link: '/developer/' }, @@ -56,47 +57,64 @@ export default defineConfig({ ], sidebar: { '/': [ - { text: 'Getting Started', link: '/getting-started' }, { text: 'User Guide', items: [ - { text: 'Connect to Your Instance', link: '/guide/connect' }, - { text: 'CLI / Agent Connection', link: '/guide/connect-cli' }, - { text: 'Prepare an Extension', link: '/guide/extensions' }, - { text: 'Collect Your First Source', link: '/guide/first-source' }, - { text: 'Find What You Saved', link: '/guide/search' }, - { text: 'Schedule Collection and Indexing', link: '/guide/schedules' }, { - text: 'Connect More Sources', - link: '/guide/sources', + text: 'Getting Started', + link: '/getting-started', items: [ - { text: 'RSS and Atom', link: '/guide/sources/rss' }, - { text: 'GitHub Stars and Lists', link: '/guide/sources/github' }, - { text: 'Email over IMAP', link: '/guide/sources/mail' }, - { text: 'Telegram Inbox', link: '/guide/sources/telegram' }, - { text: 'Twitter / X Bookmarks', link: '/guide/sources/twitter' }, - { text: 'Memos-Compatible Capture', link: '/guide/sources/memos' }, + { text: 'Connect the Web App', link: '/guide/connect' }, + { text: 'Choose Your First Source', link: '/guide/first-source' }, + { text: 'Prepare an Extension', link: '/guide/extensions' }, { text: 'Run a Collection', link: '/guide/collect' }, + { text: 'Find What You Saved', link: '/guide/search' }, ], }, { - text: 'Use Your Information', + text: 'Collection', + link: '/guide/sources', + items: [ + { + text: 'Connect More Sources', + link: '/guide/sources', + items: [ + { text: 'RSS and Atom', link: '/guide/sources/rss' }, + { text: 'GitHub Stars and Lists', link: '/guide/sources/github' }, + { text: 'Email over IMAP', link: '/guide/sources/mail' }, + { text: 'Telegram Inbox', link: '/guide/sources/telegram' }, + { text: 'Twitter / X Bookmarks', link: '/guide/sources/twitter' }, + { text: 'Memos-Compatible Capture', link: '/guide/sources/memos' }, + ], + }, + { text: 'Schedule Collection', link: '/guide/schedules' }, + ], + }, + { + text: 'Organization', + items: [{ text: 'Organize Your Information', link: '/guide/organization' }], + }, + { + text: 'Application / Use', link: '/guide/daily-use', - items: [{ text: 'Sinks: ChatGPT via MCP', link: '/guide/sinks/chatgpt' }], + items: [ + { text: 'Browse and Use Your Information', link: '/guide/daily-use' }, + { text: 'CLI / Agent Connection', link: '/guide/connect-cli' }, + { text: 'ChatGPT via MCP', link: '/guide/sinks/chatgpt' }, + ], + }, + { + text: 'Self-Hosted', + link: '/self-hosted/', + items: [ + { text: 'Render and Neon', link: '/self-hosted/render-neon' }, + { text: 'Heroku and Neon', link: '/self-hosted/heroku-neon' }, + { text: 'Custom Self-Hosting', link: '/self-hosted/custom' }, + ], }, { text: 'Troubleshooting', link: '/guide/troubleshooting' }, ], }, - { - text: 'Self-Hosted', - items: [ - { text: 'Overview', link: '/self-hosted/' }, - { text: 'Getting Started', link: '/self-hosted/getting-started' }, - { text: 'Render and Neon', link: '/self-hosted/render-neon' }, - { text: 'Heroku and Neon', link: '/self-hosted/heroku-neon' }, - { text: 'Advanced', link: '/self-hosted/advanced' }, - ], - }, ], '/developer/': [ { diff --git a/website/.vitepress/theme/custom.css b/website/.vitepress/theme/custom.css index 35584b0..4b02a63 100644 --- a/website/.vitepress/theme/custom.css +++ b/website/.vitepress/theme/custom.css @@ -1,31 +1,209 @@ :root { - --vp-c-brand-1: #3f4b9a; - --vp-c-brand-2: #5261b6; - --vp-c-brand-3: #6877c7; - --vp-c-brand-soft: rgb(63 75 154 / 14%); + --vp-c-brand-1: #1f1f1f; + --vp-c-brand-2: #303030; + --vp-c-brand-3: #474747; + --vp-c-brand-soft: rgb(31 31 31 / 10%); --vp-home-hero-name-color: var(--vp-c-brand-1); --vp-font-family-base: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; + --inkcre-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; } .dark { - --vp-c-brand-1: #aeb9ff; - --vp-c-brand-2: #91a0ef; - --vp-c-brand-3: #7384d5; - --vp-c-brand-soft: rgb(145 160 239 / 16%); + --vp-c-brand-1: #e2e2e2; + --vp-c-brand-2: #c6c6c6; + --vp-c-brand-3: #ababab; + --vp-c-brand-soft: rgb(226 226 226 / 12%); } :root:root { - --vp-button-brand-bg: #5663af; - --vp-button-brand-hover-bg: #49569f; - --vp-button-brand-active-bg: #3f4b8f; + --vp-button-brand-bg: #1f1f1f; + --vp-button-brand-hover-bg: #303030; + --vp-button-brand-active-bg: #474747; +} + +.dark:root { + --vp-button-brand-bg: #e2e2e2; + --vp-button-brand-hover-bg: #c6c6c6; + --vp-button-brand-active-bg: #ababab; + --vp-button-brand-text: #1f1f1f; +} + +.VPNavBarTitle .title, +.VPHero .name { + font-family: var(--inkcre-mono); } .VPHero .name, -.VPHero .text { +.VPHero .text, +.inkcre-home-story h2, +.inkcre-home-flow h2, +.inkcre-home-start h2 { letter-spacing: -0.03em; } .VPHero .tagline { max-width: 48rem; } + +.VPButton, +.VPFeature, +.VPImage { + border-radius: 0 !important; +} + +.dark .VPNavBarTitle img, +.dark .VPHero .VPImage { + filter: invert(1); +} + +.VPFeature { + border-color: var(--vp-c-divider); + background: var(--vp-c-bg); +} + +.inkcre-home-story, +.inkcre-home-flow, +.inkcre-home-start { + max-width: 1152px; + margin: 0 auto; + padding-right: 24px; + padding-left: 24px; +} + +.inkcre-home-story, +.inkcre-home-flow { + padding-top: 64px; +} + +.inkcre-home-story { + max-width: 840px; +} + +.inkcre-home-story h2, +.inkcre-home-flow h2, +.inkcre-home-start h2 { + margin: 0 0 20px; + border: 0; + font-size: clamp(28px, 4vw, 44px); + line-height: 1.12; +} + +.inkcre-home-story > p { + color: var(--vp-c-text-2); + font-size: 18px; + line-height: 1.7; +} + +.inkcre-flow { + display: grid; + grid-template-columns: 1fr auto 1fr auto 1fr; + align-items: stretch; + margin-top: 32px; +} + +.inkcre-flow-stage { + min-height: 190px; + padding: 24px; + border: 1px solid var(--vp-c-divider); + background: var(--vp-c-bg); +} + +.inkcre-flow-stage--core { + border-color: var(--vp-c-text-1); + background: var(--vp-c-bg-soft); +} + +.inkcre-flow-stage strong { + display: block; + margin-bottom: 12px; + font-size: 20px; +} + +.inkcre-flow-stage p { + margin: 0; + color: var(--vp-c-text-2); + line-height: 1.6; +} + +.inkcre-flow-connector { + display: grid; + width: 48px; + place-items: center; + color: var(--vp-c-text-2); + font-family: var(--inkcre-mono); +} + +.inkcre-home-start { + display: flex; + align-items: end; + justify-content: space-between; + gap: 48px; + margin-top: 72px; + margin-bottom: 64px; + padding-top: 48px; + padding-bottom: 48px; + border-top: 1px solid var(--vp-c-divider); +} + +.inkcre-home-start > div { + max-width: 680px; +} + +.inkcre-home-start p:last-child { + margin-bottom: 0; + color: var(--vp-c-text-2); + font-size: 17px; +} + +.inkcre-home-link { + flex: none; + padding: 12px 0; + color: var(--vp-c-text-1); + font-family: var(--inkcre-mono); + font-weight: 600; + text-decoration: underline; + text-underline-offset: 4px; +} + +.inkcre-home-link:hover { + color: var(--vp-c-text-2); +} + +.VPHome .vp-doc > h2, +.VPHome .vp-doc > h2 ~ p { + max-width: 768px; + margin-right: auto; + margin-left: auto; +} + +@media (max-width: 767px) { + .inkcre-home-story, + .inkcre-home-flow { + padding-top: 56px; + } + + .inkcre-flow { + grid-template-columns: 1fr; + } + + .inkcre-flow-stage { + min-height: 0; + } + + .inkcre-flow-connector { + width: auto; + height: 40px; + transform: rotate(90deg); + } + + .inkcre-home-start { + display: block; + margin-top: 64px; + } + + .inkcre-home-link { + display: inline-block; + margin-top: 24px; + } +} diff --git a/website/README.md b/website/README.md index 1b8d8ec..a9792f9 100644 --- a/website/README.md +++ b/website/README.md @@ -30,36 +30,82 @@ pnpm --dir website audit --audit-level high - Only English is active until the Chinese route set is complete or the locale switch has a deliberate fallback. - `/getting-started` owns the application-level What, Why, and How introduction. -- `/self-hosted/` contains its Getting Started path, Render/Heroku quick-deployment guides, and - Advanced guide. Its Getting Started page orders the journey rather than duplicating procedures. -- `/guide/` leaf pages own reusable client, collection, retrieval, scheduling, source, daily-use, - and troubleshooting procedures. Link to these pages from any onboarding path rather than to - sections buried inside the self-hosted walkthrough. +- `/getting-started` owns a linear first-use path in the User Guide: connect the Web app, choose a + Source, prepare its Extension, collect, and retrieve a real item. These steps remain grouped under + Getting Started instead of being filed by the capabilities they happen to exercise. +- `/self-hosted/` selects Render/Heroku quick deployment or Custom Self-Hosting. It is not a second + Getting Started hierarchy. +- After Getting Started, the User Guide groups reusable procedures into Collection, Organization, + Application / Use, and Self-Hosted chapters. Info Base browsing, Agent connections, and Sinks are + Application / Use topics. An Extension may provide Source, Sink, Organization, or other behavior, + so preparing the first Extension belongs to the onboarding journey rather than Collection. - `/guide/sources` selects independent source tutorials under `/guide/sources/`; `/guide/collect` - owns shared collection and Job observation. Memos is documented separately as write-in capture. + owns shared collection and Job observation. Collection scheduling stays separate from Organization + guidance; indexing is retrieval support, not Organization. Memos is documented separately as + write-in capture. - `/developer/` separates ecosystem integration guidance under `/developer/ecosystem/` from architecture and core contribution guidance; `/about/` describes the project. - Section indexes use trailing-slash routes, such as `/developer/`. - Leaf pages use lowercase ASCII kebab-case routes without an extension, such as `/developer/architecture`. - Source ordering belongs in navigation configuration, not numeric filename prefixes. -- Published routes are compatibility contracts. Move one only with a direct permanent redirect. -- `scripts/site-contract.mjs` owns the route matrix shared by generated-output and deployment - verification. +- Once a published route has external references, treat it as a compatibility contract and move it + only with a direct permanent redirect. +- `scripts/site-contract.mjs` owns the canonical origin and locale shared by site generation and + deployment verification. Internal Markdown links target rewritten public routes and omit `.md` and `.html`. Relative links are resolved from the rewritten route, not the source file location. +## Product Language + +- Lead initial user-facing pages with the outcome and familiar objects: InKCre collects information + so people and the tools they connect can find and use it; InKCre can improve collected information + when that helps. Wording may vary with context, but it must preserve that collection and + use-centered meaning. Source independence, storage, and self-hosting are supporting properties, + not the value claim itself. +- Introduce InKCre-specific vocabulary only after the reader has a concrete workflow that needs it. + In particular, do not make `info-base`, Blocks, Relations, Peers, or capability ownership part of + the home hero or the initial Getting Started explanation. Define such terms where they help the + reader act or understand architecture. +- Keep capability boundaries precise. Collection brings information into InKCre. Organization acts + on information already collected when that improves use. Application makes information useful to + people or downstream tools. These are independent capabilities, not mandatory stages. +- Prefer a concrete way information becomes useful—finding a saved item, following a relationship, + or retrieving it from a connected tool—over phrases such as “a shared base” or “reusable + information” that name an attribute without explaining its value. +- Review meaning with a simple counterexample, not only a terminology search: a person collects one + item through a supported integration and later finds it through another connected tool without + running Organization. Initial product copy must allow that successful path, must be understandable + without internal vocabulary, and must not imply arbitrary integrations, automatic synchronization, + uniform capabilities across connected tools, or generated answers. Finding useful information is + already a successful use; the product need not complete the surrounding task automatically. + ## Page Authoring +- Give each page one primary reader, one task, and one observable completion state. An introduction + explains; a tutorial leads to a result; a guide supports a task; a reference supplies facts. Do + not make one page perform all four jobs. +- Keep one linear first-success path under Getting Started. Formal User Guide pages must remain + independently useful and should not add a generic **Next** link when no real dependency exists. +- Repeat shared context only when entering the page directly without it could cause an incorrect or + unsafe action. Link to the owning explanation instead of restating it. +- Use headings to answer a reader's question or name an action. Avoid decorative eyebrow text, + all-caps labels, and a subsection that contains only one short sentence. +- Keep commands, screenshots, results, and caveats inside the step they explain. Use a table for + comparison, not to fit prose into columns. Bold names visible in the interface; use code style for + literal values, identifiers, and commands. +- Review a changed page with its navigation entry and exit. Render at least one representative + procedure in desktop light mode and at narrow width; confirm that hidden interface variants, + lists, code, tables, screenshots, and links remain understandable. - User procedures default to client-web. Use the shared `InterfaceGuide` component with `#web` and - `#cli` slots for alternate steps on the same route; CLI instructions primarily serve Agents and - operators. The choice survives client-side navigation, not a full reload. Without JavaScript, both - sections remain readable. Keep shared prerequisites and limitations outside the slots. + `#cli` slots for alternate steps on the same route; CLI instructions primarily serve Agents. The + choice survives client-side navigation, not a full reload. Without JavaScript, both sections + remain readable. Keep shared prerequisites and limitations outside the slots. - Set `outline: false` on interface-switching pages: the default VitePress outline includes hidden slot headings. Do not expose links to invisible instructions. The site sidebar remains available. - State actual interface gaps instead of implying feature parity. Core package installation and - lexical maintenance still need CLI/operator steps; a browser wizard requires a compatible native + lexical maintenance may still need the user's Agent; a browser wizard requires a compatible native distribution as well as its Core collector. Check both against published Registry releases. - Keep exactly one H1 per page. - Add a concise page `description` in frontmatter. @@ -74,6 +120,25 @@ are resolved from the rewritten route, not the source file location. - Do not create empty pages or navigation for future User Manual, database, Extension, API, or Chinese sections. +### Web Screenshots + +- Add a screenshot when it helps the reader identify a control, confirm a saved state, or compare a + result. Keep prose authoritative; do not use screenshots as decorative substitutes for steps. +- Capture client-web in light mode at a desktop viewport. Use 1:1, 4:3, or approximately 16:9, and + crop to the application viewport rather than including the browser toolbar or desktop. Use a + mobile viewport only when the procedure specifically documents the mobile experience. +- Show the smallest useful state around the documented action. Preserve enough surrounding UI for + orientation instead of cropping to an isolated button or field. +- Use fixtures or placeholders where possible. Remove personal content and real credentials; mask + secrets before capture, and inspect the final pixels rather than relying only on the control's + intended masking behavior. +- Store client-web images under `content/public/images/client-web/` with stable, kebab-case names. + Alt text identifies the surface and visible state; the following italic caption explains what the + reader should notice or do. +- Before publishing, inspect the rendered page at desktop width, confirm that text remains legible, + and verify the image route in the exact preview deployment. Keep raw acceptance evidence in the + task packet rather than publishing browser chrome, credentials, or transient diagnostics. + Update canonical Hub truth first when a public page reveals a real product or cross-unit contract mismatch. Public-only identity, About, and presentation facts remain website-owned and do not need an artificial Hub mirror. diff --git a/website/content/en/about/index.md b/website/content/en/about/index.md index 9255b54..be540dd 100644 --- a/website/content/en/about/index.md +++ b/website/content/en/about/index.md @@ -5,16 +5,20 @@ description: The identity, purpose, values, and current stage of InKCre. # About InKCre -InKCre is an open project for making collected information durable, organized, and reusable. The -project and the public development effort share the name **InKCre**. +InKCre is an open project that helps people put information to use. It collects information from the +tools where it already lives so people and connected tools can find and use it. InKCre can also +improve collected information when that helps. The project and the public development effort share +the name **InKCre**. ## Why InKCre exists -Information is distributed across many systems. Collection alone does not preserve its value when -the result remains source-specific, difficult to connect, or unavailable to later work. +Information is distributed across many systems. Saving or collecting more of it is not enough when +the result remains tied to one source, difficult to find, or unavailable at the point of use. -InKCre exists to help information remain reusable—from collection and organization to later use and -creation. +Many knowledge tools begin with a workspace where people write and organize. InKCre begins with +information already scattered across the tools they use and focuses on helping that information +create value again. Independent Collection, Organization, and Application capabilities support that +goal; a useful item does not have to pass through every capability first. ## The name @@ -28,22 +32,12 @@ InKCre is also known in Chinese as **第三持存** (_tertiary retention_). These values guide the project's direction. They do not imply that every corresponding product or governance mechanism is already complete. -### Open source - -InKCre is developed in the open and should remain inspectable and contributable. - -### User control - -People should retain meaningful control over their information and product behavior. - -### Self-hosting - -Running InKCre on infrastructure controlled by its users is a core direction. - -### Community-driven - -The project and its ecosystem should be shaped through open participation rather than only by a -closed central team. +- **Open source:** InKCre is developed in the open and should remain inspectable and contributable. +- **User control:** people should retain meaningful control over their information and product + behavior. +- **Self-hosting:** running InKCre on infrastructure controlled by its users is a core direction. +- **Community-driven:** the project and its ecosystem should be shaped through open participation, + not only by a closed central team. ## Current stage diff --git a/website/content/en/developer/architecture.md b/website/content/en/developer/architecture.md index 3e1ae4a..3358804 100644 --- a/website/content/en/developer/architecture.md +++ b/website/content/en/developer/architecture.md @@ -1,103 +1,115 @@ --- title: Architecture -description: A shared mental model of the InKCre info-base, peer runtimes, and ecosystem surfaces. +description: + A shared mental model of the InKCre info-base, knowledge capabilities, and peer runtimes. --- # Architecture -InKCre turns collected information into reusable product memory. Its architecture separates -collection, authoritative organization, interpretation, raw-content retrieval, and downstream use so -that no single runtime or transport becomes the whole product. +InKCre is built around one reusable **info-base**. Collection brings information into it; +Organization may improve information already there; Application retrieves, navigates, or uses it. +These are independent actions over shared graph authority, not mandatory stages in a pipeline. -## Product flow +## Knowledge capabilities ```text -external systems - -> sources collect information - -> blocks and relations enter the info-base - -> resolvers interpret; storage retrieves raw content when needed - -> sinks retrieve, index, and serve downstream use +source-native input -> Collection -----------+ + | + v + Blocks + Relations + | + Organization -------------+------------- Application + improve later use obtain useful results ``` -A **source** gathers data from an external system. The **info-base** owns the persisted blocks and -relations that make information durable and reusable. A **resolver** interprets a block and its -local graph context, while **storage** retrieves raw content that is not inline in the block. A -**sink** consumes organized information for retrieval, indexing, embedding, or another downstream -workflow. +- **Collection** maps source-native information into durable Blocks and Relations. Correct source + mapping may create a graph; that does not make every collected relationship an Organization + result. +- **Organization** acts on information already in the info-base when splitting, merging, linking, + interpreting, or another change can improve later use. It may honestly make no change. +- **Application** finds, navigates, compares, or otherwise uses existing information. Lexical + indexes, embeddings, and projections support these queries but do not become graph authority or + Organization output. + +A **Resolver** derives use-facing meaning from a Block, its hydrated content, and the direct context +required by its contract. **Storage** owns actual bytes and opaque pointers. Neither silently gains +Collection or Organization authority. See the canonical [product glossary](https://github.com/InKCre/docs/blob/main/10-prd/glossary.md) -for the complete shared vocabulary. +and +[knowledge capability contract](https://github.com/InKCre/docs/blob/main/20-product-tdd/knowledge-capability-contract.md) +for the shared semantics. + +## Info-base authority + +Persisted Blocks and Relations are the shared information authority. Source-native objects, resolver +output, search indexes, embeddings, and client views may represent or accelerate parts of that +information, but none creates a parallel authoritative store merely because its native shape is +convenient. + +PostgreSQL owns shared persisted state. The admitted `inkcre` schema exposes versioned relations and +functions to authenticated Peers through native PostgreSQL or PostgREST. Direct database +participation means using that protocol—not arbitrary SQL access to internal schemas or provider +objects. + +The canonical +[peer database runtime contract](https://github.com/InKCre/docs/blob/main/20-product-tdd/peer-database-runtime-contract.md) +defines principals, protocol admission, lifecycle, readiness, and JWT claims. ## Peer runtimes, not frontend and backend tiers -`core-py`, `client-web`, and future units are peers around the same shared info-base. PostgreSQL is -authoritative for shared persisted state. `core-py` owns migrations and the executable database -lifecycle contract, but that responsibility does not make it the owner of every request path or -product behavior. +`core-py`, `client-web`, and compatible future runtimes participate as Peers around the same +info-base. `core-py` owns migrations and the executable database lifecycle contract, but it is not a +central owner of every request path or product behavior. -The web client demonstrates this topology today: its database client reads and writes through -PostgREST while other runtime behavior can use native HTTP surfaces. The durable boundary is the -admitted protocol, not a permanent frontend/backend hierarchy. +Client-web demonstrates this topology: database operations use PostgREST, while runtime-owned +capabilities may use native HTTP surfaces advertised by an online Peer. The durable boundary is the +admitted protocol and capability contract, not a permanent frontend/backend hierarchy. Read the canonical [unit topology](https://github.com/InKCre/docs/blob/main/20-product-tdd/unit-topology.md) and [state authority](https://github.com/InKCre/docs/blob/main/20-product-tdd/system-state-and-authority.md) for the cross-unit contract. -## Database protocol - -The `inkcre` PostgreSQL schema is the admitted, versioned relation and function surface for -authenticated peers. Native PostgreSQL and PostgREST expose the same admitted semantics through -different transports. - -Direct database participation therefore does **not** mean arbitrary SQL access. A usable peer must -respect the admitted schema, explicit privileges, migration and lifecycle state, protocol revision, -and coordinated compatibility rules. Administrative schemas, provider internals, and objects without -contract admission are outside the protocol. - -The canonical -[peer database runtime contract](https://github.com/InKCre/docs/blob/main/20-product-tdd/peer-database-runtime-contract.md) -defines protocol admission, principals, lifecycle, readiness, JWT claims, and portable acceptance. - ## Ecosystem surfaces {#ecosystem-surfaces} -### Database peers +### Database Peers -Database peer participation is the foundational ecosystem surface. An authenticated runtime can use -native PostgreSQL or PostgREST to operate the admitted protocol without becoming subordinate to one -central application server. - -The current contract is concrete, but a complete third-party guide for identity, privileges, -compatibility, and worked examples is still deferred. +An authenticated runtime can participate through native PostgreSQL or PostgREST while respecting the +admitted schema, privileges, protocol revision, and compatibility rules. Administrative schemas and +provider internals remain outside that surface. ### Extensions -An Extension is an installable capability that adds source, resolver, or sink behavior without -forking core ownership boundaries. Installation, client-scoped enablement, and current runtime -activity are separate states: - -- **installed**: the deployment has the package and persisted installation record; -- **enabled**: a particular client is permitted to run it; -- **running**: the current runtime has started it and applied its side effects. +An Extension packages one or more capabilities for a compatible Host. A deployment installs one +exact version; each Peer records whether it should enable that Extension. For normal operation, +**online Peer + enabled intent** means the Host is expected to run it best-effort. There is no +second durable `running` flag for users to maintain. Runtime errors and capability observations can +still show that expected activation failed. -Core supports native Python wheels with versioned Registry releases and explicit Host compatibility. -The [Source Extension tutorial](/developer/ecosystem/source-extension) covers the current Core Host -0.2 path. Its Source programming interfaces still import Core modules; the delivery Toolkit is not a -standalone Source SDK or a promise of compatibility with every future Host. +Core supports Python wheels with explicit Host compatibility. A release may also contain a browser +distribution for client-web setup or rendering. The +[Source Extension tutorial](/developer/ecosystem/source-extension) covers the current Core Host SDK +`0.3.x` path; those programming interfaces still import Core modules and are not a standalone, +permanently stable Source SDK. -### APIs +### Native HTTP and sinks -PostgREST and native HTTP implementations expose real integration surfaces. Their existence does not -by itself create a versioned public API promise. Endpoint reference, authentication examples, and -compatibility policy will be documented when a supported external contract is ready. +An Extension may expose its own HTTP protocol through its Host, and a Sink may make admitted +capabilities available to another tool. These are integration surfaces, not ownership shortcuts: +retrieval remains Application, Organization remains explicit, and transport does not redefine graph +authority. ## Boundaries worth preserving -- Sources may propose graph data; the info-base owns persisted graph insertion. -- Source, info-base, and sink responsibilities remain distinct. -- Resolver interpretation and storage retrieval remain distinct. -- Embeddings are sink-owned even when ingestion triggers their generation. -- Extension `installed`, `enabled`, and `running` states must not collapse into one flag. +- Collection, Organization, and Application remain independent actions rather than information + states or a mandatory pipeline. +- Source-authored facts remain distinguishable from Organization-authored meaning. +- Blocks and Relations remain authoritative; indexes, embeddings, projections, and caches are + derived support. +- Resolver meaning and Storage byte access remain distinct. +- Delivery owner, Host, Peer enablement, and capability owner do not collapse merely because one + first-party repository currently implements several of them. These boundaries are maintained in the canonical [product rules](https://github.com/InKCre/docs/blob/main/10-prd/behavior/rules-and-invariants.md) diff --git a/website/content/en/developer/ecosystem/index.md b/website/content/en/developer/ecosystem/index.md index 8c2d7cd..dd4eb23 100644 --- a/website/content/en/developer/ecosystem/index.md +++ b/website/content/en/developer/ecosystem/index.md @@ -5,8 +5,8 @@ description: Add integrations to InKCre without contributing to its core impleme # Ecosystem Developers -Build an integration for your own workflow or distribute it to other InKCre operators. You do not -need to contribute it to the Core repository. Start with the boundary your integration needs: +Build an integration for your own workflow or distribute it to other InKCre users. You do not need +to contribute it to the Core repository. Start with the boundary your integration needs: | Goal | Integration path | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | @@ -17,14 +17,15 @@ need to contribute it to the Core repository. Start with the boundary your integ ## What an Extension supplies -A Source fetches and maps external information. A Resolver interprets stored content and relations. -A Sink makes information useful downstream. An Extension packages one or more such capabilities for -a particular Host; not every integration needs all three or a custom browser interface. +A Source contributes Collection by mapping external information into the info-base. A Resolver +derives use-facing meaning from stored content and required context. A Sink exposes capabilities to +another tool. An Extension packages one or more capabilities for a compatible Host; not every +integration needs all three or a custom browser interface. The Python path uses a native wheel, the `inkcre.core.extensions` entry point, and an exact Registry -Release. Core installs that release, a Peer enables it, and the running Host activates its behavior. -These are separate steps. Browser code is a separate native distribution, not automatically produced -by a Python wheel. +Release. Core installs that release and a Peer records its enabled intent. An online Host then +activates the Extension best-effort; users do not maintain a second durable running flag. Browser +code is a separate distribution, not automatically produced by a Python wheel. The Source tutorial targets **Core Host SDK 0.3.x**. Its Python programming interfaces currently import Core modules; they are not an independent, universally stable Source SDK. The Extension @@ -33,13 +34,13 @@ Toolkit builds delivery metadata and preview registries; it does not run collect ## Trust and delivery An admitted Extension is trusted in-process code, not sandboxed user content. A malicious package -could access the runtime's information and credentials. Operators must review what they install; +could access the runtime's information and credentials. Users must review what they install; Registry publication is not proof of isolation. Use a separate test deployment and non-sensitive fixtures during development, with its own database and credentials. Package identity, Host compatibility, dependencies, and immutable releases are part of delivering a usable integration. Keep your own package, tests, release history, and user setup guide in your -repository. A public Registry requires its operator's namespace and publishing authorization; a -private development preview does not grant those rights. +repository. A public Registry requires a namespace and publishing authorization; a private +development preview does not grant those rights. Continue with [Build a Source Extension](/developer/ecosystem/source-extension). diff --git a/website/content/en/developer/ecosystem/source-extension.md b/website/content/en/developer/ecosystem/source-extension.md index 850f53e..4ca9421 100644 --- a/website/content/en/developer/ecosystem/source-extension.md +++ b/website/content/en/developer/ecosystem/source-extension.md @@ -81,7 +81,7 @@ namespaces = true The product coordinate (`yourname/notebook`), Python project name, and module path serve different purposes. The entry-point name and Extension's `ext_id` must agree. Declare direct dependencies; Core checks them against its existing environment and will not fetch arbitrary missing dependencies -while enabling your Extension. A new dependency may require an operator-built Core image. +while enabling your Extension. A new dependency may require a custom Core image. Save `extensions/notebook/__init__.py`: @@ -126,7 +126,7 @@ class Note(BaseModel): class Source(SourceBase[SourceConfig], config_cls=SourceConfig): - """Save changes to one operator-selected JSON document as text snapshots.""" + """Save changes to one user-selected JSON document as text snapshots.""" async def collect(self, job: JobModel, config: BaseModel) -> None: source_config = await self.get_config() @@ -165,9 +165,9 @@ indexable. This is a snapshot collector: a changed response creates another snapshot; returning to older text can create another one too. It neither reconciles a whole remote collection nor deletes earlier -snapshots. The endpoint is selected by the trusted operator, not exposed as a public URL-fetching -API. For a real service, add its authentication, bounded response handling, native identity, -pagination, rate limits, and incremental state according to that service's contract. +snapshots. The endpoint is selected by the user, not exposed as a public URL-fetching API. For a +real service, add its authentication, bounded response handling, native identity, pagination, rate +limits, and incremental state according to that service's contract. Source configuration is long-lived input, Source state remembers progress, and Job parameters/state belong to one execution. Use `collect_config_cls` for typed per-run options and @@ -223,8 +223,8 @@ public Registry. In the terminal with your CLI, inspect `inkcre-cli peer get self` and `inkcre-cli config get extension.registry`. Record the prior setting (a missing config is normal). A Peer-level `extension_registry_url` override takes precedence; use a test Peer without an override -or have its operator adjust that override. On this **isolated test instance only**, set the -deployment Registry origin, replacing the URL if Core is remote: +or adjust that override. On this **isolated test instance only**, set the deployment Registry +origin, replacing the URL if Core is remote: ```sh inkcre-cli config replace extension.registry --schema-id extension.registry.config.v1 --input-json '{"extension_registry_url":"http://127.0.0.1:8766"}' @@ -272,9 +272,9 @@ overwrite published bytes or treat disable/re-enable as Python module reload. Keep the package in your own repository. To distribute through a Registry, obtain permission for your namespace, prepare the exact release association, upload the finalized wheel, and publish the -release using the [Extension Toolkit](https://github.com/InKCre/ext-reg/tree/main/toolkit). -Operators then install your exact coordinate/version and follow your source-specific setup guide. -The static preview is a development path, not authorization to publish to `registry.inkcre.dev`. +release using the [Extension Toolkit](https://github.com/InKCre/ext-reg/tree/main/toolkit). Users +then install your exact coordinate/version and follow your source-specific setup guide. The static +preview is a development path, not authorization to publish to `registry.inkcre.dev`. For larger collectors, study the [RSS implementation](https://github.com/InKCre/core-py/tree/main/extensions/rss) for incremental diff --git a/website/content/en/developer/index.md b/website/content/en/developer/index.md index a423971..56ce6e5 100644 --- a/website/content/en/developer/index.md +++ b/website/content/en/developer/index.md @@ -38,12 +38,12 @@ This is not a promise of unrestricted database access or a complete API compatib ## Primary repositories -| Repository | Current role | Development entry | -| ----------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| [`InKCre/docs`](https://github.com/InKCre/docs) | Shared product and cross-unit documentation Hub; source of this website | [Repository README](https://github.com/InKCre/docs#readme) | -| [`InKCre/core-py`](https://github.com/InKCre/core-py) | Python core runtime, migrations, and database lifecycle authority | [Contributing guide](https://github.com/InKCre/core-py/blob/main/CONTRIBUTING.md) | -| [`InKCre/client-web`](https://github.com/InKCre/client-web) | Web client, browser-extension workspace, and shared client infrastructure | [Repository README](https://github.com/InKCre/client-web#readme) | -| [`InKCre/ui`](https://github.com/InKCre/ui) | Design system, tokens, and shared web UI packages | [Repository README](https://github.com/InKCre/ui#readme) | +| Repository | Role and development entry | +| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`InKCre/docs`](https://github.com/InKCre/docs) | Shared product and cross-unit documentation Hub; source of this website. Start with its [README](https://github.com/InKCre/docs#readme). | +| [`InKCre/core-py`](https://github.com/InKCre/core-py) | Python core runtime, migrations, and database lifecycle authority. Follow its [contributing guide](https://github.com/InKCre/core-py/blob/main/CONTRIBUTING.md). | +| [`InKCre/client-web`](https://github.com/InKCre/client-web) | Web client, browser Extensions, and shared client infrastructure. Start with its [README](https://github.com/InKCre/client-web#readme). | +| [`InKCre/ui`](https://github.com/InKCre/ui) | Design system, tokens, and shared Web UI packages. Start with its [README](https://github.com/InKCre/ui#readme). | The [InKCre GitHub organization](https://github.com/InKCre) contains prototypes and historical repositories as well. They are not all equivalent contributor entry points. diff --git a/website/content/en/getting-started.md b/website/content/en/getting-started.md index eec100f..39dfe91 100644 --- a/website/content/en/getting-started.md +++ b/website/content/en/getting-started.md @@ -6,33 +6,26 @@ description: # Getting Started -InKCre helps you turn information scattered across your tools into a collection you can return to -and use. Start here to understand the experience, then choose how you will access an instance. You -do not need to be an InKCre developer to begin. +InKCre helps you collect information scattered across your tools so you and the tools you connect +can find and use it. Start here to understand the experience and complete one useful loop. You do +not need to be an InKCre developer. ## What is InKCre? -InKCre collects information, organizes it in an **info-base**, and makes it available for retrieval -and use in other tools. Think of the info-base as your reusable collection, including connections -between pieces of information rather than only a folder of copies. +InKCre collects information from the tools where it already lives so you can find and use it in +later work. It can also improve selected information when that helps. For example, you might collect articles from RSS feeds, keep track of saved GitHub repositories, and capture messages you forward to a Telegram bot. Later, you can find an article from a phrase you -remember, follow its related information, or make it available to a trusted assistant. - -These are connected capabilities, not mandatory stages: you can collect and retrieve information -without first configuring AI organization. Extensions provide integrations with different sources -and tools; each integration has its own setup and limits. +remember, follow its related information, or use it through an assistant you connect. ## Why use it? Saving information is useful only if you can find and reuse it. An article in one app, a repository in another, and a note in a third can become difficult to bring together when you need them. -InKCre gives that information a common home without making its usefulness depend on the original -collector or a single client. You choose the sources that matter, then access the collection from -the Web app, the command line, or connected tools in your workflow. Self-hosting also lets you -choose where the instance runs and where its information is stored. +InKCre lets you collect from those sources, then find the information in the Web app or use it +through tools you connect. You choose where your self-hosted instance runs and which sources matter. Start with a concrete need—such as finding useful articles from your subscriptions—rather than connecting every source at once. One working source and a successful search are a better first @@ -42,43 +35,33 @@ milestone than a large collection you cannot yet use. ### 1. Choose how to access an instance -An **instance** stores your info-base and runs capabilities such as collection. A **client**, such -as the [Web app](https://app.inkcre.dev/settings), connects to that instance. Opening the Web app -does not create an instance for you. +An **instance** stores your collected information and runs capabilities such as collection. A +**client**, such as the [Web app](https://app.inkcre.dev/settings), connects to that instance. +Opening the Web app does not create an instance for you. -- **Run your own instance:** choose [Self-Hosted](/self-hosted/). Its - [Getting Started](/self-hosted/getting-started) guide walks through quick deployment and your - first collection. [Advanced](/self-hosted/advanced) covers manual deployment and operating it on - infrastructure you choose. -- **Already have access to an instance:** obtain connection details from the person operating it, - then [connect the Web app or your Agent](/guide/connect), [collect a source](/guide/first-source), - and [connect your everyday tools](/guide/daily-use). Skip the deployment steps. Only connect - information and tools you are authorized to use with that instance. +- **Run your own instance:** choose a quick or custom path in [Self-Hosted](/self-hosted/), then + return here. +- **Already deployed your instance:** reuse the connection details you retained, then + [connect the Web app](/guide/connect) and [choose your first Source](/guide/first-source). Its + guide identifies the Extension to prepare. Skip the deployment steps. -This guide does not assume a hosted sign-up service or separate private user accounts inside an -instance. Access arrangements and trust matter; do not treat a shared instance as an isolated -personal account. +This guide assumes one user-owned deployment, not a hosted sign-up service or multi-user account. -### 2. Collect one useful source +### 2. Choose and collect one useful source Choose [your first source](/guide/first-source); a public RSS feed is an easy starting point. Each [source guide](/guide/sources) covers its own prerequisites, Extension setup, and first collection. Once you can retrieve a known item, add personal sources one at a time, with the credentials and permissions each requires. -### 3. Find and use what you collected +### 3. Find what you collected Follow [Find What You Saved](/guide/search) to maintain the search index, search for something you -remember, and open a result. Then [Use Your Information](/guide/daily-use) to connect the Web app or -a tool you already use. These guides work independently of your deployment choice. - -AI organization and semantic retrieval are optional next steps with their own provider and -maintenance setup. InKCre does not automatically configure a daily digest or Telegram/email push -notifications: making information available in your tools is distinct from proactively sending it. +remember, and open a result. Finding a real item completes the linear Getting Started path, +independently of your deployment choice. ## Your next step If you do not have an instance yet, open [Self-Hosted](/self-hosted/) and choose a deployment path. -If you want to understand or contribute to the implementation, use the -[Developer Guide](/developer/) instead. For the project's values and direction, read -[About InKCre](/about/). +Otherwise, [connect the Web app](/guide/connect). After you find a real item, use the User Guide +chapters for collection, organization, application, and instance operation as you need them. diff --git a/website/content/en/guide/collect.md b/website/content/en/guide/collect.md index fc415cd..8333064 100644 --- a/website/content/en/guide/collect.md +++ b/website/content/en/guide/collect.md @@ -6,29 +6,30 @@ description: Execute one Source collection and distinguish its Source ID from it # Run a Collection -Start with a [connected interface](/guide/connect). Choose Web for your own setup, or CLI / Agent -for terminal instructions. +You need a [connected interface](/guide/connect) and a configured Source. diff --git a/website/content/en/guide/connect-cli.md b/website/content/en/guide/connect-cli.md index 9572698..7034c8e 100644 --- a/website/content/en/guide/connect-cli.md +++ b/website/content/en/guide/connect-cli.md @@ -5,8 +5,8 @@ description: Connect the command-line tool to an existing InKCre instance. # Connect the CLI -You need a ready Core URL and the instance's private JWT secret. Obtain them from your deployment or -its operator. Keep the secret private; it grants instance authority, not an isolated personal login. +You need a ready Core URL and the instance's private JWT secret from your deployment. Keep the +secret private; it grants full deployment authority, not a limited app session. The CLI is primarily for your trusted Agent, and also supports manual terminal use. For your own interactive setup, start with [Connect to Your Instance](/guide/connect) and choose the Web app. The @@ -37,8 +37,8 @@ CLI connects over HTTPS; it does not run another server on your computer. } ``` - Replace both values, preserving the quotes. Use the Core base URL without `/readyz`. This file - contains a credential; keep it private. + Replace both values, preserving the quotes. Use the Core base URL without an endpoint path. This + file contains a credential; keep it private. 4. From that folder, save and check the connection: @@ -53,11 +53,11 @@ CLI connects over HTTPS; it does not run another server on your computer. directory. Protect that file too. **Checkpoint:** `connection check` can read your instance. For `401`, check the secret; for a -connection failure, check the Core URL and wake `/readyz`. In later terminal sessions, reactivate -the environment before using `inkcre-cli`. +connection failure, check the Core URL and start Core from your hosting dashboard. In later terminal +sessions, reactivate the environment before using `inkcre-cli`. The [CLI reference](https://github.com/InKCre/core-py/blob/main/cli/README.md) owns command details. `--help` explains a command; `--schema` on input-taking commands shows the configuration accepted by your running instance. -Next: [Collect your first source](/guide/first-source). +Next: [Choose your first source](/guide/first-source). diff --git a/website/content/en/guide/connect.md b/website/content/en/guide/connect.md index 95fc69f..e2f890e 100644 --- a/website/content/en/guide/connect.md +++ b/website/content/en/guide/connect.md @@ -7,29 +7,40 @@ description: Use the Web app yourself, or connect a trusted Agent through the CL # Connect to Your Instance Use **client-web** for your own day-to-day setup and reading. The **CLI** is primarily an interface -for your trusted Agent, and also works for operators who prefer a terminal. You do not need to -configure every interface before starting. The selector on these guides changes the instructions, -not your instance, and keeps your choice while navigating the site. +for your trusted Agent. You do not need to configure every interface before starting. The selector +on these guides changes the instructions, not your instance, and keeps your choice while navigating +the site. -Next: [Collect Your First Source](/guide/first-source). +Next: [Choose Your First Source](/guide/first-source). diff --git a/website/content/en/guide/daily-use.md b/website/content/en/guide/daily-use.md index 8f004f7..c4529fb 100644 --- a/website/content/en/guide/daily-use.md +++ b/website/content/en/guide/daily-use.md @@ -1,25 +1,28 @@ --- -title: Use Your Information -description: Connect the Web app and everyday tools, with optional AI organization. +title: Browse and Use Your Information +description: Browse the info-base and connect it to the tools where you work. --- -# Use Your Information +# Browse and Use Your Information -Start with a working instance and [a successful search](/guide/search). Retain your Core URL, -PostgREST URL, and private JWT secret. If someone else operates the instance, ask them to authorize -your access rather than assuming you may connect a browser Peer. +Start with your instance and [a successful search](/guide/search). Retain your Core URL, PostgREST +URL, and private JWT secret. ## Read and explore in the Web app First [connect the Web app](/guide/connect). Current Settings generates and registers the browser's -own Client ID; do not manually create a Peer or reuse Core's identity. +own Peer ID; do not manually create a Peer or reuse Core's identity. 1. Open **Info Base** and search for the phrase that worked in the [search guide](/guide/search). 2. Select a result, use **View content** where supported, and explore its relationships in the graph. The list is a search surface, not every stored Block. Some rich renderers need a compatible browser Extension; an Agent can use the CLI's `get_text` to read Core-resolved text. -3. Bookmark the app. A new browser/device needs its own connection. **Export** omits the secret and - is not an info-base backup. +3. Bookmark the app. A new browser/device needs its own connection. A Settings **Export** restores + the complete browser connection, including its secret, but is not an information backup. + +![Info Base graph centered on one Block and its direct relationships](/images/client-web/info-base-graph.png) + +_Open a result's neighborhood to move from one Block to the information directly related to it._ ## Use your information from a terminal or AI tool @@ -46,17 +49,4 @@ owns the endpoint and authentication contract. These paths make your saved information available on demand. They do not configure proactive notifications or a daily briefing. -## Add AI organization when you need it - -Once collection and reading work, configure a model provider and Agent for rumination, then -explicitly reconsider a Block. Follow the -[Core organization configuration](https://github.com/InKCre/core-py/blob/main/docs/30-unit-tdd/organization.md) -for the Agent and deployment settings before using **Ruminate** or -`inkcre-cli organization ruminate BLOCK_ID`. - -Inspect the Job and graph afterward. A valid result may add nothing. Re-index after new content is -added to find it by words. Semantic search additionally needs an embedding provider/profile and -maintenance; an LLM API key alone does not enable it. Selected content leaves your instance for -configured AI providers and may incur charges. - -Next: [Troubleshooting](/guide/troubleshooting). +Use [Troubleshooting](/guide/troubleshooting) when a workflow fails. diff --git a/website/content/en/guide/extensions.md b/website/content/en/guide/extensions.md index bc70e72..0dda90e 100644 --- a/website/content/en/guide/extensions.md +++ b/website/content/en/guide/extensions.md @@ -1,45 +1,47 @@ --- title: Prepare an Extension outline: false -description: Install a collector and enable it on the client that will run it. +description: Install a collector and enable it on the Peer that will run it. --- # Prepare an Extension -Start with a [connected interface](/guide/connect). Your source guide supplies an Extension name, an -exact compatible version, and its Source type. An Extension is installed once in the deployment; -enabled clients share that version and configuration. Only install code you trust with the host's -authority. Do not change a working installation merely to match an example. +Start with a [connected interface](/guide/connect). Your source guide supplies an Extension name, +version, and Source type. An Extension is installed once in the deployment; enabled Peers share its +version and configuration. Only install code you trust with the host's authority. Do not change a +working installation merely to match an example. diff --git a/website/content/en/guide/first-source.md b/website/content/en/guide/first-source.md index 6590c23..fa73afc 100644 --- a/website/content/en/guide/first-source.md +++ b/website/content/en/guide/first-source.md @@ -1,16 +1,14 @@ --- -title: Collect Your First Source -description: Choose a source and complete your first collection and search. +title: Choose Your First Source +description: Choose one small information source for your first collection. --- -# Collect Your First Source +# Choose Your First Source Start with a working instance and a [connected Web app or Agent](/guide/connect). The guides default to Web instructions, with a CLI / Agent alternative. You do not need to connect every account at once: choose one small source with an item you will recognize. -## Choose your first source - [RSS or Atom](/guide/sources/rss) is a useful first choice because a public feed needs no account credentials. If you prefer your own saved information, start with [GitHub Stars](/guide/sources/github), [email](/guide/sources/mail), @@ -20,20 +18,23 @@ includes its own prerequisites and setup. An **Extension** supplies a collector implementation; a **Source** is one configured use of it. For example, install the RSS Extension once, then create one Source per feed. Installing it does not automatically enable it or collect anything. [Prepare the Extension](/guide/extensions) on Core, -then configure the Source in the Web app. Select the online Core client when installing a -Python-only collector; the browser does not need to run that Extension itself. +then configure the Source in the Web app. Installation does not need a Peer selection; select the +online Core Peer when enabling a Python collector. The browser does not need to run it. + +## Continue the first loop + +1. [Prepare the Extension](/guide/extensions) named by your source guide. +2. Return to that guide to create the Source. +3. [Run a Collection](/guide/collect) and wait for its Job to finish. +4. [Find What You Saved](/guide/search) and open a known item. -## Complete the first loop +![The client-web Sources page showing saved Sources and their collection actions](/images/client-web/sources-overview.png) -1. Follow your chosen source's guide to enable its Extension and create the Source. Open its details - in the Web app, or retain the returned **Source ID** when using the CLI. -2. [Run a Collection](/guide/collect) and wait for the returned **Job ID** to finish. These are - different IDs: the Source persists across runs; each Job represents one run. -3. [Find What You Saved](/guide/search): maintain the lexical index and search for a known item. -4. Only after that works, [schedule collection and indexing](/guide/schedules). +_Each row is one configured Source. Open it to inspect configuration and history, or run a manual +collection from the row._ **Done means you retrieved a real item**, not just that installation or a Job succeeded. A successful empty collection may be normal; each source guide explains what is eligible for collection. -Next: [Connect More Sources](/guide/sources), or [Use Your Information](/guide/daily-use). +After you find a real item, Getting Started is complete. diff --git a/website/content/en/guide/organization.md b/website/content/en/guide/organization.md new file mode 100644 index 0000000..bd7109a --- /dev/null +++ b/website/content/en/guide/organization.md @@ -0,0 +1,70 @@ +--- +title: Organize Your Information +outline: false +description: Improve information already collected in your InKCre instance. +--- + +# Organize Your Information + +Organization acts on information already in your info-base to make it more useful later. It can +split, merge, link, interpret, or otherwise improve that information. Collection is different: it +brings source information into the info-base and may preserve source-authored relationships while +doing so. Finding information is Application; its indexes and embeddings are derived retrieval +support, not Organization output. + +These are independent actions, not mandatory stages. You can collect and retrieve useful information +without running Organization first. + +## Before you organize + +1. Finish [one collection](/guide/collect) and [retrieve a known item](/guide/search). +2. Choose a concrete improvement, such as interpreting an image or reconsidering one Block in its + immediate context. Do not run Organization merely to make the graph look tidy. +3. Configure a compatible model provider and Agent for the exact behavior. Organization may send + selected content to that provider and may incur charges. + +The +[Core Organization guide](https://github.com/InKCre/core-py/blob/main/docs/30-unit-tdd/organization.md) +owns the current behavior and configuration contracts. A configured model alone does not schedule or +run Organization. + +## Reconsider one Block + +For one item that would benefit from additional context or connections, retain its Block ID and ask +your trusted Agent to run: + +```sh +inkcre-cli organization ruminate BLOCK_ID +``` + +The command creates a Job. Observe that Job, then inspect the Block and its neighborhood again. +Rumination is additive and best-effort: it may add ordinary Blocks and Relations, or finish without +writing when the Agent has no useful change. It does not replace or delete the original Block. + +## Run Organization automatically + +Some Organization behaviors select their own candidates, including media interpretation. They use +ordinary typed Jobs and do not receive a schedule automatically. First use your Agent to verify that +the chosen behavior is configured and available on the online Core Peer. Run it once and inspect its +Job and graph effects before creating a Cron. + +For example, a configured media-interpreting instance can run this parameterless Job type: + +```sh +inkcre-cli job create --type core.organization.media_interpretation.v1 --input-json '{"parameters":{}}' +``` + +A finished Job is not a blanket quality verdict. One candidate may produce no useful output, and +already committed effects remain when another candidate fails. Review representative results before +choosing a schedule suitable for your information and provider budget. For example, after the manual +media Job works, schedule the same behavior once each night: + +```sh +inkcre-cli cron create --job-type core.organization.media_interpretation.v1 --input-json '{"schedule":"0 3 * * *","job_parameters":{}}' +``` + +Inspect the returned Cron and its later Jobs. Use a different frequency only when your incoming +media volume and provider budget justify it. + +Search indexes and embeddings are retrieval support, not Organization output. Maintain them through +[Find What You Saved](/guide/search#keep-search-current). diff --git a/website/content/en/guide/schedules.md b/website/content/en/guide/schedules.md index d4430dc..b24bd48 100644 --- a/website/content/en/guide/schedules.md +++ b/website/content/en/guide/schedules.md @@ -1,19 +1,16 @@ --- -title: Schedule Collection and Indexing +title: Schedule Collection outline: false -description: Keep sources and search indexes current with explicit schedules. +description: Keep information sources current with explicit collection schedules. --- -# Schedule Collection and Indexing +# Schedule Collection -Start with a [connected interface](/guide/connect). Choose Web for your own setup, or CLI / Agent -for terminal instructions. +You need a [connected interface](/guide/connect) and a Source with one successful manual run. diff --git a/website/content/en/guide/search.md b/website/content/en/guide/search.md index ac3e18f..aa5b817 100644 --- a/website/content/en/guide/search.md +++ b/website/content/en/guide/search.md @@ -6,44 +6,46 @@ description: Index collected information and retrieve it by remembered words. # Find What You Saved -Start with a [connected interface](/guide/connect). Choose Web for your own setup, or CLI / Agent -for terminal instructions. +You need a [connected interface](/guide/connect) and at least one completed collection. + +## Keep search current + +Lexical maintenance makes collected information searchable by remembered words. It does not collect +information or author graph meaning. Ask your trusted Agent to check whether the instance already +has a maintenance schedule; create only one if it does not: + +```sh +inkcre-cli cron create --job-type core.feature_retrieval.lexical.maintain.v1 --input-json '{"schedule":"*/10 * * * *","job_parameters":{}}' +``` + +This schedule runs every ten minutes while Core is available. Inspect the returned Cron and its +`last_job`; maintenance processes a bounded batch, and the Job carries its own result and +diagnostics. Sleeping hosts miss occurrences and do not automatically catch up. Pause future runs +without deleting the Cron record with: + +```sh +inkcre-cli cron disable ID +``` + +Replace `ID` with the Cron ID. Pausing index maintenance does not stop collection or Organization +and does not remove stored information. Semantic retrieval has its own configuration and +maintenance; an LLM key or lexical schedule does not enable it. diff --git a/website/content/en/guide/sinks/chatgpt.md b/website/content/en/guide/sinks/chatgpt.md index 902c1c3..3ccf662 100644 --- a/website/content/en/guide/sinks/chatgpt.md +++ b/website/content/en/guide/sinks/chatgpt.md @@ -21,8 +21,7 @@ operate; it does not have to run beside Core. Keep it running whenever ChatGPT n ## Before you start - Have a working instance and complete [a known-item search](/guide/search) first. Retain its Core - URL and private JWT secret. If someone else operates the instance, ask them to perform the Sink - setup rather than requesting their administrator credentials. + URL and private JWT secret. - Install the CLI environment from [Connect the CLI](/guide/connect-cli). The setup example below uses its installed Python dependencies because the CLI does not yet have a `sink` command. - Confirm that your ChatGPT account/workspace permits developer-mode MCP connections and that you @@ -84,11 +83,11 @@ with httpx.Client(timeout=30, headers={"Authorization": f"Bearer {token}"}) as c print(f"MCP endpoint: {core_url}/sinks/{sink_id}/mcp") ``` -Save the printed Sink ID and MCP endpoint. Enabling applies to the Core Peer you contacted. Do not -append this path to the PostgREST URL or to `/readyz`. +Save the printed Sink ID and MCP endpoint. Enabling applies to the Core Peer you contacted. Append +the Sink path to the Core base URL, not the PostgREST URL. If a request times out or enabling fails, inspect the existing Sink before repeating creation: the -first write may already have succeeded. The operator can use authenticated `GET /sinks` and +first write may already have succeeded. You can use authenticated `GET /sinks` and `POST /sinks/{id}/enable` with the same short-lived Bearer JWT pattern. Do not publish a Sink management response; it can contain configuration credentials. The authoritative API and lifecycle details are in @@ -136,11 +135,10 @@ Replace the tunnel ID and server URL before running. The environment value conta are needed because discovery/probes and regular calls reach the protected Sink separately. See the [tunnel configuration reference](https://github.com/openai/tunnel-client/blob/master/docs/configuration.md). -In another terminal, run `curl --fail http://127.0.0.1:8080/readyz`; continue when it returns -HTTP 200. The local diagnostics UI is at `http://127.0.0.1:8080/ui`. If port 8080 is occupied, -choose another loopback port in the command and both URLs. Keep this listener local; do not expose -its UI as the MCP endpoint. Core must remain reachable too, including when hosted on a sleeping -plan. +Wait until the tunnel client reports that it is ready. Its local diagnostics UI is available from +the loopback address shown in its output. If port 8080 is occupied, choose another loopback port in +the command. Keep this listener local; do not expose its UI as the MCP endpoint. Core must remain +reachable too, including when hosted on a sleeping plan. ## 4. Add the connection in ChatGPT @@ -191,6 +189,6 @@ results. Refresh the ChatGPT connection after changing server tool metadata, then test in a new chat. Stopping `tunnel-client` interrupts this tunnel path; closing its terminal or sleeping its host does the same. Remove the connection from ChatGPT when no longer needed. To revoke the endpoint itself, -the operator can call authenticated `POST /sinks/{id}/disable`; disable before deleting a Sink. For -a leaked PAT, rotate the Sink config and update the tunnel environment before restarting it. Never -disable PAT authentication just to make discovery pass. +you can call authenticated `POST /sinks/{id}/disable`; disable before deleting a Sink. For a leaked +PAT, rotate the Sink config and update the tunnel environment before restarting it. Never disable +PAT authentication just to make discovery pass. diff --git a/website/content/en/guide/sources.md b/website/content/en/guide/sources.md index 0c39c3f..1be2fc8 100644 --- a/website/content/en/guide/sources.md +++ b/website/content/en/guide/sources.md @@ -12,7 +12,7 @@ first. Choose **Web app** for your own setup or **CLI / Agent** for terminal instructions. The choice follows you between guide pages. Shared prerequisites and source limitations apply to both. The [Extension guide](/guide/extensions) distinguishes browser setup from Core installation and calls -out operations that still need an operator or Agent. +out operations that still need your Agent. | What you want to collect | Setup guide | What you need | | -------------------------------------------- | ------------------------------------------------ | ---------------------------------------- | @@ -43,5 +43,3 @@ An Extension can add a Source without becoming part of the Core repository. If y want to connect another service, follow [Build a Source Extension](/developer/ecosystem/source-extension). That is the ecosystem developer path; changing InKCre itself has a separate [contributor guide](/developer/contributing). - -Next: [Use Your Information](/guide/daily-use). diff --git a/website/content/en/guide/sources/github.md b/website/content/en/guide/sources/github.md index f7e96ef..fd0cef4 100644 --- a/website/content/en/guide/sources/github.md +++ b/website/content/en/guide/sources/github.md @@ -6,26 +6,21 @@ description: Connect your GitHub saves to InKCre. # GitHub Stars and Lists -Start with a [connected interface](/guide/connect). Choose Web for your own setup, or CLI / Agent -for terminal instructions. +You need a [connected interface](/guide/connect) and a GitHub personal access token.