Seeded repo with intent and a cool extension.

INTENT.md

@@ -0,0 +1,511 @@
+# INTENT
+
+## Project Name
+
+**can-you-assist**
+
+Short name / command name:
+
+**cya**
+
+---
+
+## Purpose
+
+`can-you-assist` exists to provide a command-line assistant interface for getting practical work done in the console with the help of large language models.
+
+The project aims to make LLM-based assistance available directly where many technical users already work: in shells, repositories, local filesystems, notes, scripts, logs, and project directories.
+
+Instead of requiring users to remember every option, flag, subcommand, file format, or tool-specific convention, `cya` should allow users to express intent in natural language and receive useful, context-aware help for command-line tasks.
+
+The guiding idea is simple:
+
+> Let the user ask for help at the console, let available LLM infrastructure provide the reasoning, and keep the memory, history, preferences, and adaptation under the user’s control.
+
+---
+
+## Primary Utility
+
+`cya` provides a command-line tool that helps users interact with their local working environment through LLM-supported assistance.
+
+It should support tasks such as:
+
+- understanding files, folders, repositories, notes, and project structures;
+- generating, explaining, improving, or transforming shell commands;
+- assisting with code repository inspection and maintenance;
+- helping with file-based workflows;
+- summarizing and navigating textual content;
+- providing context-aware hints without requiring users to remember detailed command syntax;
+- adapting to user preferences, workflows, aliases, conventions, and recurring patterns over time.
+
+The tool should act as a practical helper for console-based work, not as a replacement for the shell, editor, version control system, or specialized CLI tools.
+
+---
+
+## Core Motivation
+
+Modern command-line environments are powerful but cognitively expensive.
+
+Users often know what they want to achieve but do not remember:
+
+- the exact command;
+- the right flags;
+- the safest invocation;
+- the expected file format;
+- the best tool for the job;
+- the local project conventions;
+- the accumulated context from previous related work.
+
+LLM-based tools can help with this, but many existing systems centralize memory, history, adaptation, and workflow knowledge inside vendor-controlled applications.
+
+`cya` should provide a user-controlled alternative:
+
+- the user chooses or configures the available LLM backend;
+- interaction history remains inspectable and portable;
+- preferences and learned patterns are stored under user control;
+- project-specific context can be managed locally;
+- the tool can integrate with different LLM infrastructures instead of being locked to one provider.
+
+---
+
+## Intended Users
+
+`cya` is primarily intended for users who work frequently in a terminal and want lightweight LLM assistance without leaving their local workflow.
+
+Important user groups include:
+
+- software developers;
+- technical writers;
+- repository maintainers;
+- system operators;
+- power users managing file-based notes and knowledge spaces;
+- users working with many command-line tools but not wanting to memorize all details;
+- users who want LLM assistance while keeping memory and adaptation portable and transparent.
+
+---
+
+## Primary Use Cases
+
+### 1. Command Assistance
+
+The user describes what they want to do, and `cya` suggests an appropriate command or sequence of commands.
+
+Examples:
+
+```bash
+cya "find all markdown files modified this week"
+cya "show me the git branches that are already merged"
+cya "compress this folder but exclude node_modules"
+````
+
+The goal is not merely command generation, but safe, explainable, context-aware assistance.
+
+---
+
+### 2. Filesystem and Content Interaction
+
+`cya` should help users work with local files and directories.
+
+Examples:
+
+```bash
+cya "summarize the notes in this folder"
+cya "find files that look like project plans"
+cya "extract todos from these markdown files"
+cya "compare these two config files"
+```
+
+The tool should be especially useful for text-heavy local workspaces such as code repositories, markdown notes, documentation trees, logs, and exported knowledge bases.
+
+---
+
+### 3. Code Repository Assistance
+
+`cya` should help users inspect, understand, and work with code repositories.
+
+Examples:
+
+```bash
+cya "what does this repo do?"
+cya "where is the CLI entry point?"
+cya "find likely places where authentication is handled"
+cya "summarize recent changes"
+cya "suggest a safe first refactoring step"
+```
+
+The project should support repository-aware context discovery without assuming one fixed project structure or language ecosystem.
+
+---
+
+### 4. Local Notes and Knowledge Work
+
+`cya` should help users interact with file-based notes, project journals, markdown documents, and knowledge collections.
+
+Examples:
+
+```bash
+cya "collect open decisions from these notes"
+cya "turn this rough note into a project outline"
+cya "find related notes about deployment"
+cya "summarize what I worked on in this directory"
+```
+
+This use case is important because many users maintain valuable context in local text files rather than in centralized SaaS tools.
+
+---
+
+### 5. Personalized Console Helper
+
+`cya` should adapt to the user’s habits over time.
+
+It should be able to remember things such as:
+
+* preferred command styles;
+* preferred editors;
+* shell conventions;
+* repository conventions;
+* naming preferences;
+* common project types;
+* preferred explanation depth;
+* safety preferences;
+* recurring workflows.
+
+This adaptation should be implemented through user-controlled memory rather than opaque vendor-side personalization.
+
+---
+
+## Relationship to `llm-connect`
+
+`cya` should use **llm-connect** as the abstraction layer for accessing LLM capabilities.
+
+The purpose of this relationship is to keep `cya` independent from any single LLM provider, application, API, or runtime.
+
+`llm-connect` should provide the connectivity layer for:
+
+* selecting available LLM backends;
+* sending prompts and context;
+* receiving completions or structured responses;
+* supporting different providers or local models;
+* allowing users to configure their own LLM infrastructure.
+
+`cya` should not hard-code one privileged LLM vendor as its conceptual foundation.
+
+Instead:
+
+> `cya` asks for assistance; `llm-connect` determines how available LLM infrastructure is reached.
+
+---
+
+## Relationship to `phase-memory`
+
+`cya` should use **phase-memory** to provide memory, history, preferences, and adaptation under user control.
+
+The purpose of this relationship is to separate assistant behavior from opaque application-managed memory.
+
+`phase-memory` should support:
+
+* storing interaction history;
+* managing user preferences;
+* capturing recurring workflows;
+* maintaining project-specific memory;
+* distinguishing global, local, temporary, and contextual memory;
+* allowing users to inspect, modify, export, reset, or delete memory.
+
+This is a core design principle:
+
+> The user’s working memory should belong to the user, not to a vendor-owned assistant interface.
+
+`cya` should therefore treat memory as a local or user-controlled capability, not as an invisible feature hidden behind a hosted product.
+
+---
+
+## Design Principles
+
+### Console-Native
+
+`cya` should feel natural in a terminal environment.
+
+It should work well with:
+
+* shell pipelines;
+* current working directory context;
+* local files;
+* environment variables;
+* git repositories;
+* scripts;
+* standard input and output;
+* human-readable text;
+* machine-readable output where useful.
+
+---
+
+### User-Controlled
+
+The user should remain in control of:
+
+* which LLM backend is used;
+* what context is sent;
+* what history is stored;
+* what preferences are remembered;
+* what project memory exists;
+* when potentially destructive actions are executed.
+
+`cya` should assist, not take over.
+
+---
+
+### Explainable and Inspectable
+
+When `cya` suggests commands or actions, it should be possible to inspect what it is doing.
+
+Important behaviors should be explainable:
+
+* why a command was suggested;
+* what files are being read;
+* what context is being used;
+* what memory influenced the answer;
+* what risks may exist;
+* what assumptions were made.
+
+---
+
+### Safe by Default
+
+`cya` should avoid dangerous automatic execution.
+
+Potentially destructive operations should require explicit user confirmation.
+
+Examples include:
+
+* deleting files;
+* overwriting files;
+* force-pushing git branches;
+* changing permissions;
+* running network-affecting commands;
+* executing generated scripts;
+* modifying many files at once.
+
+The tool should prefer preview, explanation, and confirmation over blind execution.
+
+---
+
+### Backend-Agnostic
+
+`cya` should not be tied to one assistant product.
+
+It should be able to use different LLM infrastructures through `llm-connect`, including:
+
+* hosted LLM APIs;
+* local models;
+* CLI-based LLM tools;
+* organization-provided endpoints;
+* future agentic runtimes.
+
+The command-line interface should remain stable even if the underlying LLM infrastructure changes.
+
+---
+
+### Memory-Aware but Not Memory-Dependent
+
+`cya` should become more useful through memory, but it should not require memory to function.
+
+A first-time user should be able to use it immediately.
+
+A long-time user should benefit from accumulated context, preferences, and workflow knowledge.
+
+---
+
+## Conceptual Architecture
+
+At a conceptual level, `cya` consists of the following responsibilities:
+
+### 1. CLI Interface
+
+The command-line entry point used by the user.
+
+Responsible for:
+
+* parsing user input;
+* identifying command modes;
+* handling stdin/stdout;
+* resolving current directory context;
+* presenting results;
+* asking for confirmation where needed.
+
+---
+
+### 2. Context Collector
+
+Responsible for gathering relevant local context.
+
+Possible sources include:
+
+* current working directory;
+* selected files;
+* git status;
+* repository metadata;
+* configuration files;
+* piped input;
+* recent command history, where available and permitted;
+* explicit user-provided context.
+
+The context collector should be conservative and transparent.
+
+---
+
+### 3. Assistance Orchestrator
+
+Responsible for turning user intent and collected context into a structured assistance request.
+
+It decides:
+
+* what kind of help is being requested;
+* what context is relevant;
+* whether memory should be consulted;
+* whether the answer should be a command, explanation, patch, summary, or plan;
+* whether safety checks are needed.
+
+---
+
+### 4. LLM Access Layer
+
+Provided through `llm-connect`.
+
+Responsible for:
+
+* communicating with the selected LLM backend;
+* abstracting provider differences;
+* supporting configuration of available models and endpoints.
+
+---
+
+### 5. Memory Layer
+
+Provided through `phase-memory`.
+
+Responsible for:
+
+* user preferences;
+* project-specific memory;
+* interaction history;
+* workflow adaptation;
+* reusable patterns;
+* inspectable assistant state.
+
+---
+
+### 6. Safety and Confirmation Layer
+
+Responsible for identifying risky actions and enforcing confirmation flows.
+
+This layer should help prevent accidental damage caused by generated commands or misunderstood instructions.
+
+---
+
+## Expected Repository Role
+
+This repository should contain the implementation and documentation for the `cya` command-line tool.
+
+It should define:
+
+* the CLI behavior;
+* configuration model;
+* integration points with `llm-connect`;
+* integration points with `phase-memory`;
+* prompt and context-handling conventions;
+* safety rules;
+* user-facing documentation;
+* examples and workflows;
+* tests for core command behavior.
+
+---
+
+## Out of Scope
+
+The project should not initially aim to become:
+
+* a full IDE;
+* a full agentic coding environment;
+* a vendor-specific LLM client;
+* a replacement for Claude Code, Codex, shell tools, git, editors, or package managers;
+* a centralized SaaS memory platform;
+* an autonomous system that freely modifies the filesystem without confirmation;
+* a general-purpose chatbot detached from console work.
+
+`cya` may overlap with existing LLM console tools, but its intended differentiator is user-controlled, console-native assistance with portable memory and backend-agnostic LLM access.
+
+---
+
+## Initial Scope
+
+The initial version should focus on a small but useful command-line assistant loop.
+
+A reasonable first scope includes:
+
+* a `cya` command that accepts natural-language requests;
+* current-directory awareness;
+* optional file input;
+* optional stdin input;
+* basic command suggestion;
+* basic explanation mode;
+* safe preview-first behavior;
+* integration with `llm-connect`;
+* simple integration with `phase-memory` for preferences and history;
+* configuration file support;
+* clear documentation of what context is sent to the LLM.
+
+Example commands:
+
+```bash
+cya "what does this repo do?"
+cya "suggest a command to find large files"
+cya explain "tar -czf archive.tar.gz ./docs"
+cya files "summarize these markdown files" README.md docs/*.md
+cat error.log | cya "what is going wrong here?"
+```
+
+---
+
+## Long-Term Direction
+
+Over time, `cya` may evolve into a personalized command-line assistant substrate.
+
+Possible future capabilities include:
+
+* project-specific assistant profiles;
+* reusable workflow recipes;
+* local command learning;
+* shell integration;
+* repository indexing;
+* structured task execution plans;
+* safe patch generation;
+* memory inspection and editing commands;
+* team-shared memory packs;
+* domain-specific helper plugins;
+* integration with agentic coding tools;
+* support for multiple concurrent LLM backends;
+* transparent context and cost reporting.
+
+The long-term ambition is not to create yet another closed assistant interface, but to provide a small, powerful, user-controlled bridge between local work and available LLM intelligence.
+
+---
+
+## Success Criteria
+
+The project is successful if users can:
+
+* get useful command-line help without remembering tool details;
+* work more effectively with local files, notes, and repositories;
+* choose their own LLM backend;
+* inspect and control what context is used;
+* preserve their own history and preferences;
+* adapt the assistant to their workflows over time;
+* avoid vendor lock-in for assistant memory and personalization;
+* safely use LLM assistance in real console workflows.
+
+---
+
+## Mission Statement
+
+`can-you-assist` gives users a console-native, backend-agnostic LLM helper that understands local work, remembers under user control, and helps get things done without requiring command-line trivia to be kept in human memory.
+

README.md

@@ -1,3 +1,3 @@
-# repo-seed
-
-A git repository template to bootstrap coulomb projects from.
+Cya provides a console-native, backend-agnostic LLM helper that understands local work, 
+remembers, is under user control, and helps get things done without requiring command-line 
+trivia to be kept in human memory.