Refactor layout

.github/copilot-instructions.md

@@ -1,3 +1,43 @@
+## MonaDocs — AI coding agent instructions
+
+This short guide highlights repository-specific facts an AI agent needs to be productive working on the MonaDocs Docusaurus v3 site.
+
+### Quick facts (how to run)
+- Node: >= 20 (see `package.json` "engines").
+- Install: `yarn`
+- Dev server: `yarn start` (Docusaurus hot reload, port 3000)
+- Build: `yarn build` → artifacts in `build/`
+- Preview: `yarn serve`
+- Deploy: `USE_SSH=true; yarn deploy` (Docusaurus GitHub Pages preset)
+
+### Architecture & important files
+- Docusaurus config: `docusaurus.config.js` — controls navbar, footer, editUrl (points to `dev` by default), color mode, and presets.
+- Docs content: `docs/` — grouped into subfolders (e.g., `projects/`, `technologies/`). Each folder MAY contain `_category_.json` for metadata.
+- Sidebar generator: `sidebars.js` — programmatic sidebar produced from top-level folders. If you add a folder, the sidebar is auto-included by `TOP_FOLDERS` order.
+- Blog: `blog/` — MD/MDX with YAML frontmatter; authors in `blog/authors.yml`.
+- Components/UI: `src/components/*` (examples: `HomepageFeatures`, `Portfolio`, `TechStack`) and global styles in `src/css/custom.css`.
+- Static assets: `static/img/` for global images; doc-local images can live in `docs/<section>/img/` and be referenced as `./img/foo.png`.
+
+### Project-specific conventions (do this here)
+- Sidebar: Prefer adding `_category_.json` inside a docs subfolder for label/description overrides; `sidebars.js` reads these and generates categories.
+- Doc file ids: `sidebars.js` expects `folder/filename` ids (it prefers `index.md`/`index.mdx` for directory indexes).
+- Config edits: `docusaurus.config.js` runs in Node — do not reference `window`/DOM. Use `editUrl` when you want "edit this page" links to point to a specific branch (currently `dev`).
+
+### Examples (use these when making changes)
+- Add a doc: create `docs/<section>/new-doc.md`, add `_category_.json` if you need a custom label, then ensure `TOP_FOLDERS` in `sidebars.js` includes the folder if you want it surfaced.
+- Add a blog post: `blog/YYYY-MM-DD-title.md` with YAML frontmatter: `title`, `tags`, `authors` — add new authors in `blog/authors.yml`.
+- Edit homepage features: modify `src/components/HomepageFeatures/index.js` and the corresponding `styles.module.css`, then run `yarn start` to preview.
+
+### Build & validation notes
+- No CI is configured in the repo; validate changes locally with `yarn build && yarn serve` and inspect `build/`.
+- Tests: package.json provides a `test` script (`node --test scripts`) — check `scripts/` for test files if you need unit-style checks.
+
+### Watch-outs and gotchas
+- `sidebars.js` is intentionally dynamic: it expects certain folder structure and will generate indexes. If you need manual ordering beyond what it provides, edit `sidebars.js` directly.
+- Docusaurus config is evaluated by Node — avoid client-only code inside `docusaurus.config.js` or `sidebars.js`.
+- The `editUrl` in config points at the `dev` branch — update it if your PRs target a different base branch.
+
+If any part of this is incomplete or you'd like more examples (e.g., how components are wired into MDX), tell me which area to expand and I'll iterate.
 ## MonaDocs AI Coding Agent Instructions
 
 This guide enables AI coding agents to work productively in the MonaDocs Docusaurus v3 documentation site. It summarizes essential architecture, workflows, and conventions unique to this codebase.

.gitkeep

@@ -0,0 +1 @@
+This repository now prefers `index.mdx` for the Repositories page; `docs/repositories/index.md` was removed as it's legacy.

docs/technologies/convex/guide-advanced.md

@@ -0,0 +1,63 @@
+---
+title: Convex — Advanced Guide
+---
+
+# Convex — Advanced Guide
+
+This guide provides step-by-step advanced patterns for developing, testing, and deploying Convex-backed applications. It complements the reference material in `index.md` with examples and recipes.
+
+## Local development workflow
+
+- Start a local Convex dev server:
+
+```bash
+convex dev
+```
+
+- Seed a small dataset using a script to speed iterative testing:
+
+```js
+// scripts/seed.js
+import { ConvexHttpClient } from "convex/client";
+const client = new ConvexHttpClient(process.env.CONVEX_URL);
+await client.mutation("seeds/createSampleData", { count: 50 });
+```
+
+## Recommended project layout
+
+- `src/functions/` - server functions and triggers
+- `src/collections/` - data model and index declarations
+- `src/client/` - client wrappers and helpers
+
+## CI integration (example)
+
+- Run `convex deploy` to a staging project on successful build, then run smoke tests against the staging URL.
+
+```yaml
+jobs:
+  deploy-staging:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Convex CLI
+        run: npm install -g convex
+      - name: Deploy to Convex (staging)
+        run: convex deploy --project staging --message "CI deploy"
+```
+
+## Indexing recipe
+
+- Add indexes for common query filters and sort orders; measure query plans for hot paths.
+
+## Migration and data export
+
+- Use Convex export utilities or periodic snapshots to external storage for backups and migration.
+
+## Troubleshooting
+
+- Logs: use `convex logs` or the dashboard logs to trace function errors.
+- Rate limits: implement exponential backoff and jitter on retries.
+
+## Further reading
+
+- [Convex docs](https://convex.dev/docs)

docs/technologies/docker-compose/advanced.md

@@ -0,0 +1,29 @@
+---
+title: Docker Compose — Advanced Patterns
+---
+
+## Docker Compose — Advanced Patterns
+
+This guide covers advanced Docker Compose usage for development and CI: profiles, healthchecks, buildx integration and CI cleanup.
+
+### Use override files for local dev
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
+```
+
+### Healthchecks and `depends_on`
+
+Define `healthcheck` for stateful services and depend on `service_healthy` where appropriate.
+
+### Buildx cache in CI
+
+Use Buildx to persist cache in registry between CI runs. See `index.md` for example commands.
+
+### CI cleanup
+
+Always run a final cleanup step to remove volumes and containers:
+
+```bash
+docker compose down --volumes --remove-orphans
+```

docs/technologies/github-actions/advanced.md

@@ -0,0 +1,26 @@
+---
+title: GitHub Actions — Advanced Workflows
+---
+
+## GitHub Actions — Advanced Workflows
+
+This document contains reusable workflow patterns: caching, matrix builds, buildx and OIDC authentication examples.
+
+### Reusable workflow example
+
+```yaml
+name: CI Template
+on: [workflow_call]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ inputs.node-version }}
+```
+
+### Buildx multi-arch snippet
+
+See `docs/technologies/docker-compose/advanced.md` for related buildx notes.

docs/technologies/typescript/index.md

@@ -22,3 +22,81 @@ TypeScript is a superset of JavaScript that adds optional static typing. It help
 - [TypeScript Official Docs](https://www.typescriptlang.org/docs/)
 
 If you previously referenced `/docs/tecnologias/typescript`, the Portuguese content remains under that path — this English page is a compatibility stub to ensure internal links to `/docs/technologies/typescript` resolve correctly.
+
+## Advanced configuration and commands
+
+### Recommended `tsconfig.json` snippets
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./.tsbuildinfo",
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### Useful `tsc` commands
+
+- Type check without emitting: `npx tsc --noEmit`
+- Build with project references: `npx tsc -b`
+- Watch incremental changes: `npx tsc -w --preserveWatchOutput`
+
+### Project references (monorepo)
+
+- Split large codebases using `composite` projects and `references` to enable fast, incremental builds.
+
+`tsconfig.build.json` in package A
+
+```json
+{
+  "compilerOptions": { "composite": true, "outDir": "lib" },
+  "references": []
+}
+```
+
+Then in the root `tsconfig.json` use `references` to link packages.
+
+### Path aliases and bundler coordination
+
+- Use `baseUrl` and `paths` in `tsconfig.json` and wire the same aliases into your bundler (Vite, webpack) and test runner to avoid import resolution mismatches.
+
+### Linting & formatting
+
+- Use ESLint with `@typescript-eslint` parser and rules. Example minimal `.eslintrc.json`:
+
+```json
+{
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "extends": ["eslint:recommended","plugin:@typescript-eslint/recommended"],
+  "rules": { "@typescript-eslint/explicit-module-boundary-types": "off" }
+}
+```
+
+### Migration tips (JS → TS)
+
+- Start with `allowJs` + `checkJs` to progressively add type checking.
+- Introduce `strict` mode incrementally by enabling `strict` once most code is typed.
+- Use `unknown` instead of `any` for safer runtime validation points.
+
+## Team & DX recommendations
+
+- Standardize Node/TS versions using `.nvmrc` or `engines` in `package.json`.
+- Add `tsc --noEmit` to pre-commit or CI gates to prevent type-unsafe merges.
+- Provide a shared `types/` package in monorepos for cross-package types and interfaces.
+
+## Resources
+
+- TypeScript docs: https://www.typescriptlang.org/docs/
+

docusaurus.config.js

@@ -10,11 +10,12 @@ import {themes as prismThemes} from 'prism-react-renderer';
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
-  title: 'MonaDocs',
+  title: 'Docs @Monynha Softwares',
   tagline: 'Central Documentation Hub for Monynha Softwares',
   // Use an SVG favicon for crisp rendering on modern browsers
   // If you need .ico for legacy support, add `static/img/favicon.ico` and update this line.
-  favicon: 'img/favicon.svg',
+  // Updated to use Monynha-branded favicon
+  favicon: 'img/favicon-monynha.svg',
 
   // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future
   future: {

package.json

@@ -10,6 +10,7 @@
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
+    "favicon:generate": "node scripts/generate-favicons.js",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "test": "node --test scripts"
@@ -26,6 +27,9 @@
   "devDependencies": {
     "@docusaurus/module-type-aliases": "3.9.2",
     "@docusaurus/types": "3.9.2"
+  ,
+    "sharp": "^0.32.0",
+    "png-to-ico": "^1.1.0"
   },
   "browserslist": {
     "production": [

scripts/generate-favicons.js

@@ -0,0 +1,40 @@
+const fs = require('fs');
+const path = require('path');
+const sharp = require('sharp');
+const pngToIco = require('png-to-ico');
+
+async function generate() {
+  const src = path.join(__dirname, '..', 'static', 'img', 'favicon-monynha.svg');
+  const out16 = path.join(__dirname, '..', 'static', 'img', 'favicon-monynha-16.png');
+  const out32 = path.join(__dirname, '..', 'static', 'img', 'favicon-monynha-32.png');
+  const outIco = path.join(__dirname, '..', 'static', 'img', 'favicon-monynha.ico');
+
+  if (!fs.existsSync(src)) {
+    console.error('Source SVG not found:', src);
+    process.exit(1);
+  }
+
+  try {
+    // Generate PNGs
+    await sharp(src)
+      .resize(32, 32)
+      .png({ quality: 90 })
+      .toFile(out32);
+
+    await sharp(src)
+      .resize(16, 16)
+      .png({ quality: 90 })
+      .toFile(out16);
+
+    // Generate ICO from PNGs
+    const icoBuffer = await pngToIco([out16, out32]);
+    fs.writeFileSync(outIco, icoBuffer);
+
+    console.log('Favicons generated:', out16, out32, outIco);
+  } catch (err) {
+    console.error('Failed to generate favicons:', err);
+    process.exit(1);
+  }
+}
+
+generate();

sidebars.js

@@ -21,16 +21,38 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const DOCS_DIR = path.join(__dirname, 'docs');
 
+// Friendly overrides for some category labels shown in the sidebar.
+/** @type {{[key:string]: string}} */
+const LABEL_OVERRIDES = {
+  projects: 'Projects',
+  repositories: 'Repositories',
+  technologies: 'Technologies & Stack',
+  guidelines: 'Guidelines & Standards',
+  identity: 'Visual Identity & UI Components',
+  contribution: 'Contribution & Governance',
+  architecture: 'Architecture',
+};
+
+/**
+ * Read optional `_category_.json` metadata for a docs folder.
+ * @param {string} dir
+ */
 function readCategoryMeta(dir) {
   try {
     const p = path.join(DOCS_DIR, dir, '_category_.json');
     if (fs.existsSync(p)) return JSON.parse(fs.readFileSync(p, 'utf8'));
   } catch (e) {
     // ignore
   }
-  return { label: dir.replace(/-/g, ' ').replace(/\b\w/g, (s) => s.toUpperCase()) };
+  const defaultLabel = dir.replace(/-/g, ' ').replace(/\b\w/g, (s) => s.toUpperCase());
+  return { label: LABEL_OVERRIDES[dir] || defaultLabel };
 }
 
+/**
+ * List docs in a directory and normalize to sidebar ids.
+ * @param {string} dir
+ * @returns {string[]}
+ */
 function listDocsInDir(dir) {
   const base = path.join(DOCS_DIR, dir);
   if (!fs.existsSync(base)) return [];
@@ -54,6 +76,11 @@ function listDocsInDir(dir) {
       }
     }
   }
+  // dedupe items (avoid duplicates when both index.md and index.mdx exist)
+  const uniqueItems = Array.from(new Set(items));
+  // replace items with unique list
+  items.length = 0;
+  uniqueItems.forEach((i) => items.push(i));
   // deterministic ordering: index first, then alpha
   items.sort((a, b) => {
     if (a.endsWith('/index') && !b.endsWith('/index')) return -1;
@@ -74,6 +101,7 @@ const TOP_FOLDERS = [
   'architecture',
 ];
 
+/** @type {any[]} */
 const tutorialSidebar = ['intro'];
 
 for (const folder of TOP_FOLDERS) {

src/components/HomepageFeatures/index.js

@@ -39,7 +39,8 @@ function Feature({Svg, title, description}) {
   return (
     <div className={clsx('col col--4')}>
       <div className="text--center">
-        <Svg className={styles.featureSvg} role="img" />
+        {/* Provide accessible label for decorative/illustrative SVGs */}
+        <Svg className={styles.featureSvg} role="img" aria-label={title} />
       </div>
       <div className="text--center padding-horiz--md">
         <Heading as="h3">{title}</Heading>