shallok 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shallok Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# Shallok (`shallok`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> AI-Powered, Versioned Localization Tool for Developers & AI Coding Agents.
+
+Shallok is a developer tool and AI agent skill system that enables developers and AI coding agents (Antigravity, Cursor, Claude Code, GitHub Copilot) to add, configure, extract, translate, and maintain localization across existing codebases.
+
+## Features
+
+- **AST-Based Extraction**: Deterministic AST parsing (Babel) safely extracts user-facing text and attributes into stable semantic keys.
+- **Agent-Native Translation**: **Zero external API keys required**. AI coding agents translate missing and stale keys directly with natural cultural fluency.
+- **AI-Enriched Semantic Context**: Context notes are enriched by AI agents and strictly preserved across extractions.
+- **Per-Key Versioning & Content Hashing**: SHA-256 content hashes detect source modifications and mark translations stale on a granular, per-key basis.
+- **Framework Adapters**:
+  - **React**: `react-i18next` with `src/i18n.ts`
+  - **Next.js**: `next-intl` (App Router `routing.ts`, `request.ts`, `middleware.ts`)
+  - **Expo / React Native**: `expo-localization` + `i18next` with native device locale detection
+  - **Astro**: `astro:i18n` with dynamic message compilation
+- **Placeholder & Integrity Validation**: Validates 0 missing keys, 0 stale versions, and 0 corrupted placeholder tokens (`{count}`, `{name}`).
+
+---
+
+## Quickstart
+
+### 1. Developer CLI Quickstart
+Run in any React, Next.js, Expo, or Astro project:
+```bash
+npx shallok init
+```
+This command automatically:
+1. Analyzes project architecture, detected framework, and router.
+2. Scaffolds `localization.json`, `localization_base/`, `messages/`, and framework files.
+3. Installs `shallok` into `devDependencies` using your project's package manager.
+4. Installs AI agent skills directly into `.agents/skills/` and `skills/`.
+
+### 2. Direct AI Agent Skill Usage
+Copy any of the skills from `skills/` into your AI agent's skills directory (e.g. `.agents/skills/`), then tell your agent:
+> *"Add localization to this application with Kannada and Hindi"*
+
+The agent automatically verifies `shallok` is present, installs it if needed, and executes the complete 6-phase localization workflow.
+
+---
+
+## CLI Commands
+
+```bash
+# Analyze project architecture
+shallok analyze --json
+
+# Initialize configuration and framework files
+shallok init --source en --locales kn,hi,fr --framework react --yes
+
+# Extract strings and preview changes
+shallok extract --dry-run
+shallok extract
+
+# Apply AST transformations to source code
+shallok extract --apply
+
+# Check localization status
+shallok status
+
+# Compile runtime message bundles
+shallok build
+
+# Validate placeholder and catalog integrity
+shallok validate
+```
+
+---
+
+## License
+
+MIT © Shallok Contributors