Import System

Import and sync documentation and templates from external sources.

Overview

The Import System allows you to:

Import docs and templates from Git repositories, npm packages, or local folders
Keep imports synced with their sources
Share patterns and conventions across multiple projects
Reference imported content with @doc/imports/<name>/<path>

Quick Start

bash

# Import from GitHub
knowns import github:knowns-dev/templates --name templates

# List all imports
knowns import list

# Sync to get updates
knowns import sync

# Reference imported docs
# @doc/imports/templates/patterns/component

Source Types

Git Repositories

bash

# GitHub shorthand
knowns import github:user/repo --name my-patterns

# GitLab shorthand
knowns import gitlab:user/repo --name patterns

# Full URL (any Git host)
knowns import https://github.com/org/knowledge-base.git --name kb

# Specific branch or tag
knowns import github:org/templates --ref main --name templates
knowns import github:org/templates --ref v1.0.0 --name templates-v1

NPM Packages

bash

# Latest version
knowns import npm:@myorg/patterns --name patterns

# Specific version
knowns import npm:@myorg/patterns --ref ^1.0.0 --name patterns

# Exact version
knowns import npm:@myorg/patterns --ref 1.2.3 --name patterns

Local Folders

bash

# Copy files
knowns import ./shared-docs --name shared

# Symlink (changes reflect immediately)
knowns import ./shared-docs --name shared --link

# Relative to home
knowns import ~/company/patterns --name company

CLI Commands

`knowns import add`

Add a new import. Shorthand: knowns import <source>.

bash

knowns import add <source> [options]
knowns import <source> [options]  # shorthand

Option	Description
`-n, --name <name>`	Custom name for the import
`-t, --type <type>`	Force source type: `git`, `npm`, `local`
`-r, --ref <ref>`	Git branch/tag or npm version
`--include <patterns...>`	Include only matching files (glob patterns)
`--exclude <patterns...>`	Exclude matching files (glob patterns)
`--link`	Symlink local imports instead of copying
`-f, --force`	Overwrite existing import
`--dry-run`	Preview without writing files
`--plain`	Plain text output (for AI)

Examples:

bash

# Import only markdown docs
knowns import github:org/repo --name docs --include "**/*.md"

# Exclude tests
knowns import github:org/repo --name patterns --exclude "**/*.test.*"

# Preview what would be imported
knowns import github:org/repo --name preview --dry-run

`knowns import list`

List all configured imports with their status.

bash

knowns import list [options]

Option	Description
`--plain`	Plain text output (for AI)

Output includes:

Import name and source
Last sync date
Number of files
Sync status

`knowns import sync`

Update imports from their sources.

bash

knowns import sync [name] [options]

Option	Description
`-f, --force`	Overwrite locally modified files
`--dry-run`	Preview changes without applying
`--plain`	Plain text output (for AI)

Examples:

bash

# Sync all imports
knowns import sync

# Sync specific import
knowns import sync patterns

# Preview sync changes
knowns import sync --dry-run

# Force sync (overwrite local changes)
knowns import sync patterns --force

`knowns import remove`

Remove an import configuration.

bash

knowns import remove <name> [options]

Option	Description
`--delete`	Also delete the imported files
`--plain`	Plain text output (for AI)

Examples:

bash

# Remove config only (keep files)
knowns import remove old-patterns

# Remove config and files
knowns import remove old-patterns --delete

Import Structure

When you import content, it's organized as:

.knowns/
├── imports.json              # Import configurations
├── docs/
│   └── imports/
│       ├── patterns/         # Import named "patterns"
│       │   ├── auth.md
│       │   └── api.md
│       └── templates/        # Import named "templates"
│           └── component.md
└── templates/
    └── patterns/             # Templates from "patterns" import
        └── react-component/

`imports.json`

Stores import metadata:

JSON

{
  "patterns": {
    "source": "github:myorg/patterns",
    "type": "git",
    "ref": "main",
    "lastSync": "2025-01-25T10:30:00Z",
    "files": 15
  }
}

Referencing Imported Content

In Tasks

bash

knowns task create "Add auth" \
  -d "Implement auth following @doc/imports/patterns/auth"

In Documentation

Markdown

# API Guidelines

See our shared patterns: @doc/imports/patterns/api

Related: @doc/imports/templates/rest-endpoint

In Templates

Link imported documentation in _template.yaml:

YAML

description: "API endpoint generator"
doc: "imports/patterns/api"  # References imported doc

Workflows

Team Pattern Library

Share patterns across all team projects:

bash

# In each project
knowns import github:myorg/patterns --name patterns

# Keep updated
knowns import sync patterns

Monorepo Shared Docs

Share docs between packages in a monorepo:

bash

# In packages/app
knowns import ../../shared/docs --name shared --link

# Changes in shared/docs reflect immediately

Versioned Templates

Use specific versions of templates:

bash

# Production: stable version
knowns import npm:@myorg/templates --ref ^1.0.0 --name templates

# Development: latest
knowns import npm:@myorg/templates --ref latest --name templates-dev

Best Practices

1. Use Meaningful Names

bash

# Good: descriptive names
knowns import github:org/api-patterns --name api-patterns
knowns import github:org/ui-components --name ui-components

# Avoid: generic names
knowns import github:org/stuff --name stuff

2. Pin Versions for Stability

bash

# Production: pin to specific version
knowns import npm:@org/patterns --ref 1.2.3 --name patterns

# Development: allow minor updates
knowns import npm:@org/patterns --ref ^1.2.0 --name patterns

3. Use Include/Exclude Filters

Import only what you need:

bash

# Only docs, no tests or examples
knowns import github:org/repo \
  --name patterns \
  --include "docs/**/*.md" \
  --exclude "**/*.test.*"

4. Sync Regularly

Add to your workflow:

bash

# Before starting work
knowns import sync

# Or automate in CI/CD
knowns import sync --force

5. Preview Before Importing

Always preview first:

bash

# See what would be imported
knowns import github:org/large-repo --name test --dry-run

# Then import
knowns import github:org/large-repo --name patterns

Troubleshooting

Import Failed

bash

# Check source is accessible
git ls-remote https://github.com/org/repo

# For npm, check package exists
npm view @org/package

# Try with verbose output
knowns import github:org/repo --name test --plain

Sync Conflicts

When local files were modified:

bash

# Preview conflicts
knowns import sync patterns --dry-run

# Force overwrite local changes
knowns import sync patterns --force

# Or backup and re-import
knowns import remove patterns
knowns import github:org/patterns --name patterns

Large Imports

For large repositories:

bash

# Filter to specific folders
knowns import github:org/large-repo \
  --name docs \
  --include "docs/**/*"

# Or specific file types
knowns import github:org/repo \
  --name patterns \
  --include "**/*.md"

Auto sync

Knowns dùng knowns sync và knowns update để giữ generated artifacts đồng bộ với binary và project config.

Sync được gì

instruction files
skills
MCP config
platform-specific config
git integration
semantic setup và indexing

Lệnh

bash

knowns sync
knowns sync --skills
knowns sync --instructions
knowns update

Legacy

Project cũ vẫn dùng .agent/skills → Knowns tiếp tục sync để giữ tương thích, có thể in warning.