documents

package
v0.9.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 23, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package documents indexes managed local markdown roots for model-facing rediscovery, browse, search, and section retrieval.

The operator-facing contract for what counts as a managed document root lives in docs/understanding/document-roots.md. Keep that document in sync with behavioral changes here, especially when changing how config paths become indexed corpora or how the documents capability is meant to differ from raw file access.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types 

type Backlink struct {
	Ref              string   `json:"ref"`
	Path             string   `json:"path"`
	Title            string   `json:"title"`
	ModifiedAt       string   `json:"modified_at"`
	Targets          []string `json:"targets,omitempty"`
	TargetsTruncated bool     `json:"targets_truncated,omitempty"`
}

Backlink is one indexed document that links to another document.

type BrowseArgs 

type BrowseArgs struct {
	Root       string `json:"root"`
	PathPrefix string `json:"path_prefix,omitempty"`
	Limit      int    `json:"limit,omitempty"`
}

BrowseArgs requests one rooted browse step through an indexed corpus.

type BrowseDirectory 

type BrowseDirectory struct {
	Name          string `json:"name"`
	PathPrefix    string `json:"path_prefix"`
	DocumentCount int    `json:"document_count"`
}

BrowseDirectory describes one child directory in a rooted browse view.

type BrowseResult 

type BrowseResult struct {
	Root        string            `json:"root"`
	PathPrefix  string            `json:"path_prefix,omitempty"`
	Directories []BrowseDirectory `json:"directories,omitempty"`
	Documents   []DocumentSummary `json:"documents,omitempty"`
}

BrowseResult is the rooted "phone tree" view for one root/prefix.

type CopyArgs 

type CopyArgs struct {
	Ref            string `json:"ref"`
	DestinationRef string `json:"destination_ref"`
	Overwrite      bool   `json:"overwrite,omitempty"`
}

CopyArgs duplicates one managed document at a new semantic ref.

type CopyResult 

type CopyResult struct {
	Action      string   `json:"action"`
	FromRef     string   `json:"from_ref"`
	ToRef       string   `json:"to_ref"`
	FromRoot    string   `json:"from_root"`
	FromPath    string   `json:"from_path"`
	ToRoot      string   `json:"to_root"`
	ToPath      string   `json:"to_path"`
	Overwrote   bool     `json:"overwrote,omitempty"`
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	UpdatedAt   string   `json:"updated_at,omitempty"`
	ModifiedAt  string   `json:"modified_at"`
	WordCount   int      `json:"word_count"`
	SizeBytes   int64    `json:"size_bytes"`
}

CopyResult summarizes one managed document copy.

type DeleteArgs 

type DeleteArgs struct {
	Ref string `json:"ref"`
}

DeleteArgs removes one managed document by semantic ref.

type DeleteResult 

type DeleteResult struct {
	Action      string   `json:"action"`
	DeletedRef  string   `json:"deleted_ref"`
	Root        string   `json:"root"`
	Path        string   `json:"path"`
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	UpdatedAt   string   `json:"updated_at,omitempty"`
	ModifiedAt  string   `json:"modified_at"`
	WordCount   int      `json:"word_count"`
	SizeBytes   int64    `json:"size_bytes"`
}

DeleteResult summarizes one managed document deletion. 

type DocumentLink struct {
	Target string `json:"target"`
	Kind   string `json:"kind"`
	Ref    string `json:"ref,omitempty"`
	Title  string `json:"title,omitempty"`
	URL    string `json:"url,omitempty"`
	Anchor string `json:"anchor,omitempty"`
}

DocumentLink is one outgoing link projected from an indexed document.

type DocumentRecord 

type DocumentRecord struct {
	Root        string              `json:"root"`
	Ref         string              `json:"ref"`
	Path        string              `json:"path"`
	Title       string              `json:"title"`
	Description string              `json:"description,omitempty"`
	Tags        []string            `json:"tags,omitempty"`
	Frontmatter map[string][]string `json:"frontmatter,omitempty"`
	Body        string              `json:"body"`
	Outline     []Section           `json:"outline,omitempty"`
	ModifiedAt  string              `json:"modified_at"`
	WordCount   int                 `json:"word_count"`
	SizeBytes   int64               `json:"size_bytes"`
}

DocumentRecord is the full model-facing view of one managed document.

type DocumentSummary 

type DocumentSummary struct {
	Root        string              `json:"root"`
	Ref         string              `json:"ref"`
	Path        string              `json:"path"`
	Title       string              `json:"title"`
	Summary     string              `json:"summary,omitempty"`
	Tags        []string            `json:"tags,omitempty"`
	Frontmatter map[string][]string `json:"frontmatter,omitempty"`
	ModifiedAt  string              `json:"modified_at"`
	WordCount   int                 `json:"word_count"`
}

DocumentSummary is the compact search/browse view of a document.

type EditArgs 

type EditArgs struct {
	Ref         string              `json:"ref"`
	Mode        string              `json:"mode"`
	Content     string              `json:"content,omitempty"`
	Section     string              `json:"section,omitempty"`
	Heading     string              `json:"heading,omitempty"`
	Level       int                 `json:"level,omitempty"`
	Title       string              `json:"title,omitempty"`
	Description string              `json:"description,omitempty"`
	Tags        []string            `json:"tags,omitempty"`
	Frontmatter map[string][]string `json:"frontmatter,omitempty"`
}

EditArgs updates part of a managed document without leaving the semantic document abstraction.

type JournalUpdateArgs 

type JournalUpdateArgs struct {
	Ref          string              `json:"ref"`
	Entry        string              `json:"entry"`
	Window       string              `json:"window,omitempty"`
	MaxWindows   int                 `json:"max_windows,omitempty"`
	HeadingLevel int                 `json:"heading_level,omitempty"`
	Title        string              `json:"title,omitempty"`
	Description  string              `json:"description,omitempty"`
	Tags         []string            `json:"tags,omitempty"`
	Frontmatter  map[string][]string `json:"frontmatter,omitempty"`
}

JournalUpdateArgs appends a timestamped note into a rolling window journal document while keeping window headings and timestamps stable.

type LinksArgs 

type LinksArgs struct {
	Ref              string `json:"ref"`
	Mode             string `json:"mode,omitempty"`
	Limit            int    `json:"limit,omitempty"`
	PerBacklinkLimit int    `json:"per_backlink_limit,omitempty"`
}

LinksArgs requests outgoing links, backlinks, or both for one document.

type LinksResult 

type LinksResult struct {
	Ref                string         `json:"ref"`
	Mode               string         `json:"mode"`
	Limit              int            `json:"limit,omitempty"`
	PerBacklinkLimit   int            `json:"per_backlink_limit,omitempty"`
	Outgoing           []DocumentLink `json:"outgoing,omitempty"`
	OutgoingTruncated  bool           `json:"outgoing_truncated,omitempty"`
	Backlinks          []Backlink     `json:"backlinks,omitempty"`
	BacklinksTruncated bool           `json:"backlinks_truncated,omitempty"`
}

LinksResult is the outgoing/backlink view for one indexed document.

type MoveArgs 

type MoveArgs struct {
	Ref            string `json:"ref"`
	DestinationRef string `json:"destination_ref"`
	Overwrite      bool   `json:"overwrite,omitempty"`
}

MoveArgs relocates one managed document to a new semantic ref.

type MoveResult 

type MoveResult struct {
	Action      string   `json:"action"`
	FromRef     string   `json:"from_ref"`
	ToRef       string   `json:"to_ref"`
	FromRoot    string   `json:"from_root"`
	FromPath    string   `json:"from_path"`
	ToRoot      string   `json:"to_root"`
	ToPath      string   `json:"to_path"`
	Overwrote   bool     `json:"overwrote,omitempty"`
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	UpdatedAt   string   `json:"updated_at,omitempty"`
	ModifiedAt  string   `json:"modified_at"`
	WordCount   int      `json:"word_count"`
	SizeBytes   int64    `json:"size_bytes"`
}

MoveResult summarizes one managed document move/rename.

type MutationResult 

type MutationResult struct {
	Action      string   `json:"action"`
	Ref         string   `json:"ref"`
	Root        string   `json:"root"`
	Path        string   `json:"path"`
	Existed     bool     `json:"existed"`
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	CreatedAt   string   `json:"created_at,omitempty"`
	UpdatedAt   string   `json:"updated_at,omitempty"`
	ModifiedAt  string   `json:"modified_at"`
	WordCount   int      `json:"word_count"`
	SizeBytes   int64    `json:"size_bytes"`
	Section     string   `json:"section,omitempty"`
	Window      string   `json:"window,omitempty"`
}

MutationResult summarizes one managed document write/edit.

type RefArgs 

type RefArgs struct {
	Ref string `json:"ref"`
}

RefArgs identifies one managed document by canonical semantic ref.

type RootDocumentHint 

type RootDocumentHint struct {
	Ref        string `json:"ref"`
	Path       string `json:"path"`
	Title      string `json:"title"`
	ModifiedAt string `json:"modified_at"`
}

RootDocumentHint is a compact example document attached to a root summary.

type RootSummary 

type RootSummary struct {
	Root            string             `json:"root"`
	Path            string             `json:"-"`
	DocumentCount   int                `json:"document_count"`
	TotalSizeBytes  int64              `json:"total_size_bytes"`
	TotalWordCount  int                `json:"total_word_count"`
	LastModifiedAt  string             `json:"last_modified_at,omitempty"`
	TopTags         []string           `json:"top_tags,omitempty"`
	TopDirectories  []BrowseDirectory  `json:"top_directories,omitempty"`
	RecentDocuments []RootDocumentHint `json:"recent_documents,omitempty"`
}

RootSummary describes one indexed document root.

type SearchArgs 

type SearchArgs struct {
	Root            string              `json:"root,omitempty"`
	PathPrefix      string              `json:"path_prefix,omitempty"`
	Query           string              `json:"query,omitempty"`
	Tags            []string            `json:"tags,omitempty"`
	Frontmatter     map[string][]string `json:"frontmatter,omitempty"`
	FrontmatterKeys []string            `json:"frontmatter_keys,omitempty"`
	ModifiedAfter   string              `json:"modified_after,omitempty"`
	ModifiedBefore  string              `json:"modified_before,omitempty"`
	Limit           int                 `json:"limit,omitempty"`
}

SearchArgs requests structured document search over indexed roots.

type SearchQuery 

type SearchQuery struct {
	Root            string              `json:"root,omitempty"`
	PathPrefix      string              `json:"path_prefix,omitempty"`
	Query           string              `json:"query,omitempty"`
	Tags            []string            `json:"tags,omitempty"`
	Frontmatter     map[string][]string `json:"frontmatter,omitempty"`
	FrontmatterKeys []string            `json:"frontmatter_keys,omitempty"`
	ModifiedAfter   *time.Time          `json:"-"`
	ModifiedBefore  *time.Time          `json:"-"`
	Limit           int                 `json:"limit,omitempty"`
}

SearchQuery filters document search results.

type Section 

type Section struct {
	Heading   string `json:"heading"`
	Slug      string `json:"slug"`
	Level     int    `json:"level"`
	StartLine int    `json:"start_line"`
	EndLine   int    `json:"end_line"`
	Content   string `json:"content,omitempty"`
}

Section captures one heading-defined region in a markdown document.

type SectionArgs 

type SectionArgs struct {
	Ref     string `json:"ref"`
	Section string `json:"section,omitempty"`
}

SectionArgs selects one document section by ref and optional heading.

type SectionTransferArgs 

type SectionTransferArgs struct {
	Ref                string `json:"ref"`
	Section            string `json:"section"`
	DestinationRef     string `json:"destination_ref"`
	DestinationSection string `json:"destination_section,omitempty"`
	DestinationLevel   int    `json:"destination_level,omitempty"`
}

SectionTransferArgs copies or moves one section into another managed doc.

type SectionTransferResult 

type SectionTransferResult struct {
	Action             string   `json:"action"`
	SourceRef          string   `json:"source_ref"`
	SourceRoot         string   `json:"source_root"`
	SourcePath         string   `json:"source_path"`
	SourceSection      string   `json:"source_section"`
	DestinationRef     string   `json:"destination_ref"`
	DestinationRoot    string   `json:"destination_root"`
	DestinationPath    string   `json:"destination_path"`
	DestinationSection string   `json:"destination_section"`
	DestinationLevel   int      `json:"destination_level"`
	DestinationExisted bool     `json:"destination_existed"`
	Title              string   `json:"title"`
	Description        string   `json:"description,omitempty"`
	Tags               []string `json:"tags,omitempty"`
	CreatedAt          string   `json:"created_at,omitempty"`
	UpdatedAt          string   `json:"updated_at,omitempty"`
	ModifiedAt         string   `json:"modified_at"`
	WordCount          int      `json:"word_count"`
	SizeBytes          int64    `json:"size_bytes"`
}

SectionTransferResult summarizes one section-level copy or move.

type Store 

type Store struct {
	// contains filtered or unexported fields
}

Store indexes managed markdown roots into the primary Thane SQLite DB.

func NewStore 

func NewStore(db *sql.DB, roots map[string]string, logger *slog.Logger) (*Store, error)

NewStore creates a document index store backed by db.

func (*Store) Browse 

func (s *Store) Browse(ctx context.Context, root, prefix string, limit int) (*BrowseResult, error)

Browse returns the immediate child directories and documents for a rooted prefix.

func (*Store) Copy 

func (s *Store) Copy(ctx context.Context, args CopyArgs) (*CopyResult, error)

func (*Store) CopySection 

func (s *Store) CopySection(ctx context.Context, args SectionTransferArgs) (*SectionTransferResult, error)

func (*Store) Delete 

func (s *Store) Delete(ctx context.Context, args DeleteArgs) (*DeleteResult, error)

func (*Store) Edit 

func (s *Store) Edit(ctx context.Context, args EditArgs) (*MutationResult, error)

func (*Store) JournalUpdate 

func (s *Store) JournalUpdate(ctx context.Context, args JournalUpdateArgs) (*MutationResult, error)
func (s *Store) Links(ctx context.Context, ref string, mode string, limit int, perBacklinkLimit int) (*LinksResult, error)

Links returns outgoing links, backlinks, or both for one indexed document.

func (*Store) Move 

func (s *Store) Move(ctx context.Context, args MoveArgs) (*MoveResult, error)

func (*Store) MoveSection 

func (s *Store) MoveSection(ctx context.Context, args SectionTransferArgs) (*SectionTransferResult, error)

func (*Store) Outline 

func (s *Store) Outline(ctx context.Context, ref string) ([]Section, error)

Outline returns the heading tree for a document ref.

func (*Store) Read 

func (s *Store) Read(ctx context.Context, ref string) (*DocumentRecord, error)

func (*Store) Refresh 

func (s *Store) Refresh(ctx context.Context) error

Refresh incrementally refreshes all indexed roots.

func (*Store) Roots 

func (s *Store) Roots(ctx context.Context) ([]RootSummary, error)

Roots returns the current indexed root summaries.

func (*Store) RunRefresher 

func (s *Store) RunRefresher(ctx context.Context)

RunRefresher keeps the index warm in the background using the store's refresh interval. Errors are logged and retried on the next tick.

func (*Store) Search 

func (s *Store) Search(ctx context.Context, q SearchQuery) ([]DocumentSummary, error)

Search returns matching documents, sorted by relevance and recency.

func (*Store) Section 

func (s *Store) Section(ctx context.Context, ref string, selector string) (*Section, error)

Section returns one section by heading text or slug. An empty selector returns the whole document.

func (*Store) Values 

func (s *Store) Values(ctx context.Context, root, key string, limit int) ([]ValueCount, error)

Values returns observed frontmatter values for one key.

func (*Store) Write 

func (s *Store) Write(ctx context.Context, args WriteArgs) (*MutationResult, error)

type Tools 

type Tools struct {
	// contains filtered or unexported fields
}

Tools exposes model-facing document navigation tools.

func NewTools 

func NewTools(store *Store) *Tools

NewTools creates a document tool surface.

func (*Tools) Browse 

func (t *Tools) Browse(ctx context.Context, args BrowseArgs) (string, error)

Browse returns one rooted browse step through an indexed corpus.

func (*Tools) Copy 

func (t *Tools) Copy(ctx context.Context, args CopyArgs) (string, error)

Copy clones one managed document to a new semantic ref.

func (*Tools) CopySection 

func (t *Tools) CopySection(ctx context.Context, args SectionTransferArgs) (string, error)

CopySection copies one section into another managed document.

func (*Tools) Delete 

func (t *Tools) Delete(ctx context.Context, args DeleteArgs) (string, error)

Delete removes one managed document.

func (*Tools) Edit 

func (t *Tools) Edit(ctx context.Context, args EditArgs) (string, error)

Edit applies one structured edit to a managed document.

func (*Tools) JournalUpdate 

func (t *Tools) JournalUpdate(ctx context.Context, args JournalUpdateArgs) (string, error)

JournalUpdate appends one journal-window entry to a managed document. 

func (t *Tools) Links(ctx context.Context, args LinksArgs) (string, error)

Links returns outgoing links, backlinks, or both for one indexed document.

func (*Tools) Move 

func (t *Tools) Move(ctx context.Context, args MoveArgs) (string, error)

Move relocates one managed document to a new semantic ref.

func (*Tools) MoveSection 

func (t *Tools) MoveSection(ctx context.Context, args SectionTransferArgs) (string, error)

MoveSection moves one section into another managed document.

func (*Tools) Outline 

func (t *Tools) Outline(ctx context.Context, args RefArgs) (string, error)

Outline returns the heading tree for one indexed document.

func (*Tools) Read 

func (t *Tools) Read(ctx context.Context, args RefArgs) (string, error)

Read returns one indexed document payload.

func (*Tools) Roots 

func (t *Tools) Roots(ctx context.Context) (string, error)

Roots returns summaries of the indexed document roots.

func (*Tools) Search 

func (t *Tools) Search(ctx context.Context, args SearchArgs) (string, error)

Search returns compact summaries for documents matching the structured filters.

func (*Tools) Section 

func (t *Tools) Section(ctx context.Context, args SectionArgs) (string, error)

Section returns one named section, or the whole body when no selector is given.

func (*Tools) Values 

func (t *Tools) Values(ctx context.Context, args ValuesArgs) (string, error)

Values returns observed frontmatter values for one key.

func (*Tools) Write 

func (t *Tools) Write(ctx context.Context, args WriteArgs) (string, error)

Write creates or replaces one managed document.

type ValueCount 

type ValueCount struct {
	Value string `json:"value"`
	Count int    `json:"count"`
}

ValueCount counts observed frontmatter values.

type ValuesArgs 

type ValuesArgs struct {
	Root  string `json:"root,omitempty"`
	Key   string `json:"key"`
	Limit int    `json:"limit,omitempty"`
}

ValuesArgs requests observed values for one frontmatter key.

type WriteArgs 

type WriteArgs struct {
	Ref          string              `json:"ref"`
	Title        string              `json:"title,omitempty"`
	Description  string              `json:"description,omitempty"`
	Tags         []string            `json:"tags,omitempty"`
	Frontmatter  map[string][]string `json:"frontmatter,omitempty"`
	Body         *string             `json:"body,omitempty"`
	JournalEntry string              `json:"journal_entry,omitempty"`
}

WriteArgs creates or replaces a whole managed document.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.